Playbooks

Playbooks automate common workflows and processes by defining reusable templates of actions that can be triggered on-demand by users, when specific events happen or through webhooks.

Some key benefits include:

• Accelerated GitOps Adoption - Use "ClickOps" to make changes to resources but have them being applied as Git pull requests in the background, enabling non-technical teams to leverage GitOps workflows.
• Consistency - Provide easy to discover and reusable templates for common tasks, preventing the complexity of doing the same thing multiple ways.
• Self-Service - Enable developers/operators to provision and manage their own resources without involving a central DevOps/Platform team.
• Compliance - Improve compliance and security by limiting the need for elevated privileges.
• Cost Efficiency - Optimize costs with on-demand environments that spin down after a fixed duration.
• Portability - A consistent interface for performing operations irrespective of the underlying infrastructure and/or environment

---

Use cases

Provisioning

Day 2 Operations

Day 2 operations can be added onto existing resources (configs, components or health checks) using resource selectors.

For example scaling a Kubernetes Deployment is only applicable to config items of type: Kubernetes::Deployment

scale-deployment.yaml
apiVersion: mission-control.flanksource.com/v1
kind: Playbook
metadata:
  name: scale-deployment
spec:
  description: Scale Deployment
  configs:
    - types:
        - Kubernetes::Deployment
  parameters:
    - name: replicas
      label: The new desired number of replicas.
  actions:
    - name: kubectl scale
      exec:
        script: |
          kubectl scale --replicas={{.params.replicas}} \
            --namespace={{.config.tags.namespace}} \
            deployment {{.config.name}}

Before running a playbook, users can provide input using parameters. In the playbook above, the user can decide the new number of replicas before running the playbook.

Just In Time Access

AIOps

Actions

Playbooks execute a sequence of actions (steps), these actions can update git repositories, invoke pipelines or run command line tools like kubectl and aws.

Templating

The actions values can be templated using Go Templates

restart-deployment.yaml
#...
kind: Playbook
spec:
  configs:
    - types:
        - Kubernetes::Deployment
  actions:
    - name: 'Restart kubernetes deployment'
      exec:
        script: kubectl rollout restart deployment {{.config.name}} -n {{.config.tags.namespace}}

The parameters to the playbooks are available in the Context

Approval

Playbooks can require approval before execution by configuring an approval block:

approve-kubernetes-scaling.yaml
#...
kind: Playbook
spec:
  #...
  approval:
    type: any
    approvers:
      people:
        - admin@local
      teams:
        - DevOps

Field	Description	Scheme	Required
type	How many approvals required. Defaults to all	any or all	false
approvers.[]people	Login or id of a person	People	false
approvers.[]teams	Name or id of a team	Team	false

Permissions

Playbook permissions control who can perform various actions on playbooks.

playbook-permissions.yaml
---
# yaml-language-server: $schema=../../config/schemas/permission.schema.json
apiVersion: mission-control.flanksource.com/v1
kind: Permission
metadata:
  name: allow-user-playbook-run
spec:
  description: |
    allow user john to run any playbook but only on configs in `mission-control` namespace
  subject:
    person: john@doe.com
  actions:
    - playbook:*
  object:
    playbooks:
      - name: "*" # this is a wildcard selector that matches any playbook
    configs:
      - namespace: mission-control

Required Permissions

To run a playbook, a principal (user, team, or service account) needs:

1. The playbook:run permission on the playbook
2. A read permission on the resource the playbook targets

For example, to run a playbook that scales a Kubernetes deployment, the principal needs:

• playbook:run permission on the scaling playbook
• read permission on the target Kubernetes deployment resource

Permission Types

Permission	Description
playbook:run	Run a playbook
playbook:approve	Approve a playbook run
playbook:cancel	Cancel a running playbook

Permission Inheritance

info

When a playbook triggers another playbook, the permissions are evaluated using the playbook's identity, not the original user who initiated the first playbook. This means the triggering playbook must have permission to run the target playbook and to read the resources.