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:
hostPathvolumes.- 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,ScheduleandRestoreresources. 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 thebackup.velero.io/backup-volumes-excludesannotation has no effect.