Runbook

See our blog post for the philosophy behind Runbook and an overview of its features.

Runbook provides a DSL for specifying a series of steps to execute an operation. Once your runbook is specified, you can use it to generate a formatted representation of the book or to execute the runbook interactively. For example, you can export your runbook to markdown or use the same runbook to execute commands on remote servers.

<div align="center"> <img width="600" src="images/runbook_example.gif" alt="example of a runbook" /> </div> <br>

Runbook has two modes for evaluating your runbook. The first mode, view mode, allows you to export your runbook into various formats such as markdown. The second mode, run mode, allows you to execute behavior based on the statements in your runbook.

<div align="center"> <img width="600" src="images/runbook_execution_modes.png" alt="diagram of execution modes" /> </div> <br>

Runbook can be integrated into existing infrastructure in many different ways. It can be integrated into existing projects to add orchestration functionality, installed on systems as a stand-alone executable, or runbooks can be defined as self-executable scripts. In addition to being useful for automating common tasks, runbooks are a perfect bridge for providing operations teams with step-by-step instructions to handle common issues (especially when solutions cannot be easily automated).

Lastly, Runbook provides an extendable interface for augmenting the DSL and defining your own behavior.

Features

• Remote Command Execution - Runbook lets you execute commands on remote hosts using SSHKit
• Dynamic Control Flow - Runbooks can start execution at any step and can skip steps based on user input.
• Resumable - Runbooks save their state at each step. If your runbook encounters an error, you can resume your runbook at the previous step after addressing the error.
• Noop and Auto Modes - Runbooks can be executed in noop mode. This allows you to see what a runbook will do before it executes. Runbooks can be run in auto mode to eliminate the need for human interaction.
• Execution Lifecycle Hooks - Runbook provides before, after, and around hooks to augment its execution behavior.
• Tmux Integration - Runbook integrates with tmux. You can define terminal pane layouts and send commands to terminal panes.
• Generators - Runbook provides commands to generate runbooks, extensions, and runbook projects. You can define your own generators for easy, customized runbook creation.
• Extendable DSL - Runbook's DSL is designed to be extendable. You can extend its DSL to add your own behavior.

Use Cases

Though Runbook can solve a myriad of problems, it is best used for removing the need for repeated, rote developer operations. Runbook allows developers to execute processes at a higher level than that of individual command-line commands. Additionally, Runbook provides features to simply and safely execute operations in mission-critical environments.

Runbook is not intended to replace more special-purpose automation solutions such as configuration management solutions (Puppet, Chef, Ansible, Salt), deployment solutions (Capistrano, Kubernetes, Docker Swarm), monitoring solutions (Nagios, Datadog), or local command execution (shell scripts, Rake tasks, Make). Instead Runbook is best used as a glue when needing to accomplish a task that cuts across these domains.

Quick Start

Installation

Add this line to your application's Gemfile:

gem 'runbook'

And then execute:

$ bundle

Or install it yourself as:

$ gem install runbook

Your First Runbook

Generate a runbook using the Runbook Generator:

$ runbook generate runbook my_first_runbook

Execute the runbook:

$ runbook exec my_first_runbook.rb

Slightly Longer Start

When setting up Runbook, you can install it at a system level, create a dedicated runbook project, or incorporate Runbook into an existing project.

System Level Setup

Install runbook at a system level using gem:

$ gem install runbook

Set any Runbook configuration in /etc/runbook.conf.

Generate runbook files using runbook generate runbook. Execute runbook generate help runbook for more details.

Installing Runbook at a system level can be useful for executing runbooks on remote hosts or within docker containers. One disadvantage of installing Runbook at a system level is that there is no built-in solution for dependency management.

New Project Setup

Install runbook using gem:

$ gem install runbook

Generate a new runbook project:

$ runbook generate project <PROJECT_NAME>

This will generate a new runbook project. Cd into your project directory and initialize its dependencies:

$ cd <PROJECT_NAME> && bin/setup

Existing Project Setup

Add this line to your project's Gemfile:

gem 'runbook'

Install the Runbook gem:

$ bundle install

Initialize Runbook in your project:

$ bundle exec runbook init

Contents

• 1. Runbook Anatomy
  • 1.1 Entities, Statements, and Setters
    • 1.1.1 Books, Sections, Steps, and Setup
      • 1.1.1.1 Books
      • 1.1.1.2 Sections
      • 1.1.1.3 Steps
      • 1.1.1.4 Setup
      • 1.1.1.5 Tags and Labels
    • 1.1.2 Statements
      • 1.1.2.1 Ask
      • 1.1.2.2 Assert
      • 1.1.2.3 Capture
      • 1.1.2.4 Capture All
      • 1.1.2.5 Command
      • 1.1.2.6 Confirm
      • 1.1.2.7 Description
      • 1.1.2.8 Download
      • 1.1.2.9 Layout
      • 1.1.2.10 Note
      • 1.1.2.11 Notice
      • 1.1.2.12 Ruby Command
      • 1.1.2.13 Tmux Command
      • 1.1.2.14 Upload
      • 1.1.2.15 Wait
      • 1.1.2.16 Tmux Layouts
    • 1.1.3 Setters
• 2. Working With Runbooks
  • 2.1 Via The Command Line
  • 2.2 From Within Your Project
  • 2.3 Self-executable
• 3. Configuration
  • 3.1 Configuration Files
• 4. Best Practices
  • 4.1 Iterative Automation
  • 4.2 Parameterizing Runbooks
  • 4.3 Passing State
  • 4.4 Execution Best Practices
  • 4.5 Remote Command Execution
  • 4.6 Composing Runbooks
  • 4.7 Deep Nesting
  • 4.8 Load Vs. Eval
• 5. Generators
  • 5.1 Predefined Generators
  • 5.2 Custom Generators
• 6. Extending Runbook
  • 6.1 Adding New Statements
  • 6.2 Adding Run and View Functionality
  • 6.3 DSL Extensions
  • 6.4 Adding Runs and Views
  • 6.5 Augmenting Functionality With Hooks
  • 6.6 Adding New Run Behaviors
  • 6.7 Adding to Runbook's Run Metadata
  • 6.8 Adding to Runbook's Configuration
• 7. Testing
• 8. Known Issues
• 9. FAQ
• 10. Development
• 11. Contributing
• 12. Feature Requests
• 13. License
• 14. Code of Conduct

Runbook Anatomy

Below is an example of a runbook:

Runbook.book "Restart Nginx" do
  description <<-DESC
This is a simple runbook to restart nginx and verify
it starts successfully
  DESC

  section "Restart Nginx" do
    server "app01.prod"
    user "root"

    step "Stop Nginx" do
      note "Stopping Nginx..."
      command "service nginx stop"
      assert %q{service nginx status | grep "not running"}
    end

    step { wait 5 }

    step "Start Nginx" do
      note "Starting Nginx..."
      command "service nginx start"
      assert %q{service nginx status | grep "is running"}
      confirm "Nginx is taking traffic"
      notice "Make sure to report why you restarted nginx"
    end
  end
end

Hierarchically, a runbook looks like this:

<div align="center"> <img width="600" src="images/runbook_anatomy_diagram.png" alt="diagram of a runbook" /> </div> <br>

Entities, Statements, and Setters

A runbook is composed of entities, statements, and setters. Runbook entities contain either other entities or statements. Examples of entities include Books, Sections, and Steps. They define the structure of the runbook and can be considered the "nodes" of the tree structure. As entities are the nodes of the tree structure, statements are the "leaves" of the structure and comprise the various behaviors or commands of the runbook. Setters, typically referenced from within steps, associate state with the node, which can be accessed by its children.

Books, Sections, Steps, and Setup

Entities are composed of a title and a list of items which are their children. Each entity can be rendered with a specific view or executed with a specif