Skip to main content
Version: 8.5.7 (latest)

Blueprint YAML Schema and Template Variables

A Kasten Blueprint is a Kubernetes Custom Resource of kind Blueprint in the cr.kanister.io/v1alpha1 API group. The open-source Kanister framework defines this CR. Kasten integrates with Kanister to execute application-specific logic around backup and restore operations.

Blueprint CR​

apiVersion: cr.kanister.io/v1alpha1
kind: Blueprint
metadata:
  name: <blueprint-name>
  namespace: kasten-io
actions:
  <actionName>:
    ...

Blueprints must reside in the Veeam Kasten namespace (default kasten-io). Kasten does not discover blueprints in other namespaces. Annotations, BlueprintBindings, and action hooks reference blueprints by name.

Action​

Each key under actions is an action name (for example, backupPrehook or restorePosthook). Kasten uses the action name to determine when to call the action.

In standalone Kanister, action names can be arbitrary. In the Kasten context, Kasten only calls actions with specific reserved names (such as backupPrehook, backupPosthook, restorePosthook). Actions with non-reserved names are silently ignored unless configured as action hooks on a policy.

Field Type Required Description
kind string No Expected Kubernetes resource kind (for example, StatefulSet or Deployment). See Kind Field.
configMapNames []string No ConfigMap names declared at the action level. Part of the standalone Kanister ActionSet mechanism. In the Kasten context, use the phase-level Objects Block instead.
secretNames []string No Secret names declared at the action level. Part of the standalone Kanister ActionSet mechanism. In the Kasten context, use the phase-level Objects Block instead.
phases []Phase Yes Ordered list of phases to execute
deferPhase Phase No A single phase that runs after all phases in an action complete, regardless of success or failure. See Defer Phase.
outputArtifacts map[string]Artifact No Key-value metadata stored in the restore point after the action completes. See Artifacts.
inputArtifactNames []string No Names of artifacts from a previous action to make available as .ArtifactsIn

Kind Field​

Kasten auto-discovers the resource kind from the actual Kubernetes resource the blueprint is bound to. Kasten populates typed template variables (.StatefulSet.*, .Deployment.*) only for StatefulSet and Deployment resources. For all other resource types (including custom resources), use .Object to access the resource metadata.

The kind field in the blueprint serves as documentation of which resource type the action expects. It does not affect Kasten's behavior.

For a complete list of available variables, see Template Variables. 

actions:
  backupPrehook:
    kind: StatefulSet
    phases:
      - func: KubeExec
        name: quiesce
        args:
          namespace: "{{ .StatefulSet.Namespace }}"
          pod: "{{ index .StatefulSet.Pods 0 }}"
          command: [sh, -c, "<quiesce command>"]

Phase​

A phase is a single step within an action, executed by the Kanister engine. Phases execute sequentially in the order they appear in the list. If a phase fails, all subsequent phases are skipped. To run cleanup logic regardless of success or failure, use a Defer Phase.

Field Type Required Description
func string Yes Kanister function to execute (for example, KubeExec, KubeTask, KubeOps, WaitV2, ScaleWorkload)
name string Yes Unique name within the action. Used to reference outputs from this phase through .Phases.<name>.Output.
args map[string]any Yes Arguments passed to the Kanister function. Each function defines its own argument schema. Template variables resolve before execution.
objects map[string]ObjectReference No Kubernetes Secrets or ConfigMaps to resolve at runtime. See Objects Block. 
phases:
  - func: KubeExec
    name: quiesceApp
    objects:
      dbSecret:
        kind: Secret
        name: '{{ .StatefulSet.Name }}-credentials'
        namespace: '{{ .StatefulSet.Namespace }}'
    args:
      namespace: "{{ .StatefulSet.Namespace }}"
      pod: "{{ index .StatefulSet.Pods 0 }}"
      container: postgres
      command:
        - sh
        - -c
        - |
          DB_PASSWORD='{{ index .Phases.quiesceApp.Secrets.dbSecret.Data "password" | toString }}'
          mydb-cli --password "$DB_PASSWORD" -c "FLUSH TABLES WITH READ LOCK;"

Defer Phase​

A defer phase runs after the phases list completes or after a phase failure stops execution. It runs regardless of success or failure. This makes it suitable for cleanup logic such as deleting temporary pods. It follows the same schema as a regular phase.

Declare deferPhase at the action level, as a sibling to phases:

actions:
  backupPrehook:
    kind: StatefulSet
    phases:
      - func: KubeOps
        name: createDumpPod
        args: { ... }
      - func: KubeExec
        name: dumpData
        args: { ... }
    deferPhase:
      func: KubeOps
      name: cleanupDumpPod
      args:
        namespace: "{{ .StatefulSet.Namespace }}"
        op: delete
        resource:
          apiVersion: v1
          resource: pods
          name: "{{ .StatefulSet.Name }}-dump-pod"
warning

In backupPrehook, the defer phase runs before Kasten takes PVC snapshots. Do not delete a dump PVC in the defer phase. Instead, delete the dump PVC in backupPosthook, which Kasten calls after snapshots complete.

Objects Block​

The objects block on a phase declares Kubernetes Secrets or ConfigMaps that Kasten resolves at runtime. The resolved data becomes available through template variables within that same phase.

Field Type Required Description
kind string Yes Secret or ConfigMap
name string Yes Resource name (supports template variables)
namespace string Yes Resource namespace (supports template variables)

Access resolved data as follows:

  • Secrets: .Phases.<phaseName>.Secrets.<objName>.Data.<key>
  • ConfigMaps: .Phases.<phaseName>.ConfigMaps.<objName>.Data.<key>

The | toString filter is required for Secret data, which contains base64-decoded bytes. 

phases:
  - func: KubeExec
    name: quiesceApp
    objects:
      pgSecret:
        kind: Secret
        name: '{{ .StatefulSet.Name }}'
        namespace: '{{ .StatefulSet.Namespace }}'
    args:
      command:
        - sh
        - -c
        - |
          password='{{ index .Phases.quiesceApp.Secrets.pgSecret.Data "password" | toString }}'
info

The objects block must be declared at the phase level, not the action level. Kasten resolves objects defined on phases only. Objects defined at the action level in standalone Kanister are not resolved in the Kasten context.

Artifacts​

Artifacts pass key-value metadata between actions through the Kasten restore point. Kasten stores artifact data inside the restore point alongside the resource manifests and snapshot references. This data persists for the lifetime of the restore point.

A backup action produces artifacts. A restore or delete action consumes them by declaring inputArtifactNames.

Output Artifacts​

Declare outputArtifacts at the action level. Each artifact is a named map of key-value pairs. Values support template variables and typically reference phase outputs through .Phases.<name>.Output.<key>.

Phase outputs are produced in two ways:

  • Shell-based functions (KubeExec, KubeTask): Use the kando output <key> <value> CLI inside the container.
  • Resource-based functions (KubeOps, WaitV2): Return outputs directly through the function implementation. 
actions:
  backupPrehook:
    kind: StatefulSet
    outputArtifacts:
      appMeta:
        keyValue:
          dbName: "{{ .Phases.captureInfo.Output.dbName }}"
          backupPath: "{{ .Phases.captureInfo.Output.backupPath }}"
    phases:
      - func: KubeExec
        name: captureInfo
        args:
          command:
            - sh
            - -c
            - |
              kando output dbName myDatabase
              kando output backupPath /dump/2024-01-01

Input Artifact Names​

Declare inputArtifactNames at the action level. This field lists artifact names from a previous action. The listed artifacts become available as .ArtifactsIn.<name>.KeyValue.<key>. 

actions:
  restorePosthook:
    kind: StatefulSet
    inputArtifactNames:
      - appMeta
    phases:
      - func: KubeExec
        name: postRestore
        args:
          command:
            - sh
            - -c
            - |
              DB="{{ .ArtifactsIn.appMeta.KeyValue.dbName }}"
info

Artifacts are only available for resource-bound blueprints (annotation or BlueprintBinding). They are not available for action hooks.

Template Variables​

When Kasten calls a blueprint action, it builds a template context and injects it into all string values before execution. The context includes resource metadata, resolved Secrets and ConfigMaps, phase outputs, artifacts, the location profile, and pod override settings. Blueprint authors do not create or manage this context directly.

All string values in args, objects, outputArtifacts, and kind fields support Go template rendering. Templates use {{ }} delimiters.

Resource Context Variables​

Kasten populates these variables when a blueprint binds to a resource through an annotation or BlueprintBinding. Kasten auto-discovers the resource type and selects the corresponding variable group.

Always available:

Variable Description
.Object.metadata.name Name of the bound Kubernetes object
.Object.metadata.namespace Namespace of the bound object
.Object.metadata.labels Labels on the bound object
.Object.metadata.annotations Annotations on the bound object
.Object.data.<key> Data field (for ConfigMap or Secret objects)

.Object contains the full Kubernetes resource as an unstructured map. You can access any field and use Go template constructs such as range loops. For example, to iterate over ImageStream tags: 

{{range $i, $tag := .Object.status.tags}}
  tag_name="{{ index $tag "tag" | toString }}"
{{end}}

Kasten populates one of the following groups based on the discovered resource type.

StatefulSet resources:

Variable Description
.StatefulSet.Name Name of the StatefulSet
.StatefulSet.Namespace Namespace of the StatefulSet
.StatefulSet.Pods List of pod names
.StatefulSet.Containers List of container name lists, one per pod
.StatefulSet.PersistentVolumeClaims PVC mappings per pod

Deployment resources:

Variable Description
.Deployment.Name Name of the Deployment
.Deployment.Namespace Namespace of the Deployment
.Deployment.Pods List of pod names
.Deployment.Containers List of container name lists, one per pod
.Deployment.PersistentVolumeClaims PVC mappings per pod

DeploymentConfig resources (OpenShift):

Variable Description
.DeploymentConfig.Name Name of the DeploymentConfig
.DeploymentConfig.Namespace Namespace of the DeploymentConfig
.DeploymentConfig.Pods List of pod names

PVC resources:

Variable Description
.PVC.Name Name of the PVC
.PVC.Namespace Namespace of the PVC

Namespace Context Variables​

Kasten populates these variables when the blueprint runs as an action hook. They are also available when the action targets a namespace rather than a specific resource.

Variable Description
.Namespace.Name Name of the namespace

Phase Output Variables​

A previous phase within the same action execution can emit output. Shell-based functions use kando output <key> <value>. Resource-based functions produce outputs directly.

Phase outputs pass information between phases that run in different contexts. For example, a KubeTask phase can discover workload state using a custom image with kubectl. A subsequent KubeExec phase can then use that information inside the application container.

Variable Description
.Phases.<phaseName>.Output.<key> Output value from a named phase

Secret and ConfigMap Variables​

Kasten populates these variables when the phase declares an objects block.

Variable Description
.Phases.<phaseName>.Secrets.<objName>.Data.<key> Decoded Secret data
.Phases.<phaseName>.ConfigMaps.<objName>.Data.<key> ConfigMap data

Use | toString when you access Secret data. Use index for keys that contain special characters: 

{{ index .Phases.myPhase.Secrets.mySecret.Data "my.key" | toString }}

Artifact Variables​

Kasten populates these variables in restore and delete actions when the action declares inputArtifactNames.

Variable Description
.ArtifactsIn.<artifactName>.KeyValue.<key> Artifact key-value from a previous action

Profile Variables​

Kasten populates these variables for resource-bound blueprints when a location profile is associated with the backup policy. These variables are not available for action hooks.

Variable Description
.Profile.Location Location profile configuration
.Profile.Credential Credential information for the profile
.Profile.SkipSSLVerify Whether SSL verification is skipped
info

Kasten passes the profile reference regardless of the profile type (object storage, NFS, or SMB). Most blueprint authors do not need to access profile details directly, as Kasten manages the storage interaction.

Time Variables​

Provided by the Kanister template engine at action execution time.

Variable Description
.Time Current UTC timestamp

Pod Override Variables​

These variables reflect pod specification overrides applied to Kanister job pods. For more information, see Kanister Pod Override.

Variable Description
.PodOverride Pod specification overrides (from the pod-spec-override ConfigMap)
.PodAnnotations Annotations applied to Kanister job pods
.PodLabels Labels applied to Kanister job pods

Template Functions​

Blueprint templates support Go built-in template functions and additional helpers provided by the Kanister framework.

Function Source Description Example
index Go built-in Access map keys with special characters {{ index .Object.data "my.key" }}
toString Kanister Convert bytes to string (required for Secret data) {{ .Phases.p.Secrets.s.Data.key | toString }}
toJson Kanister Convert value to JSON string {{ .Phases.p.Secrets.s.Data | toJson }}
toDate Kanister Parse a date string {{ toDate "2006-01-02" .Time }}
date Kanister Format a date {{ date "2006-01-02" .Time }}