Skip to content

Reference: Velero Annotations

We run a central Velero instance that backs up your namespace. You do not create Velero Backup, Schedule or Restore resources yourself. Instead, you control how Velero treats your workloads by adding annotations and labels to your own resources. With them you can include persistent volume data in the backup, exclude resources from the backup, and run commands in your containers before and after a backup or after a restore.

This page documents Velero 1.18.4.

Annotation or label prefix Purpose
backup.velero.io/backup-volumes, backup.velero.io/backup-volumes-excludes Select which pod volumes Velero backs up at file-system level.
velero.io/exclude-from-backup Exclude a resource from the backup.
pre.hook.backup.velero.io/*, post.hook.backup.velero.io/* Run a command in a container before or after Velero backs up the pod.
init.hook.restore.velero.io/* Add an init container to the pod when Velero restores it.
post.hook.restore.velero.io/* Run a command in a container after Velero restores the pod.

Example

The following StatefulSet includes the www volume in the backup and flushes pending writes to disk before Velero copies the volume data. The ConfigMap holds generated data that you do not want restored, so it carries the exclusion label.

apiVersion: apps/v1
kind: StatefulSet
metadata:
  name: web
  namespace: my-namespace
spec:
  selector:
    matchLabels:
      app: nginx
  serviceName: "nginx"
  replicas: 2
  template:
    metadata:
      labels:
        app: nginx
        netic.dk/network-ingress: "contour"
      annotations:
        # Volume name from the pod spec, here the volumeClaimTemplates name
        backup.velero.io/backup-volumes: www
        pre.hook.backup.velero.io/container: nginx
        pre.hook.backup.velero.io/command: '["/bin/sh", "-c", "sync"]'
        pre.hook.backup.velero.io/on-error: Fail
        pre.hook.backup.velero.io/timeout: 1m
    spec:
      securityContext:
        runAsUser: 1000
        runAsGroup: 3000
        fsGroup: 2000
      containers:
        - name: nginx
          image: nginxinc/nginx-unprivileged:1.20
          ports:
            - containerPort: 8080
              name: http
          volumeMounts:
            - name: www
              mountPath: /usr/share/nginx/html
          securityContext:
            allowPrivilegeEscalation: false
            capabilities:
              drop:
                - all
  volumeClaimTemplates:
    - metadata:
        name: www
      spec:
        accessModes: ["ReadWriteOnce"]
        storageClassName: "vsphere-sc"
        resources:
          requests:
            storage: 1Gi
---
apiVersion: v1
kind: ConfigMap
metadata:
  name: web-cache
  namespace: my-namespace
  labels:
    velero.io/exclude-from-backup: "true"
data:
  generated: "..."

Where to Put Annotations

Velero reads the volume and hook annotations from the pod. If a controller such as a Deployment or StatefulSet manages your pods, put the annotations in the pod template (spec.template.metadata.annotations). Annotations on the Deployment or StatefulSet object itself have no effect.

The exclusion label works on any resource. Velero reads it from the resource it is about to back up, so put it on the object you want to exclude.

Annotation and label values are strings. Quote values such as "true" in YAML.

Volume Selection

Velero backs up the content of pod volumes with File System Backup (FSB). FSB copies the files of a mounted volume to the backup storage. Velero discovers which volumes to copy in one of two modes:

  • Opt-in. Velero copies only the volumes you list in backup.velero.io/backup-volumes. This is the upstream default.
  • Opt-out. Velero copies every pod volume except the ones you list in backup.velero.io/backup-volumes-excludes.

The mode is a setting on the Velero backup, not on your pod. See Platform Notes for the mode on Contain Platform.

Annotation Applies to Value Description
backup.velero.io/backup-volumes Pod (pod template) Comma-separated list of volume names, for example www,data Volumes to include in FSB in opt-in mode. Use the volume names from spec.volumes in the pod spec. For a StatefulSet, the volume name is the metadata.name of the entry in volumeClaimTemplates, not the name of the generated PersistentVolumeClaim (such as www-web-0). Velero ignores this annotation in opt-out mode.
backup.velero.io/backup-volumes-excludes Pod (pod template) Comma-separated list of volume names Volumes to skip in opt-out mode. Velero ignores this annotation in opt-in mode.

In opt-out mode, Velero always skips these volume types, so you do not need to list them:

  • hostPath volumes.
  • Volumes that mount Secrets, ConfigMaps, or the default service account token.
  • Projected volumes.

Velero backs up the Secret and ConfigMap objects themselves as Kubernetes resources.

Resource Exclusion

Label Applies to Value Description
velero.io/exclude-from-backup Any namespaced resource "true" Velero does not include the resource in the backup, even if it matches the backup's label selector. Any other value has no effect.

Backup Hooks

A backup hook runs a command in a running container of a pod while Velero backs up that pod. A pre hook runs before Velero backs up the pod and its volumes. A post hook runs after Velero has backed up the pod and its related items. Use pre hooks to quiesce an application, for example to flush buffers or lock tables, and post hooks to resume it.

Velero groups related items into an ItemBlock and backs them up together. If an ItemBlock contains more than one pod, for example pods that share a ReadWriteMany volume, Velero runs the pre hooks of all those pods, backs up the items, and then runs all post hooks.

Pre Hooks

Annotation Applies to Value Description
pre.hook.backup.velero.io/command Pod (pod template) Command as a JSON array, for example '["/usr/bin/uname", "-a"]' Required to define the hook. The command to run. Velero does not run it in a shell.
pre.hook.backup.velero.io/container Pod (pod template) Container name Optional. The container to run the command in. Defaults to the first container in the pod.
pre.hook.backup.velero.io/on-error Pod (pod template) Fail or Continue Optional. What to do if the command exits with a non-zero code. Defaults to Fail. Velero ignores any other value.
pre.hook.backup.velero.io/timeout Pod (pod template) Duration, for example 30s or 2m Optional. How long to wait for the command. Velero treats a command that exceeds the timeout as failed. Defaults to 30s.

Post Hooks

Annotation Applies to Value Description
post.hook.backup.velero.io/command Pod (pod template) Command as a JSON array Required to define the hook. The command to run. Velero does not run it in a shell.
post.hook.backup.velero.io/container Pod (pod template) Container name Optional. The container to run the command in. Defaults to the first container in the pod.
post.hook.backup.velero.io/on-error Pod (pod template) Fail or Continue Optional. What to do if the command exits with a non-zero code. Defaults to Fail. Velero ignores any other value.
post.hook.backup.velero.io/timeout Pod (pod template) Duration, for example 30s or 2m Optional. How long to wait for the command. Velero treats a command that exceeds the timeout as failed. Defaults to 30s.

Backup Hook Example

The following pod template annotations lock MySQL tables before the backup and unlock them afterwards. The command starts /bin/sh so that it can read the MYSQL_ROOT_PASSWORD environment variable of the container.

  template:
    metadata:
      annotations:
        backup.velero.io/backup-volumes: data
        pre.hook.backup.velero.io/container: mysql
        pre.hook.backup.velero.io/command: >-
          ["/bin/sh", "-c",
          "mysql --password=$MYSQL_ROOT_PASSWORD -e 'FLUSH TABLES WITH READ LOCK'"]
        pre.hook.backup.velero.io/timeout: 2m
        post.hook.backup.velero.io/container: mysql
        post.hook.backup.velero.io/command: >-
          ["/bin/sh", "-c",
          "mysql --password=$MYSQL_ROOT_PASSWORD -e 'UNLOCK TABLES'"]

Restore Hooks

Restore hooks run when Velero restores your pod. You set them as annotations before the backup is taken, because Velero restores the pod with the annotations it had at backup time.

Init Container Restore Hooks

An init container restore hook adds an init container to the restored pod. Use it to prepare the pod before the application containers start, for example to fix file permissions on restored data. Velero adds the hook container as the first init container. If Velero restored volumes with FSB, the hook container comes after Velero's own restore-wait init container. Mutating webhooks in the cluster can change this order.

Annotation Applies to Value Description
init.hook.restore.velero.io/container-image Pod (pod template) Container image reference Required to define the hook. The image for the init container. Without this annotation, Velero adds no init container.
init.hook.restore.velero.io/container-name Pod (pod template) Container name Optional. The name of the init container. Defaults to a generated name of the form velero-restore-init-<id>.
init.hook.restore.velero.io/command Pod (pod template) Command as a JSON array Optional. The entrypoint of the init container. Velero does not run it in a shell. Defaults to the ENTRYPOINT of the image.

The following annotations add an init container that prints the date when the pod is restored:

  template:
    metadata:
      annotations:
        init.hook.restore.velero.io/container-name: restore-hook
        init.hook.restore.velero.io/container-image: alpine:latest
        init.hook.restore.velero.io/command: '["/bin/ash", "-c", "date"]'

Exec Restore Hooks

An exec restore hook runs a command in a container of the restored pod after the container starts. If a pod has the post.hook.restore.velero.io/command annotation, Velero runs only that hook in the pod and ignores any exec hooks defined in the Restore resource.

Annotation Applies to Value Description
post.hook.restore.velero.io/command Pod (pod template) Command as a JSON array Required to define the hook. The command to run. Velero does not run it in a shell.
post.hook.restore.velero.io/container Pod (pod template) Container name Optional. The container to run the command in. Defaults to the first container in the pod.
post.hook.restore.velero.io/on-error Pod (pod template) Fail or Continue Optional. What to do if the command fails. Defaults to Continue, which only logs the failure. With Fail, Velero runs no more restore hooks in any pod and marks the restore PartiallyFailed.
post.hook.restore.velero.io/exec-timeout Pod (pod template) Duration, for example 45s Optional. How long to wait once the command starts. Defaults to 30s.
post.hook.restore.velero.io/wait-timeout Pod (pod template) Duration, for example 5m Optional. How long to wait for the container to become ready to run the command. The timer starts when Velero restores the container, so include time for image pulls and volume mounts. Without this annotation, Velero waits indefinitely.
post.hook.restore.velero.io/wait-for-ready Pod (pod template) "true" or "false" Optional. If "true", Velero runs the command only after the container passes its readiness probe. Any value other than "true" counts as "false". Defaults to "false". If one restore hook of a pod sets this to "true", all other hooks of that pod also wait for the Ready state.

The following annotations load a SQL dump into PostgreSQL after the pod is restored:

  template:
    metadata:
      annotations:
        post.hook.restore.velero.io/container: postgres
        post.hook.restore.velero.io/command: '["/bin/bash", "-c", "psql < /backup/backup.sql"]'
        post.hook.restore.velero.io/wait-timeout: 5m
        post.hook.restore.velero.io/exec-timeout: 45s
        post.hook.restore.velero.io/on-error: Continue

Commands in Hook Annotations

All hook command annotations follow the same rules:

  • Write the command as a JSON array, for example '["/usr/bin/uname", "-a"]'. If the value does not start with [ or is not valid JSON, Velero uses the whole value as a single executable name with no arguments.
  • Velero does not run the command in a shell. To use shell features such as environment variables, pipes, or &&, start the command with a shell that exists in the container, for example ["/bin/sh", "-c", "..."].
  • The container must contain the executables the command calls.

Velero also accepts backup hook annotations without the pre. or post. prefix (hook.backup.velero.io/command and so on) and runs them as pre hooks. This is a legacy form. Use the pre. prefix in new manifests.

Platform Notes

  • We manage the Velero Backup, Schedule and Restore resources. You do not create them. To restore an application or its data, contact the platform team as described in the Getting Started guide.
  • Kubernetes resources in your namespace are backed up by default. Persistent volume data is backed up only if you opt in with backup.velero.io/backup-volumes, as described in the Getting Started guide. This is the opt-in mode described in Volume Selection, so the backup.velero.io/backup-volumes-excludes annotation has no effect.

Further Reading