Report Action

Report action renders a catalog report for a set of config items and saves it as an artifact. A report gathers everything Mission Control knows about the selected config items — their changes, insights, relationships, access and access logs — and renders it as HTML, PDF, JSON, CSV, Markdown or Slack.

The config items to report on come from one of three places, which are mutually exclusive:

• configsFromParams — reuse the config items already resolved from a playbook parameter named configs of type configs. This avoids a second database query and guarantees the report covers exactly what the user selected.
• configs — an inline resource selector.
• view — an existing View.

catalog-report.yaml
# yaml-language-server: $schema=../../config/schemas/playbook.schema.json
apiVersion: mission-control.flanksource.com/v1
kind: Playbook
metadata:
  name: catalog-report
spec:
  title: Catalog Report
  category: Reporting
  description: >-
    Generates a catalog report for one or more root config items and uploads it
    as an artifact.
  parameters:
    - name: configs
      label: Root configs
      description: Select one or more root config items
      type: configs
      required: true
    - name: format
      label: Format
      type: list
      default: html
      properties:
        options:
          - label: HTML
            value: html
          - label: PDF
            value: pdf
          - label: JSON
            value: json
    - name: title
      label: Report title
      type: text
      default: Catalog Report
    - name: since
      label: Time period
      description: 'Time range for changes and access logs (e.g. 7d, 30d, 90d)'
      type: text
      default: 30d
    - name: recursive
      label: Include all descendant config items
      type: checkbox
      default: "false"
    - name: groupBy
      label: Group descendant data
      type: list
      default: none
      properties:
        options:
          - label: None
            value: none
          - label: Merged
            value: merged
          - label: Per config
            value: config
    - name: changes
      label: Include config changes
      type: checkbox
      default: "true"
    - name: insights
      label: Include config insights
      type: checkbox
      default: "true"
    - name: resolvedInsights
      label: Include recently resolved insights
      type: checkbox
      default: "false"
    - name: insightDetails
      label: Render insight details
      description: >-
        Render each insight's message under the affected resource. Without it
        insights are only grouped and counted.
      type: checkbox
      default: "false"
    - name: relationships
      label: Include relationships
      type: checkbox
      default: "true"
    - name: access
      label: Include RBAC access
      type: checkbox
      default: "true"
    - name: accessLogs
      label: Include access logs
      type: checkbox
      default: "false"
    - name: configJSON
      label: Include raw config JSON
      type: checkbox
      default: "false"
    - name: changeArtifacts
      label: Include change artifacts
      type: checkbox
      default: "false"
    - name: expandGroups
      label: Expand group access into members
      type: checkbox
      default: "false"
    - name: audit
      label: Include audit details
      type: checkbox
      default: "false"
    - name: filters
      label: Additional descendant filters
      description: Comma-separated filters appended to the default report filters
      type: text
      default: ""
  actions:
    - name: Generate Report
      report:
        # Reuse the already-resolved `configs` parameter instead of querying the selected IDs again.
        configsFromParams: true
        title: '{{ .params.title }}'
        format: '{{ .params.format }}'
        since: '{{ .params.since }}'
        recursive: '{{ .params.recursive }}'
        groupBy: '{{ .params.groupBy }}'
        changeArtifacts: '{{ .params.changeArtifacts }}'
        expandGroups: '{{ .params.expandGroups }}'
        audit: '{{ .params.audit }}'
        filters:
          - '{{ .params.filters | default "" }}'
        file:
          path: report/CatalogReport.tsx
        facet:
          connection: connection://mission-control/facet
        sections:
          changes: '{{ .params.changes }}'
          insights: '{{ .params.insights }}'
          resolvedInsights: '{{ .params.resolvedInsights }}'
          insightDetails: '{{ .params.insightDetails }}'
          relationships: '{{ .params.relationships }}'
          access: '{{ .params.access }}'
          accessLogs: '{{ .params.accessLogs }}'
          configJSON: '{{ .params.configJSON }}'

This example:

1. Uses a configs parameter of type configs so the operator picks the root config items in the UI.
2. Uses configsFromParams: true to reuse those resolved config items instead of querying the selected IDs again.
3. Uses file.path and facet.connection to render CatalogReport.tsx through a facet server, and sections to choose what the report covers.

Field	Description	Scheme
name*	Step Name	string
report	Report Action	Report
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

Report

Field	Description	Scheme
audit	Include build details, effective settings, query logs, scrapers and groups	boolean
changeArtifacts	Embed artifacts associated with the included config changes	boolean
configs	Inline selector for the config items to report on	ResourceSelector
configsFromParams	Use the config items resolved from the playbook parameter named configs. The playbook must declare a parameter with that name and the type configs	boolean
expandGroups	Expand group-granted access into a row per active group member	boolean
facet	Rendering options for the facet-html and facet-pdf formats	Facet
file	The TSX template that renders the report. When unset, Mission Control uses the embedded CatalogReport.tsx	File
filters	Filters that Mission Control appends to the report's own filters. Explicitly selected roots remain selected; filters only apply to recursive descendants	[]string
format	Output format	html | pdf | json | csv | markdown | slack | facet-html | facet-pdf
groupBy	How descendant data is grouped. Defaults to none	none | merged | config
recursive	Include all descendant config items	boolean
sections	Which sections to include in the report	Sections
since	Time range for changes, access logs and resolved insights e.g. 30d. Defaults to 30d	Duration
title	Overrides the default report title	string
variables	Variables passed to the view queries	[map[string]string]
view	Reference an existing view by namespace/name or just name	string

You must specify one of configsFromParams, configs or view

note

recursive, changeArtifacts, expandGroups, audit and every field under sections accept either a literal boolean or a template that renders to true or false. Mission Control decodes actions before it runs templates, so '{{ .params.recursive }}' is valid in all of them.

Sections

Each section defaults to the report template's own setting.

Field	Description	Scheme
access	Include RBAC access	boolean
accessLogs	Include access logs	boolean
changes	Include config changes	boolean
configJSON	Include the raw config JSON	boolean
insightDetails	Render each insight's message under the affected resource. Without it, insights are only grouped and counted	boolean
insights	Include config insights	boolean
relationships	Include config relationships	boolean
resolvedInsights	Include recently resolved insights	boolean

File

Selects the TSX template used to render the report, either from a local path or from a git repository.

Field	Description	Scheme
git	A TSX file inside a git repository	Git
path	Path to a local TSX file. A relative path is resolved against the working directory e.g. report/CatalogReport.tsx. The file's directory must contain the report scaffold	string

You must specify path or git but not both

Git

Field	Description	Scheme
file*	Path to the TSX file within the repository	string
url*	URL of the git repository	string
base	Branch to clone. Defaults to main	string
connection	Connection name used for credentials to the git repo	string

Facet

The facet-html and facet-pdf formats render the report through a facet server.

Field	Description	Scheme
connection	Connection to the facet server e.g. connection://mission-control/facet	string
footer	HTML rendered as the page footer	string
header	HTML rendered as the page header	string
landscape	Render in landscape orientation	boolean
margins.bottom	Bottom margin	integer
margins.left	Left margin	integer
margins.right	Right margin	integer
margins.top	Top margin	integer
pageSize	Page size e.g. A4, Letter	string
timeout	Timeout for the render e.g. 10m. When unset the facet server's own render timeout applies	Duration
timestampUrl	RFC 3161 timestamp authority used to timestamp the rendered document	string
url	URL of the facet server	string

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