Kanister Function Reference

A Kanister function executes a single operation inside a blueprint phase. The func field in a phase selects the function. The args field passes arguments to it. All string values in args support template variables.

This page covers the Kanister functions available in the Kasten context. For the full upstream function list, see the Kanister documentation.

---

KubeExec

Executes a command inside an existing container. This function is similar to kubectl exec. Use KubeExec when the command needs the application's running environment, such as database credentials, Unix sockets, or mounted volumes.

KubeExec Arguments

Argument	Type	Required	Default	Description
namespace	string	Yes		Namespace of the target pod
pod	string	Yes		Name of the target pod
container	string	No	First container	Container name. Defaults to the first container. Specify this value when the pod has multiple containers.
command	[]string	Yes		Command to execute as a string array

KubeExec Outputs

KubeExec captures stdout from the executed command. The Kanister controller parses stdout for structured output markers. Use kando output <key> <value> inside the command to write these markers. Access outputs from subsequent phases through .Phases.<phaseName>.Output.<key>.

KubeExec Namespace Behavior

The function executes a command inside an existing pod, similar to kubectl exec. The namespace argument identifies where that pod runs.

KubeExec Example

This example uses .StatefulSet.Pods to select a pod by index. The typed variables (.StatefulSet.*, .Deployment.*) provide pod and container lists that .Object does not include. Kasten populates typed variables only for StatefulSet and Deployment resources. For all other resources, use .Object to access resource metadata.

- func: KubeExec
  name: quiesceDB
  args:
    namespace: "{{ .StatefulSet.Namespace }}"
    pod: "{{ index .StatefulSet.Pods 0 }}"
    container: postgres
    command:
      - sh
      - -c
      - |
        psql -U postgres -c "SELECT pg_start_backup('kasten');"
        kando output backupStarted "true"

---

KubeTask

Creates a temporary pod, executes a command, and deletes the pod after completion. Use KubeTask when the command needs a specific tool image or isolation from the application container.

KubeTask does not natively mount existing PVCs. Although podOverride can add volume mounts, the recommended approach for running a command against data on an existing PVC is to use these functions together:

1. KubeOps to create a pod with the PVC mounted
2. WaitV2 to wait for the pod to be ready
3. KubeExec to execute inside the pod

KubeTask Arguments

Argument	Type	Required	Default	Description
image	string	Yes		Container image for the temporary pod
command	[]string	Yes		Command to execute as a string array
namespace	string	No	Kasten namespace	Namespace where the temporary pod runs. Defaults to the Kasten namespace (default kasten-io).
podOverride	map[string]any	No		Pod spec overrides (for example, serviceAccountName, nodeSelector, tolerations)
podAnnotations	map[string]string	No		Annotations for the temporary pod
podLabels	map[string]string	No		Labels for the temporary pod

KubeTask Outputs

KubeTask captures stdout from the temporary pod. The Kanister controller parses stdout for structured output markers. Use kando output <key> <value> inside the command to write these markers. Access outputs from subsequent phases through .Phases.<phaseName>.Output.<key>.

KubeTask Namespace Behavior

When namespace is specified, the temporary pod runs in that namespace. When omitted, the pod runs in the Kanister controller namespace (the Kasten namespace, default kasten-io).

When the target namespace differs from the Kasten namespace, the pod uses the default service account in that target namespace. Override the service account through podOverride if needed.

Choose the namespace based on what the command does:

• Kubernetes API operations (patching CRs, scaling workloads): Run in the Kasten namespace. The pod inherits the Kasten executor service account, which has cluster-admin permissions. Use podOverride to set a more restrictive service account if needed.
• Network calls to in-cluster services (database HTTP APIs, gRPC): Run in the application namespace. Network policies may block cross-namespace traffic.

KubeTask Example

- func: KubeTask
  name: checkClusterState
  args:
    namespace: "{{ .Object.metadata.namespace }}"
    image: my-tools-image:latest
    podOverride:
      serviceAccountName: my-blueprint-sa
    command:
      - sh
      - -c
      - |
        kubectl get pods -n "{{ .Object.metadata.namespace }}" -l app=mydb -o name
        kando output podCount "$(kubectl get pods -n {{ .Object.metadata.namespace }} -l app=mydb --no-headers | wc -l)"

---

KubeOps

Creates, patches, or deletes Kubernetes resources. Use KubeOps to manage temporary resources such as pods, PVCs, or Jobs during blueprint execution.

KubeOps Arguments

Argument	Type	Required	Default	Description
operation	string	Yes		Operation to perform: create, patch, or delete
namespace	string	No	default	Namespace for the operation. The resource spec can override this value.
spec	string	No		YAML manifest of the resource. Required for create and patch.
objectReference	map[string]any	No		Reference to an existing resource. Required for patch and delete.

ObjectReference fields:

Field	Type	Required	Description
apiVersion	string	Yes	API version only (for example, v1). Do not include the group.
group	string	No	API group (for example, apps). Omit for core API resources such as pods, configmaps, and secrets.
resource	string	Yes	Plural resource name (for example, pods, deployments)
name	string	Yes	Resource name
namespace	string	No	Resource namespace

KubeOps Outputs

KubeOps returns an ObjectReference for the affected resource. Access the fields from subsequent phases:

• .Phases.<phaseName>.Output.apiVersion
• .Phases.<phaseName>.Output.group
• .Phases.<phaseName>.Output.resource
• .Phases.<phaseName>.Output.name
• .Phases.<phaseName>.Output.namespace

KubeOps Namespace Behavior

For create operations, the namespace in the resource spec takes priority over the namespace argument. For delete operations, the objectReference.namespace field takes priority.

KubeOps Operations

Create: Applies the YAML manifest from spec to create a new resource. Returns an ObjectReference for the created resource.

Patch: Applies a strategic merge patch from spec to the resource identified by objectReference.

Delete: Deletes the resource identified by objectReference. The function waits for the resource to be fully removed before it returns.

KubeOps Example

- func: KubeOps
  name: createTempPVC
  args:
    operation: create
    namespace: "{{ .Object.metadata.namespace }}"
    spec: |-
      apiVersion: v1
      kind: PersistentVolumeClaim
      metadata:
        name: "{{ .Object.metadata.name }}-dump"
      spec:
        accessModes: ["ReadWriteOnce"]
        resources:
          requests:
            storage: 10Gi

Delete the resource in a subsequent phase or defer phase:

- func: KubeOps
  name: deleteTempPVC
  args:
    operation: delete
    objectReference:
      apiVersion: "{{ .Phases.createTempPVC.Output.apiVersion }}"
      group: "{{ .Phases.createTempPVC.Output.group }}"
      resource: "{{ .Phases.createTempPVC.Output.resource }}"
      name: "{{ .Phases.createTempPVC.Output.name }}"
      namespace: "{{ .Phases.createTempPVC.Output.namespace }}"

---

WaitV2

Waits for a Kubernetes resource to reach a desired state. The function polls the resource until a Go template condition evaluates to true or the timeout expires.

WaitV2 Arguments

Argument	Type	Required	Description
timeout	string	Yes	Maximum wait duration in Go duration format (for example, 5m, 60s, 1h)
conditions	map[string]any	Yes	Condition groups: anyOf and allOf. Each group contains an array of Condition objects.

Condition fields:

Field	Type	Required	Description
condition	string	Yes	Go template that evaluates to true or false against the resource object
objectReference	map[string]any	Yes	Reference to the Kubernetes resource to evaluate

The objectReference in a Condition uses the same fields as the KubeOps ObjectReference: apiVersion, group, resource, name, and namespace.

info

The apiVersion field contains the version only (for example, v1), not the combined group/version string. Specify the API group separately in the group field.

• Core resources (Pods, PVCs): apiVersion: v1 with no group
• apps/v1 resources: apiVersion: v1, group: apps
• CRDs: apiVersion: v1, group: elasticsearch.k8s.elastic.co

WaitV2 Condition Logic

• anyOf: Succeeds when at least one condition evaluates to true.
• allOf: Succeeds when all conditions evaluate to true simultaneously.

Both groups can appear in the same conditions block. The function succeeds when all specified groups are satisfied.

WaitV2 Outputs

WaitV2 does not produce outputs. Use it to gate subsequent phases on a resource state.

WaitV2 Namespace Behavior

Each Condition specifies its target resource through the objectReference. Include namespace for namespaced resources. Omit namespace for cluster-scoped resources.

WaitV2 Go Template Conditions

Conditions use Go template syntax evaluated against the full Kubernetes resource object. The resource is the root context ($). The template must return the string true or false.

Validate conditions with kubectl before using them in a blueprint:

kubectl get deploy -n $NAMESPACE $DEPLOY_NAME \
  -o go-template='{{ $available := false }}{{ range $condition := $.status.conditions }}{{ if and (eq .type "Available") (eq .status "True") }}{{ $available = true }}{{ end }}{{ end }}{{ $available }}'

WaitV2 Example

- func: WaitV2
  name: waitForReady
  args:
    timeout: 5m
    conditions:
      anyOf:
        - condition: '{{ $available := false }}{{ range $condition := $.status.conditions }}{{ if and (eq .type "Available") (eq .status "True") }}{{ $available = true }}{{ end }}{{ end }}{{ $available }}'
          objectReference:
            apiVersion: v1
            group: apps
            resource: deployments
            name: "{{ .Object.metadata.name }}"
            namespace: "{{ .Object.metadata.namespace }}"

---

ScaleWorkload

Scales a Kubernetes workload to a specified replica count. The function waits for the workload to reach the target state before it returns. It supports Deployments, StatefulSets, and DeploymentConfigs (OpenShift).

ScaleWorkload Arguments

Argument	Type	Required	Default	Description
replicas	int	Yes		Target replica count
namespace	string	No	From template context	Namespace of the workload. Falls back to the bound resource namespace.
name	string	No	From template context	Name of the workload. Falls back to the bound resource name.
kind	string	No	From template context	Workload type: StatefulSet, Deployment, or DeploymentConfig (case-insensitive). Falls back to the bound resource kind.
waitForReady	bool	No	true	Wait for the workload to reach the target replica count before returning

When namespace, name, and kind are omitted, the function uses the resource context from the blueprint binding, such as .StatefulSet or .Deployment.

ScaleWorkload Outputs

Output Key	Type	Description
originalReplicaCount	int	Replica count before the scale operation

Access the original count from subsequent phases through .Phases.<phaseName>.Output.originalReplicaCount.

ScaleWorkload Namespace Behavior

When namespace is provided, the function targets the workload in that namespace. When omitted, the function resolves the namespace from the template context of the bound resource.

ScaleWorkload Example

Scale down before a data operation, then restore the original replica count:

- func: ScaleWorkload
  name: scaleDown
  args:
    namespace: "{{ .Object.metadata.namespace }}"
    name: "{{ .Object.metadata.name }}"
    kind: Deployment
    replicas: 0

- func: ScaleWorkload
  name: scaleUp
  args:
    namespace: "{{ .Object.metadata.namespace }}"
    name: "{{ .Object.metadata.name }}"
    kind: Deployment
    replicas: "{{ .Phases.scaleDown.Output.originalReplicaCount }}"

---

Additional Functions

Kanister provides additional functions beyond those listed on this page:

• KubeExecAll — Executes a command across multiple pods and containers in parallel
• MultiContainerRun — Creates a temporary pod with two containers connected through a shared volume. Although general-purpose, this function is typically used to stream data to the location profile through kando location push. This makes the blueprint responsible for data movement and bypasses Kasten features such as incremental backups and immutability. The recommended approach is to write dump data to a PVC that Kasten snapshots.
• PrepareData — Creates a temporary pod that mounts PVCs and executes a data manipulation command

For details on these functions, see the Kanister documentation.

warning

Do not use BackupData, RestoreData, DeleteData, CopyVolumeData, or their variants in Kasten blueprints. These standalone Kanister data mover functions conflict with the Kasten data management pipeline. Kasten manages data movement through its own internal mechanisms.