Skip to main content

Configuring Backup and Restore Hooks

This topic describes the use of custom backup and restore hooks and demonstrates a common example.

About Backup and Restore Hooks

Velero supports the use of backup hooks and restore hooks.

Your application workload might require additional processing or scripts to be run before or after creating a backup to prepare the system for a backup. Many application workloads also require additional processing or scripts to run during or after the restore process.

Some common examples of how to use a hook to create backups are:

  • Run pg_dump to export a postgres database prior to backup
  • Lock a file before running a backup, and unlock immediately after
  • Delete TMP files that should not be backed up
  • Restore a database file only if that file exists
  • Perform required setup tasks in a restored Pod before the application containers can start

Additionally, for embedded clusters created by Replicated kURL, you must write custom backup and restore hooks to enable back ups for any object-stored data that is not KOTS-specific and does not use persistentVolumeClaims (PVCs). For more information about object-stored data, see Other Object Stored Data in Backup and Restore.

For more information about backup and restore hooks, see Backup Hooks and Restore Hooks in the Velero documentation.


The following example demonstrates how to include Velero backup and restore hooks for a Postgres database in a Replicated HelmChart custom resource manifest file.

The use case for this example is an application packaged with a Helm chart that includes a Postgres database. A description of key fields from the YAML follows the example.

kind: HelmChart
name: postgresql
exclude: 'repl{{ ConfigOptionEquals `postgres_type` `external_postgres` }}'

name: postgresql
chartVersion: 8.7.4


podAnnotations: backup '["/bin/bash", "-c", "PGPASSWORD=$POSTGRES_PASSWORD pg_dump -U username -d dbname -h > /scratch/backup.sql"]' 3m '["/bin/bash", "-c", "[ -f \"/scratch/backup.sql\" ] && PGPASSWORD=$POSTGRES_PASSWORD psql -U username -h -d dbname -f /scratch/backup.sql && rm -f /scratch/backup.sql;"]'

- name: backup
sizeLimit: 1Gi
- name: backup
mountPath: /scratch

postgresqlUsername: username
postgresqlPassword: "repl{{ ConfigOption `embedded_postgres_password` }}"
postgresqlDatabase: dbname

builder: {}

The following describes key fields from the example above:

  • spec.exclude: A common and recommended pattern for applications. The customer can choose to bring an external Postgres instance instead of running it in-cluster. The Replicated KOTS template function in spec.exclude evaluates to true when the user specifies the external database option in the admin console Config page. This means that the internal Postgres database is not included in the deployment.

  • spec.values.master.podAnnotations: Adds podAnnotations to the postgres master PodSpec. Velero backup and restore hooks are included in the podAnnotations. The following table describes the podAnnotations:


    Run backup hooks inside the container that contains the data to back up.

    podAnnotationDescription comma-separated list of volumes from the Pod to include in the backup. The primary data volume is not included in this field because data is exported using the backup hook. stringified JSON array containing the command for the backup hook. This command is a pg_dump from the running database to the backup volume. duration for the maximum time to let this script run. Velero exec restore hook that runs a script to check if the database file exists, and restores only if it exists. Then, the script deletes the file after the operation is complete.
  • spec.master.extraVolumes: A new volume that is injected into the postgres Pod. The new volume is an empty volume that uses ephemeral storage. The ephemeral storage must have enough space to accommodate the size of the exported data. The extraVolumeMounts field mounts the volume into the /scratch directory of the master Pod. The volume is used as a destination when the backup hook command described above runs pg_dump. This is the only volume that is backed up.