Playbook

Playbooks are configurable automated processes that can be used to perform a variety of actions for a component or a config item. They are defined using a YAML configuration.

restart-unhealthy-database.yaml

apiVersion: mission-control.flanksource.com/v1
kind: Playbook
metadata:
  name: restart-unhealthy-database
spec:
  description: Restart when a database becomes unhealthy
  on:
    component:
      - event: unhealthy
        filter: component.type == 'database'
        labels:
          industry: e-commerce
  actions:
    - name: 'Restart kubernetes deployment'
      exec:
        script: kubectl rollout restart deployment {{.component.name}}

Fig: Playbooks Page

Spec

Field	Description	Scheme	Required
description	A short description	string	true
icon	Icon for the playbook	string
on	Specify events to automatically trigger the Playbook. .	[]Trigger
checks	Specify selectors for checks that can be run on the Playbook.	[]ResourceFilter
configs	Specify selectors for config items that can be run on the Playbook.	[]ResourceFilter
components	Specify selectors for component items that can be run on the Playbook.	[]ResourceFilter
parameters	Define a set of labeled parameters for the Playbook.	[]Parameter
actions	Specify the set of actions to run.	[]Action	true
approval	Specify who can approve runs on this playbook.	Approval

Trigger

Field	Description	Scheme	Required
canary	Setup trigger on canary events	EventTrigger
component	Setup trigger on health check events.	EventTrigger
webhook	Setup a webhook endpoint that triggers the playbook.	WebhookTrigger

ResourceFilter

Filters can define what resources (checks, configs or components) are permitted be run on the Playbook.

Field	Description	Scheme	Required
type	Specify type of component.	string
tags	Specify tags of component.	map[string]string

Parameter

Playbook parameter defines a parameter that a playbook needs to run.

Field	Description	Scheme	Required
name	Name of parameter.	string	true
default	Default value of the parameter.	string
label	Label of the parameter.	string	true
required	Specify if the parameter is required	bool
icon	Icon of parameter. See icons	string
description	Description of the parameter.	string
type	Type of parameter.	string
properties	Properties of parameter.	map[string]string

Run

A run is the execution of a Playbook consisting of a sequence of actions. A run can be trigger either

• manually
• on events
• on schedule (upcoming)

For example, a playbook can be executed when a health check passes or fails.

Fig: Playbooks Runs

Start Time

Every run must have a start time which is the time the run is scheduled to start. By default, the it is set to the current time.

Start time can be in future or even in the past.

Action

Actions are the fundamental tasks executed by a playbook. A playbook can comprise multiple actions, which are executed sequentially. If any action encounters an error and fails, the execution of the playbook is halted.

Field	Description	Scheme	Required
name	Name of action.	string	true
delay	A CEL expression that evaluates to a duration to delay the execution of the action. (Sensitive to the minute.)	string
timeout	Timeout on this action.	DurationString
exec	Specify exec of action.	ExecAction
gitops	Specify gitops of action.	GitopsAction
http	Specify http of action.	HttpAction
sql	Specify sql of action.	SqlAction
pod	Specify pod of action.	PodAction
notification	Specify notification of action.	NotificationAction

note

Specify one or more actions; but at least one.

Fig: Playbooks Action Logs

Delaying actions

Actions can be delayed by a fixed duration or conditionally by a CEL expression. It's only sensitive to the minute. i.e. if you delay by 20s it can take upto a minute to execute.

Templating

The CEL expression receives a environment variable that contain details about the corresponding config, check or component and the parameter (if applicable).

Field	Description	Schema
config	Config passed to the playbook	ConfigItem
component	Component passed to the playbook	Component
check	Canary Check passed to the playbook	Check
params	User provided parameters to the playbook	map[string]string

Valid time units are "s", "m", "h", "d", "w", "y". Eg:

• 1m15s
• 1h5m
• 23h
• 1d8h
• 1w6d8h
• 19w0d8h

Conditionally running actions

Playbook actions can be conditionally run using a CEL Expression. The expressions should either return

• a boolean value (true indicating run the action & skip the action otherwise)
• or a special function among the ones listed below

Functions

Function	Description
always()	run no matter what; even if the playbook is cancelled/fails
failure()	run if any of the previous actions failed
skip()	skip running this action
success()	run only if all previous actions succeeded (default)
timeout()	run only if any of the previous actions timed out

Examples

• if: config.deleted_at ? true: false
• if: always()