Skip to main content
Version: 8.5.9 (latest)

Reserved Action Names and Timeouts

Kasten calls blueprint actions at fixed points during backup, restore, and delete operations. For resource-bound blueprints (assigned through an annotation or BlueprintBinding), the action name must match one of the reserved names listed on this page — Kasten silently ignores any other names. For action hooks configured on a policy, any action name is valid. The policy maps the hook to a specific execution point.

For details on how actions fit into the full operation sequence, see the Phase Lifecycle Reference.

Reserved Action Names​

Backup Action Names​

Action Name When Kasten Calls It Typical Use
backupPrehook Before PVC snapshots start for the bound resource Quiesce the database or create a dump on a PVC
backupPosthook After PVC snapshots complete for the bound resource Resume the database after quiesce
backup Instead of PVC snapshots (logical blueprint) Blueprint manages data movement. See Logical Blueprints.

Restore Action Names​

Action Name When Kasten Calls It Typical Use
restorePosthook After PVC and resource restoration completes Post-restore initialization or cache warming
restore Instead of PVC restoration (logical blueprint) Blueprint manages data restoration. See Logical Blueprints.

Delete Action Name​

Action Name When Kasten Calls It Typical Use
delete When Kasten retires (deletes) a restore point Clean up external backups. See Delete Action Context.

Timeout Configuration​

Each action has a default timeout. If the action does not complete within the timeout, Kasten marks it as failed.

Action Name Helm Value Default
backupPrehook timeout.blueprintHooks 20 minutes
backupPosthook timeout.blueprintHooks 20 minutes
restorePosthook timeout.blueprintHooks 20 minutes
backup timeout.blueprintBackup 45 minutes
restore timeout.blueprintRestore 600 minutes
delete timeout.blueprintDelete 45 minutes

Override timeouts in the Helm values file. Values are in minutes.

timeout:
  blueprintBackup: 45
  blueprintRestore: 600
  blueprintDelete: 45
  blueprintHooks: 20

All hook actions (backupPrehook, backupPosthook, restorePosthook) share the same timeout.blueprintHooks value.

Resource-Bound Actions and Action Hooks​

Kasten supports two ways to invoke blueprint actions. Both can coexist in the same backup policy.

Resource-Bound Actions​

Resource-bound actions fire through an annotation or BlueprintBinding on a Kubernetes resource. Kasten calls reserved action names at fixed points in its operation lifecycle.

Property Value
Scope Per resource
Trigger Annotation or BlueprintBinding
Reserved names only Yes. Non-reserved names are silently ignored.
Template context .Object, .StatefulSet.*, .Deployment.* (resource metadata)
.Namespace.Name Not available. Use .Object.metadata.namespace.
Artifacts Available through outputArtifacts and inputArtifactNames
Location profile Available through .Profile when a location profile for Kanister actions is configured on the policy.
info

To assign a blueprint to a workload without a BlueprintBinding, add the kanister.kasten.io/blueprint annotation to the workload. Set the value to the blueprint name. The blueprint must exist in the Kasten namespace (kasten-io by default). If both an annotation and a BlueprintBinding match the same resource, the BlueprintBinding takes priority.

Action Hooks​

Action hooks fire through the hook specification on a BackupAction, RestoreAction, or ExportAction. ImportAction does not support hooks.

Property Value
Scope Per namespace (fires once per namespace in the policy)
Trigger preHook, onSuccess, or onFailure in the action spec
Reserved names only No. Any action name is valid.
Template context .Namespace.Name (namespace only, unless a subject resource is set)
.Object Not available unless the hook specifies a subject (a target resource such as a StatefulSet)
Artifacts The preHook hook's outputArtifacts pass as inputArtifacts to the onSuccess and onFailure hooks. These artifacts do not persist into the restore point. See Kanister Execution Hooks.
Location profile Not available

Comparison​

Resource-Bound Action Hook
Use case Quiesce, resume, dump, restore Namespace metadata, notifications, cleanup
Fires per Resource Namespace
Blueprint assignment Annotation or BlueprintBinding Action hooks on a policy
PVC created during action Not discovered (PVC discovery runs first) Discovered if created in preHook
info

PVC discovery runs before resource-bound backupPrehook actions. A PVC created during backupPrehook is not included in the restore point. To create a temporary PVC that Kasten snapshots, use a preHook action hook instead.

ActionSet Lifecycle​

When Kasten executes a blueprint action, it creates a Kanister ActionSet CR in the Kasten namespace. The ActionSet tracks execution progress and captures phase outputs.

In standalone Kanister, users create and manage ActionSets directly. In the Kasten context, Kasten handles this automatically:

  1. Kasten creates the ActionSet before executing the action.
  2. Kasten monitors the ActionSet until all phases complete.
  3. Kasten deletes the ActionSet after execution finishes.

Blueprint authors do not create, modify, or delete ActionSets. The ActionSet is an internal mechanism between Kasten and the Kanister execution engine.

Logical Blueprints​

When a blueprint defines a backup action, Kasten calls that action instead of taking PVC snapshots for the bound resource. Similarly, a restore action replaces PVC restoration.

Kasten still captures PVC manifests in the restore point, but the volume data is empty. The logical blueprint's restore action is responsible for seeding the data during recovery.

Logical Blueprint Limitations​

Logical blueprints carry the following limitations compared to snapshot-based blueprints:

  • No incremental backups. The blueprint writes a full backup to local disk on every run, so backup duration grows with data size. The Kopia repository deduplicates data on the backup target, but the local write is always full. As a guideline, logical blueprints remain practical for databases up to approximately 50 GiB.
  • Custom image required. The kando CLI is only distributed inside gcr.io/kasten-images/kanister-tools. Logical blueprints that use kando location push must run in a container that also has the database dump tools. You must build and maintain a combined image.
  • Opaque artifacts. You cannot browse, verify, or manually restore from data written by kando location push. Debugging a failed restore requires replaying the entire blueprint.
  • Data mover selection ignored. kando location push always uses Kopia internally. It does not honor the policy's data mover selection. If your organization requires VBR, a logical blueprint silently bypasses it.
  • Limited immutability enforcement. Kasten cannot re-trigger bucket protection for blueprint artifacts. Backups older than the bucket's protection period can be deleted.
warning

Prefer snapshot-based blueprints (backupPrehook and backupPosthook) over logical blueprints (backup and restore). Snapshot-based blueprints preserve Kasten features such as incremental backups, deduplication, and immutability.

Use logical blueprints only when PVC snapshots are not viable, such as managed databases or vendor operator backup APIs.

Delete Action Context​

The delete action runs when Kasten retires a restore point. The execution context differs from backup and restore actions.

Property Behavior
Namespace context Kasten namespace, not the application namespace
Application object May no longer exist. The application namespace may have been deleted before the restore point is retired.
.Namespace.Name Resolves to the Kasten namespace
.ArtifactsIn Available if the backup action declared outputArtifacts

Store backup identifiers in outputArtifacts during the backup action. Retrieve them through .ArtifactsIn in the delete action to clean up external resources. 

actions:
  backup:
    outputArtifacts:
      backupMeta:
        keyValue:
          backupId: "{{ .Phases.triggerBackup.Output.backupId }}"
    phases:
      - func: KubeTask
        name: triggerBackup
        args:
          namespace: "{{ .Object.metadata.namespace }}"
          image: my-tools-image:latest
          command:
            - sh
            - -c
            - |
              # Trigger external backup and store its identifier
              kando output backupId "$BACKUP_ID"

  delete:
    inputArtifactNames:
      - backupMeta
    phases:
      - func: KubeTask
        name: cleanupExternalBackup
        args:
          namespace: "{{ .Namespace.Name }}"
          image: my-tools-image:latest
          command:
            - sh
            - -c
            - |
              BACKUP_ID="{{ .ArtifactsIn.backupMeta.KeyValue.backupId }}"
              # Call external API to delete the backup

Integrated (Built-in) Blueprints​

warning

Kasten plans to deprecate built-in blueprints in a future release. Replace them with user-managed Blueprint CRs and BlueprintBindings for full visibility and control over blueprint logic.

Kasten includes three built-in blueprints for managed data services. Kasten creates these as Blueprint CRs automatically when it discovers the corresponding workload types.

Blueprint Workload Type Trigger
K8ssandra CassandraDatacenter CR Automatic when a backup includes K8ssandra CRs
Crunchy PGO PostgresCluster CR Automatic when a backup includes PGO CRs
RDS Postgres ConfigMap with annotation Opt-in via kanister.kasten.io/rds: rds-postgres annotation on a ConfigMap

Disabling Built-in Blueprints​

Disable the K8ssandra and Crunchy PGO blueprints through the Helm value: 

kanister:
  managedDataServicesBlueprintsEnabled: false

This value does not affect the RDS Postgres blueprint. To disable RDS Postgres, remove the kanister.kasten.io/rds: rds-postgres annotation from the ConfigMap.