New to KubeStash? Please start here.

BackupBlueprint

What is BackupBlueprint

KubeStash uses 1-1 mapping among BackupConfiguration and the target. So, whenever you want to backup a target(workload/PV/PVC/database), you have to create a BackupConfiguration object. This could become tiresome when you are trying to backup similar types of target and the BackupConfiguration has only slight differences. To mitigate this problem, KubeStash provides a way to specify a blueprint for this object via BackupBlueprint CRD.

A BackupBlueprint is a Kubernetes CustomResourceDefinition(CRD) which specifies a blueprint for BackupConfiguration in a Kubernetes native way.

You have to create only one BackupBlueprint for all similar types of workloads (i.e. Deployment, DaemonSet, StatefulSet etc.). Then, you just need to add some annotations in the target workload. KubeStash will automatically create respective BackupConfiguration object using the blueprint. In KubeStash parlance, we call this process as auto backup.

BackupBlueprint CRD Specification

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

A sample BackupBlueprint object to auto backup the volumes of workload is shown below,

apiVersion: core.kubestash.com/v1alpha1
kind: BackupBlueprint
metadata:
  name: sample-blueprint
  namespace: demo
spec:
  usagePolicy:
    allowedNamespaces: 
      from: All
  backupConfigurationTemplate:
    deletionPolicy: OnDelete
    backends:
    - name: gcs-backend
      storageRef:
        namespace: demo
        name: gcs-storage
      retentionPolicy:
        name: demo-retention
        namespace: demo
    sessions:
    - name: backup-every-five-minutes
      sessionHistoryLimit: 3
      scheduler: # CronJob specification
        schedule: "*/5 * * * *"
        jobTemplate:
          backoffLimit: 1
      repositories:
      - name: ${repoName}
        backend: gcs-backend
        directory: ${namespace}/${targetName}
        encryptionSecret:
          name: encrypt-secret
          namespace: demo
      addon:
        name: workload-addon
        tasks:
        - name: LogicalBackup
          params:
            paths: ${paths}
      retryConfig:
        maxRetry: 2
        delay: 1m

The sample BackupBlueprint that has been shown above can be used to backup Deployments, DaemonSets, StatefulSets. You only have to add some annotations to these workloads. For more details on how auto backup works in KubeStash, please visit here.

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

BackupBlueprint Spec

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

• usagePolicy : lets you control which namespaces are allowed to use the BackupBlueprint and which are not. If you refer to a BackupBlueprint from a restricted namespace, KubeStash operator will reject creating BackupConfiguration from it. You can use the usagePolicy to allow only the same namespace, a subset of namespaces, or all the namespaces to refer to the BackupBlueprint. If you don’t specify any usagePolicy, KubeStash will allow referencing the BackupBlueprint only from the namespace where the BackupBlueprint has been created.

Here is an example of spec.usagePolicy that limits referencing the BackupBlueprint only from the same namespace,

spec:
  usagePolicy:
    allowedNamespaces:
      from: Same

Here is an example of spec.usagePolicy that allows referencing the BackupBlueprint from only prod and staging namespaces,

spec:
  usagePolicy:
    allowedNamespaces:
      from: Selector
      selector:
        matchExpressions:
          - key: "kubernetes.io/metadata.name"
            operator: In
            values: ["prod","staging"]

Here is an example of spec.usagePolicy that allows referencing the BackupBlueprint from all namespaces,

spec:
  usagePolicy:
    allowedNamespaces:
      from: All

• backupConfigurationTemplate : specifies the blueprint for the BackupConfiguration that will be created for the respective target. It consists of the following fields:
  • namespace : specifies the namespace of the BackupConfiguration. The field is optional. If you don’t provide the namespace, then BackupConfiguration will be created in the BackupBlueprint namespace.
  • backends : specifies a list of storage references where the backed up data will be stored. The respective BackupStorages can be in a different namespace than the BackupConfiguration. However, it must be allowed by the usagePolicy of the BackupStorage to refer from this namespace. This field is optional, if you don’t provide any backend here, KubeStash will use the default BackupStorage for the namespace. If a default BackupStorage does not exist in the same namespace, then KubeStash will look for a default BackupStorage in other namespaces that allows using it from the BackupConfiguration namespace. Each backend has the following fields:

• sessions : specifies a list of session template for backup. You can use custom variables in your template then provide the variable value through annotations. Each session has the following fields:
  • name : specifies an identifier for this session. This name must be unique.
  • scheduler : specifies the configuration for backup triggering CronJob. To learn about the fields under scheduler, see Scheduler Spec.
  • hooks : specifies the backup hooks that should be executed before and/or after the backup. Hooks has two fields:
    • preBackup : specifies a list of hooks that will be executed before backup. To learn about the fields under preBackup, see HookInfo.
    • postBackup : specifies a list of hooks that will be executed after backup. To learn about the fields under postBackup, see HookInfo.
  • retryConfig : specifies the behavior of retry in case of a backup failure. RetryConfig has the following fields:
    • maxRetry : specifies the maximum number of times KubeStash should retry the backup/restore process. By default, KubeStash will retry only 1 time.
    • delay : The amount of time to wait before next retry. If you don’t specify this field, KubeStash will retry immediately. Format: 30s, 2m, 1h etc.
  • timeout : specifies the maximum duration of backup. BackupSession will be considered Failed if backup does not complete within this time limit. By default, KubeStash don’t set any timeout for backup.
  • sessionHistoryLimit : specifies how many backup Jobs and associate resources KubeStash should keep for debugging purpose. The default value is 1.
  • addon : specifies addon configuration that will be used to backup the target. Addon has the following fields:
    • name : specifies the name of the addon that will be used for the backup purpose.
    • tasks : specifies a list of backup tasks and their configuration parameters. To learn about the fields under task, see Task Reference.
    • containerRuntimeSettings : specifies runtime settings for the backup executor container. More information can be found here.
    • jobTemplate : specifies runtime configurations for the backup Job. More information can be found here.
  • repositories : specifies a list of repository information where the backed up data will be stored. KubeStash will create the respective Repository CRs using this information. Each repository consists of the following fields:
    • name : specifies the name of the Repository.
    • backend : specifies the name of the backend where this repository will be initialized. This should point to a backend name specified in .spec.backupConfigurationTemplate.backends section. For using a default backend, keep this field empty.
    • directory : specifies the path inside the backend where the backed up data will be stored.
    • encryptionSecret : refers to the Secret containing the encryption key which will be used to encode/decode the backed up data. You can refer to a Secret of a different namespace by providing name and namespace fields.
    • deletionPolicy : specifies what to do when you delete a Repository CR. The valid values for this field are:
      • Delete : This will delete just the Repository CR from the cluster but keep the backed up data in the remote backend. This is the default behavior.
      • WipeOut : This will delete the Repository CR as well as the backed up data from the backend.
• deletionPolicy : specifies whether the BackupConfiguration will be deleted on BackupBlueprint deletion. This field is optional, if you don’t provide deletionPolicy, then BackupConfiguration will not be deleted on BackupBlueprint deletion. The only valid value for this field is OnDelete which specifies the BackupConfiguration will be deleted on BackupBlueprint deletion.

Next Steps

• Learn how to use BackupBlueprint for auto backup of workloads data from here.
• Learn how to use BackupBlueprint for auto backup of stand-alone PVC from here.