Overview

Meet Runbooks!

Runbooks are interactive markdown documents with a first-class experience for generating files based on custom configurations, running customizable scripts or commands, and validating assertions about their local system or infrastructure.

Runbooks are open source and free to use.

How are Runbooks useful?

DevOps and Platform Engineers are often the “expertise bottlenecks” when it comes to enabling their organization to achieve an infrastructure goal.

Historically, there has not been a straightforward way to “capture” this hard-won expertise and make it available to others. To fully adopt a pattern defined by a subject matter expert, an end-user needs to:

1. Read the documentation
2. Generate the code from the documentation
3. Run the code
4. Validate the code
5. Iterate as needed

Static documentation meets the first step, but quickly gets out of date, requires manual copy & pasting, manual adaptation of the instructure to fit the end user’s needs, and typically lacks validation steps. Worse, the subject matter expert rarely gets feedback about which part of the documentation was incomplete or incorrect. This gives rise to the all-too-common “it’s not quite what I wanted” experience of using documentation.

There are various templating tools available to automate the second step above, but code generation is rarely paired with effective documentation, it can be hard to customize, and the end user experience is often clumsy.

Runbooks aim to offer a new paradigm that dramatically lowers the bar for subject matter experts by making it enjoyable to capture their expertise, and dramatically raises the bar for “expertise consumers” by giving them an interactive, personalized, and clean experience they can use to understand and apply a pattern.

What does a Runbook look like?

Runbook authors are DevOps subject matter experts and write Runbooks.

A typical Runbook directory looks like this:

• runbook.mdx The official Runbook file.
• Directorychecks/ Bash scripts used by Checks

  • …
• Directoryscripts/ Bash scripts used by Commands

  • …
• Directorytemplates/ Templates used by BoilerplateInputs

  • …
• Directoryassets/ Images and other assets used by the Runbook

  • …

You can learn more about how to write a Runbook in the Authoring Runbooks section, but for now, the basic idea is that a runbook.mdx file contains a mix of markdown and interactive blocks. Those blocks optionally reference files in the checks/, scripts/, and templates/ directories.

How do you open a Runbook?

Runbook consumers want to apply someone else’s DevOps expertise, so they consume Runbooks by opening them on their local machine, and using them in their web browser.

To open a Runbook, you can use the runbooks open command:

runbooks open /path/to/runbook.mdx

Note that for now, you will need to manually download the full Runbook directory (runbook.mdx plus any other files in the checks/, scripts/, and templates/ directories) to your local machine.

Next

To see a Runbook in action, let’s Install Runbooks and then Write Your First Runbook.