Use cases

These are the situations where teams most often wait on an infrastructure expert.

Developer self-service

To use an infrastructure pattern, an app developer has to look it up, learn enough of the technology to write the code, debug it, and deploy it. Many ask an infrastructure expert for help and then wait for an answer.

A runbook written by that expert lets app developers launch new infrastructure that follows your organization’s practices. For example:

Create a new K8s Service
Scaffold a new app repo
Launch a new database
Launch a new static website

Landing zones

Most engineering organizations eventually need a repeatable way to create new AWS accounts, GCP projects, or Azure subscriptions, organize them, and install a baseline of resources for security and governance. This is called setting up a landing zone.

Setting up a landing zone means solving three problems:

Define your baseline, for example as OpenTofu modules.
Define a way to create a new AWS account, GCP project, or Azure subscription, for example through the cloud API or an OpenTofu module.
Present a UI where users configure the account, project, or subscription they want.

OpenTofu modules and cloud APIs already solve the first two. A runbook solves the third by combining them. It asks the user for values such as an email, name, and description, calls the API to provision the account, and generates the code that installs the baseline.

A value the runbook asks for, such as an AWS account ID, is available to the code it generates and the scripts it runs.

The same runbook can provision SSO access, explain how to use the new resources, point the user at policies to review, and link to their account, without a custom user interface.

Internal processes

Many internal processes are captured as static documentation. A runbook carries out the process as you read it. For example:

Provision a new AWS Account, configure the account baseline and all networking configurations, and validate everything along the way.
Stand up a new customer with all the infrastructure and all the information they need to get started.

Document IaC modules

A reusable infrastructure-as-code (IaC) module needs more than its code. Users need to know how to use it, see common usage examples, and confirm that it works.

A runbook collects configuration from the user, generates the module code, and validates the result. For example:

Create an SNS topic that notifies a Slack channel
Create an SNS topic that notifies an email address
Create an SNS topic that notifies a PagerDuty service

You might define one Runbook for each of these, or a single Runbook that can create any of these configurations.

Next, see how Runbooks compares to other tools.