You are looking at the documentation of a prior release. To read the documentation of the latest release, please visit here.

New to Stash? Please start here.


What is BackupConfiguration

A BackupConfiguration is a Kubernetes CustomResourceDefinition(CRD) which specifies the backup target, parameters(schedule, retention policy etc.) and a Repository object that holds snapshot storage information in a Kubernetes native way.

You have to create a BackupConfiguration object for each backup target. A backup target can be a workload, database or a PV/PVC.

BackupConfiguration CRD Specification

Like any official Kubernetes resource, a BackupConfiguration has TypeMeta, ObjectMeta and Spec sections. However, unlike other Kubernetes resources, it does not have a Status section.

A sample BackupConfiguration object to backup the volumes of a Deployment is shown below:

kind: BackupConfiguration
  name: demo-backup
  namespace: demo
  driver: Restic
    name: local-repo
  # task:
  #   name: workload-backup # task field is not required for workload data backup but it is necessary for database backup.
  schedule: "* * * * *" # backup at every minutes
  paused: false
  backupHistoryLimit: 3
    alias: app-data
      apiVersion: apps/v1
      kind: Deployment
      name: stash-demo
    - /source/data
    - /source/data/not-important.txt
    - /source/data/*.html
    - /source/data/tmp/*
    - name: source-data
      mountPath: /source/data
          - /bin/sh
          - -c
          - echo "Sample PreBackup hook demo"
      containerName: my-app-container
          - /bin/sh
          - -c
          - echo "Sample PostBackup hook demo"
      containerName: my-app-container
          memory: 256M
          memory: 256M
        runAsUser: 2000
        runAsGroup: 2000
        adjustment: 5
        class: 2
        classData: 4
      - name:  my-private-registry-secret
      serviceAccountName: my-backup-svc
    medium: "Memory"
    sizeLimit: "2Gi"
    disableCaching: false
    name: 'keep-last-5'
    keepLast: 5
    prune: true

Here, we are going to describe the various sections of BackupConfiguration crd.

BackupConfiguration Spec

A BackupConfiguration object has the following fields in the spec section.


spec.driver indicates the mechanism used to backup a target. Currently, Stash supports Restic and VolumeSnapshotter as drivers. The default value of this field is Restic.

Driver Usage
Restic Used to backup workload data, persistent volumes data and databases. It uses restic to backup the target.
VolumeSnapshotter Used to take snapshot of PersistentVolumeClaims of a targeted workload. It leverages Kubernetes VolumeSnapshot crd and CSI driver to snapshot the PVCs. field indicates the target for backup runs. This field consists of the following sub-fields:

  • : The alias is used as an identifer of the backed up data in the backend. This is particularly useful for BackupBatch where multiple targets are backed up into a single repository.

  • : refers to the target of backup. You have to specify apiVersion, kind and name of the target. Stash will use this information to inject a sidecar to the target or to create a backup job for it.

  • : specifies list of file paths to backup.

  • : Specifies a list of pattern for the files that should be ignored during backup. Stash will not backup the files that matches these patterns.

  • : are the list of volumes and their mountPaths that contain the target file paths. Stash will mount these volumes inside a sidecar container or a backup job.

  • indicates the VolumeSnapshotClass to use for volume snasphotting. Use this field only if spec.driver is set to VolumeSnapshotter.

spec.repository indicates the Repository crd name that holds necessary backend information where the backed up data will be stored.


spec.schedule is a cron expression that specifies the schedule of backup. Stash creates a Kubernetes CronJob with this schedule.


spec.backupHistoryLimit specifies the number of BackupSession and its associate resources (Job, PVC etc.) to keep for debugging purposes. The default value of this field is 1. Stash will cleanup the old BackupSession and it’s associate resources after each backup session according to backupHistoryLimit.


spec.task specifies the name and parameters of the Task crd to use to backup the target.

  • indicates the name of the Task to use for this backup process.
  • spec.task.params: spec.task.params is an array of custom parameters to use to configure the task.

spec.task section is not required for backing up workload data (i.e. Deployment, DaemonSet, StatefulSet etc.). However, it is necessary for backing up databases and stand-alone PVCs.


spec.paused can be used as enable/disable switch for backup. If it is set true, Stash will not take any backup of the target specified by this BackupConfiguration.


spec.hooks allows performing some actions before and after the backup process. You can send HTTP requests to a remote server via httpGet or httpPost hooks. You can check whether a TCP socket is open using tcpSocket hook. You can also execute some commands into your application pod using exec hook.

  • spec.hooks.preBackup: spec.hooks.preBackup hooks are executed before the backup process.
  • spec.hooks.postBackup: spec.hooks.postBackup hooks are executed after the backup process.

For more details on how hooks work in Stash and how to configure different types of hook, please visit here.


spec.runtimeSettings allows to configure runtime environment for the backup sidecar or job. You can specify runtime settings at both pod level and container level.

  • spec.runtimeSettings.container

    spec.runtimeSettings.container is used to configure the backup sidecar/job at container level. You can configure the following container level parameters:

Field Usage
resources Compute resources required by the sidecar container or backup job. To learn how to manage resources for containers, please visit here.
livenessProbe Periodic probe of backup sidecar/job container’s liveness. Container will be restarted if the probe fails.
readinessProbe Periodic probe of backup sidecar/job container’s readiness. Container will be removed from service endpoints if the probe fails.
lifecycle Actions that the management system should take in response to container lifecycle events.
securityContext Security options that backup sidecar/job’s container should run with. For more details, please visit here.
nice Set CPU scheduling priority for backup process. For more details about nice, please visit here.
ionice Set I/O scheduling class and priority for backup process. For more details about ionice, please visit here.
env A list of the environment variables to set in the sidecar container or backup job’s container.
envFrom This allows to set environment variables to the container that will be created for this function from a Secret or ConfigMap.
  • spec.runtimeSettings.pod

    spec.runtimeSettings.pod is used to configure backup job in pod level. You can configure the following pod level parameters,

Field Usage
serviceAccountName Name of the ServiceAccount to use for the backup job. Stash sidecar will use the same ServiceAccount as the target workload.
nodeSelector Selector which must be true for backup job pod to fit on a node.
automountServiceAccountToken Indicates whether a service account token should be automatically mounted into the backup pod.
nodeName nodeName is used to request to schedule backup job’s pod onto a specific node.
securityContext Security options that backup job’s pod should run with. For more details, please visit here.
imagePullSecrets A list of secret names in the same namespace that will be used to pull image from private Docker registry. For more details, please visit here.
affinity Affinity and anti-affinity to schedule backup job’s pod on a desired node. For more details, please visit here.
schedulerName Name of the scheduler that should dispatch the backup job.
tolerations Taints and Tolerations to ensure that backup job’s pod is not scheduled in inappropriate nodes. For more details about toleration, please visit here.
priorityClassName Indicates the backup job pod’s priority class. For more details, please visit here.
priority Indicates the backup job pod’s priority value.
readinessGates Specifies additional conditions to be evaluated for Pod readiness. For more details, please visit here.
runtimeClassName RuntimeClass is used for selecting the container runtime configuration. For more details, please visit here
enableServiceLinks EnableServiceLinks indicates whether information about services should be injected into pod’s environment variables.


Stash mounts an emptyDir for holding temporary files. It is also used for caching for faster backup performance. You can configure the emptyDir using spec.tempDir section. You can also disable caching using this field. The following fields are configurable in spec.tempDir section:

  • spec.tempDir.medium : Specifies the type of storage medium should back this directory.
  • spec.tempDir.sizeLimit : Maximum limit of storage for this volume.
  • spec.tempDir.disableCaching : Disable caching while backup. This may negatively impact backup performance. This is set to false by default.


For some targets (i.e. some databases), Stash can’t directly pipe the dumped data to the uploading process. In this case, it has to store the dumped data temporarily before uploading to the backend. spec.interimVolumeTemplate specifies a PVC template for holding those data temporarily. Stash will create a PVC according to the template and use it to store the data temporarily. This PVC will be deleted according to the spec.backupHistoryLimit.

Note that the usage of this field is different than spec.tempDir which is used for caching purpose. Stash has introduced this field because the emptyDir volume that is used for spec.tempDir does not play nice with large databases( i.e. 100Gi database). Also, it provides debugging capability as Stash keeps it until it hits the limit specified in spec.backupHistoryLimit.


spec.retentionPolicy specifies the policy to follow for cleaning old snapshots. Following options are available to configure retention policy:

Policy Value restic forget command flag Description
name string Name of retention policy. You can provide any name.
keepLast integer –keep-last n Never delete the n last (most recent) snapshots.
keepHourly integer –keep-hourly n For the last n hours in which a snapshot was made, keep only the last snapshot for each hour.
keepDaily integer –keep-daily n For the last n days which have one or more snapshots, only keep the last one for that day.
keepWeekly integer –keep-weekly n For the last n weeks which have one or more snapshots, only keep the last one for that week.
keepMonthly integer –keep-monthly n For the last n months which have one or more snapshots, only keep the last one for that month.
keepYearly integer –keep-yearly n For the last n years which have one or more snapshots, only keep the last one for that year.
keepTags array –keep-tag Keep all snapshots which have all tags specified by this option (can be specified multiple times).
prune bool –prune If set true, Stash will cleanup unreferenced data from the backend.
dryRun bool –dry-run Stash will not remove anything but print which snapshots would be removed.

BackupConfiguration Status

A BackupConfiguration object has the following fields in the status section.

  • observedGeneration : The most recent generation observed by the BackupConfiguration controller.

  • conditions : The spec.conditions shows current backup setup condition for this BackupConfiguration. The following conditions are set by the Stash operator:

Condition Type Usage
RepositoryFound Indicates whether the respective Repository object was found or not.
BackendSecretFound Indicates whether the respective backend secret was found or not.
CronJobCreated Indicates whether the backup triggering CronJob was created or not.

Next Steps

  • Learn how to configure BackupConfiguration to backup workloads data from here.
  • Learn how to configure BackupConfiguration to backup databases from here.
  • Learn how to configure BackupConfiguration to backup stand-alone PVC from here.