Exec Action

Exec action allows you to executes a command or a script file on the target host. The type of scripts executed include:

Bash scripts
Powershell scripts

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}}

Field	Description	Scheme
`name*`	Step Name	`string`
`exec`	Exec Action	Exec
`delay`	A delay before running the action e.g. `8h`	`Duration` or CEL with Playbook Context
`filter`	Conditionally run an action	CEL with Playbook Context
`runsOn`	Which runner (agent) to run the action on	`[]Agent`
`templatesOn`	Where templating (and secret management) of actions should occur	`host` or `agent`
`timeout`	Timeout on this action.	Duration

Exec

Field	Description	Scheme
`script*`	The script to execute	`string`
`artifacts`	Artifacts produced by the action	Artifacts
`checkout`	Checkout a git repository before running the script	Checkout
`connections`	Connections used by the action	Connections
`env`	Environment variables to set during execution	[]EnvVar
`setup`	Install runtime dependencies (Bun, Python, PowerShell, Playwright) before execution	Setup

Output

Field	Description	Scheme
`args`	Args for the command	`[]string`
`exitCode`	Exit code of command	`integer`
`path`	Path for command context	`string`
`stderr`	Stderr of command	`string`
`stdout`	Stdout of command	`string`

Templating

Scripts are templatable with Go Templates

exec:
        script: kubectl rollout release deployment -n $(.config.tags.namespace) $(.conf

Shell Language

Use a shebang (#!) line to choose a different shell (python, bash and pwsh are included in the base image)

exec:
  script: |
    #! pwsh
    Get-Items | ConvertTo-JSON

Switching scripting language

Use a shebang (#!) line to choose a different shell (python, bash and pwsh are included in the base image)

exec:
  script: |
    #! pwsh
    Get-Items | ConvertTo-JSON

Escaping templates in Helm Charts

If you need to pass a template through a Helm Chart and prevent Helm from templating you need to escape it:

{{`{{ .secret }}`}}

Alternatively change the templating delimiters (see below)

Multiline handling with YAML

If you are using a YAML multiline string use | and not > which strips newlines.

Instead of:

exec:
  script: >
    #! pwsh
    Get-Items | ConvertTo-JSON

Do this:

exec:
  script: |
    #! pwsh
    Get-Items | ConvertTo-JSON

Changing templating delimiters

The template delimiters can be changed from the defaults of $() and {{}} with gotemplate comments

exec:
  script: |
    #! pwsh
    # gotemplate: left-delim=$[[ right-delim=]]
    $message = "$[[.config.name]]"
    Write-Host "{{  $message }}"
    Write-Host  @{ Number = 1; Shape = "Square"; Color = "Blue"} | ConvertTo-JSON

Connections

Exec connections allow you to specify credentials for a list of CLI tools that are needed by your scripts. Eg: You can specify the AWS connection name and the credential files along with the necessary environment variables will be setup on the host running the script.

Field	Description	Scheme
`aws`	AWS connection	AWSConnection
`azure`	Azure connection	AzureConnection
`eksPodIdentity`	EKSPodIdentity when enabled will allow access to AWS_* env vars	`boolean`
`fromConfigItem`	Fetch connection from a Config item's scraper	uuid
`gcp`	GCP connection	GCPConnection
`kubernetes`	Kubernetes connection	KubernetesConnection
`opensearch`	OpenSearch connection	OpenSearchConnection
`serviceAccount`	ServiceAccount when enabled will allow access to KUBERNETES env vars	`boolean`

Artifacts

exec-artifact.yaml
apiVersion: mission-control.flanksource.com/v1
kind: Playbook
metadata:
  name: exec-artifact
spec:
  description: Simple script to generate an artifact
  configs:
    - types: 
        - EC2 Instance
      labelSelector: "telemetry=enabled"
  actions:
    - name: 'Generate artifact'
      exec:
        script: echo "hello world" > /tmp/output.txt
        artifacts:
          - path: /tmp/output.txt

Field	Description	Type	Required
`path`	Path or glob.	`string`	`true`

Git Checkout

exec-checkout.yaml
apiVersion: mission-control.flanksource.com/v1
kind: Playbook
metadata:
  name: read-git-repository
spec:
  description: Clones the git repository and reads the first line of the file
  configs:
    - types:
        - AWS::EKS::Cluster
  actions:
    - name: Clone and read go.sum
      exec:
        script: head -n 1 $READ_FILE
        env:
          - name: READ_FILE
            value: go.sum
        checkout:
          url: https://github.com/flanksource/artifacts
          connection: connection://github/aditya-all-access

Field	Description	Scheme
`branch`	Branch or tag to checkout. Defaults to the repository's default branch	`string`
`certificate`	SSH private key to authenticate with	EnvVar
`certificate`		EnvVar
`connection`	Connection name to use for the git credentials	`string`
`connection`	The connection url to use, mutually exclusive with `username` and `password`	Connection
`depth`	Git clone depth for shallow clones	`integer`
`password`	Password or access token to authenticate with	EnvVar
`password`		EnvVar
`type`	Git repository type	`github`, `gitlab`, `azure_devops`, `http`, `git`
`url`	URL of the git repository	`string`
`username`	Username to authenticate with	EnvVar
`username`		EnvVar

You must specify connection or url but not both

Setup

The setup field allows you to automatically install runtime environments before executing your script. This is useful when your script requires specific versions of Bun, Python, PowerShell or Playwright that may not be available in the base image.

Bun

exec-deps-pkgs-bun.yaml
---
apiVersion: mission-control.flanksource.com/v1
kind: Playbook
metadata:
  name: echo-bun-dependency-with-pkgs
  namespace: mc
spec:
  category: Exec
  actions:
    - name: foo
      exec:
        setup:
          bun:
            version: "1.3.5"
        script: |
          #!/usr/bin/env bun
          import isOdd from 'is-odd';
          console.log(isOdd(3));

Python

For Python scripts, you can declare dependencies inline using PEP 723 inline script metadata. The uv package manager is used to manage Python environments.

exec-deps-pkgs-python.yaml
---
apiVersion: mission-control.flanksource.com/v1
kind: Playbook
metadata:
  name: echo-python-dependency-with-pkgs
  namespace: mc
spec:
  category: Exec
  actions:
    - name: yaml
      exec:
        setup:
          python:
            version: "3.10.19"
        script: |
          #!/usr/bin/python3           
          # /// script
          # dependencies = [
          #   "pyyaml",
          # ]
          # ///

          # Declare dependencies inline with `Inline script metadata`
          # See: https://packaging.python.org/en/latest/specifications/inline-script-metadata/#inline-script-metadata

          import yaml
          document = """
            a: 1
            b:
              c: 3
              d: 4
          """
          print(yaml.dump(yaml.safe_load(document)))

Field	Description	Scheme
`bun`	Install Bun runtime	RuntimeSetup
`playwright`	Install Playwright and its browsers	RuntimeSetup
`powershell`	Install PowerShell	RuntimeSetup
`python`	Install Python runtime via uv	RuntimeSetup

RuntimeSetup

Field	Description	Scheme
`version`	Version to install (e.g., "1.3.5" for Bun, "3.10.19" for Python)	`string`

Action Result

Field	Description	Schema
`stdout`		`string`
`stderr`		`string`
`exitCode`	Process exit code	`int`

Templating

CEL Expressions

The following variables can be used within the CEL expressions of filter, if, delays and parameters.default:

Field	Description	Schema
`config`	Config passed to the playbook	`ConfigItem`
`check`	Canary Check passed to the playbook	`Check`
`playbook`	Playbook passed to the playbook	`Playbook`
`run`	Current run	`Run`
`params`	User provided parameters to the playbook	`map[string]any`
`request`	Webhook request	`Webhook Request`
`env`	Environment variables defined on the playbook	`map[string]any`
`user.name`	Name of the user who invoked the action	`string`
`user.email`	Email of the user who invoked the action	`string`
`agent.id`	ID of the agent the resource belongs to.	`string`
`agent.name`	Name of the agent the resource belongs to.	`string`

Conditionally Running Actions

Playbook actions can be selectively executed based on CEL expressions. These expressions must either return

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

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

delete-kubernetes-pod.yaml
---
apiVersion: mission-control.flanksource.com/v1
kind: Playbook
metadata:
  name: notify-send-with-filter
spec:
  parameters:
    - name: message
      label: The message for notification
      default: '{{.config.name}}'
  configs:
    - types: 
        - Kubernetes::Pod
  actions:
    - name: Send notification
      exec:
        script: notify-send "{{.config.name}} was created"
    - name: Bad script
      exec:
        script: deltaforce
    - name: Send all success notification
      if: success() # this filter practically skips this action as the second action above always fails
      exec:
        script: notify-send "Everything went successfully"
    - name: Send notification regardless
      if: always()
      exec:
        script: notify-send "a Pod config was created"

Defaulting Parameters

delete-kubernetes-pod.yaml
apiVersion:
  mission-control.flanksource.com/v1
  kind: Playbook
  metadata:
    name: edit
  spec:
    title: 'Edit Kustomize Resource'
    icon: flux
    parameters:
    - default: 'chore: update $(.config.type)/$(.config.name)'
      name: commit_message

Go Templating

When templating actions with Go Templates, the context variables are available as fields of the template's context object . eg .config, .user.email

Templating Actions

delete-kubernetes-pod.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}}

Functions

Function	Description	Return
`getLastAction()`	Returns the result of the action that just run	Action Specific
`getAction({action})`	Return the result of a specific action	Action Specific

Printing out Results

Reusing Action Results

action-results.yaml
apiVersion: mission-control.flanksource.com/v1
kind: Playbook
metadata:
  name: use-previous-action-result
spec:
  description: Creates a file with the content of the config
  configs:
    - types:
        - Kubernetes::Pod
  actions:
    - name: Fetch all changes
      sql:
        query: SELECT id FROM config_changes WHERE config_id = '{{.config.id}}'
        driver: postgres
        connection: connection://postgres/local
    - name: Send notification
      if: 'last_result().count > 0'
      notification:
        title: 'Changes summary for {{.config.name}}'
        connection: connection://slack/flanksource
        message: |
          {{$rows:=index last_result "count"}}
          Found {{$rows}} changes

Exec​

Output​

Templating​

Shell Language​

Connections​

Artifacts​

Git Checkout​

Setup​

Bun​

Python​

RuntimeSetup​

Action Result​

Templating​

CEL Expressions​

Go Templating​

Functions​

Exec

Output

Templating

Shell Language

Connections

Artifacts

Git Checkout

Setup

Bun

Python

RuntimeSetup

Action Result

Templating

CEL Expressions

Go Templating

Functions