Backing Up and Restoring CredHub Instances

Page last updated:

This topic describes how to back up and restore CredHub instances.


CredHub does not store any stateful data. However, CredHub relies on components that do store stateful data.

If you use CredHub in production or a similar environment that needs resiliency, you should create backups regularly so you can recover in the event of a component failure.

The components you should back up are:

Back Up the Deployment Manifest

Back up the CredHub deployment manifest every time you revise it. You may want to keep the backups in a revision control system so you can manage them automatically.

To download the most recent version of your CredHub deployment manifest, run:

bosh manifest -d DEPLOYMENT > MANIFEST.yml


  • DEPLOYMENT is the name of your CredHub deployment.
  • MANIFEST is the filename of your CredHub deployment manifest.

Back Up the Encryption Keys

The process for backing up CredHub encryption keys differs based on the encryption provider you use. CredHub supports internal providers and Luna HSM.


The internal provider performs encryption and decryption operations using a symmetrical AES key. This key is a hexadecimal value provided to the app during deployment.

Store the key in a secure place so you can use it in a future recovery deployment.

Luna HSM

Luna Hardware Security Modules (HSMs) do not support traditional data export. HSMs are designed not to release key material once it is placed on the device.

This does not mean data lost from a Luna HSM is unrecoverable. You can configure your deployment to ensure that no data is lost if an HSM fails.

If you use a Luna HSM to store sensitive data, you can ensure data resiliency by:

  • Setting up a redundant HSM configuration, or

  • Managing a Luna Backup HSM device. For more information, see the SafeNet Luna Network HSMs documentation.

CredHub supports management and integration with a high availability (HA) Luna HSM cluster. If you use this configuration, multiple HSMs use mirrored partitions to process incoming requests. Each HSM contains a copy of the encryption key. This provides redundancy, ensuring that all but one of your HSMs could fail without the losing the availability of key material.

If you use a Luna HSM from AWS, see What Is AWS CloudHSM? in the AWS documentation.


Back up the encryption keys whenever you rotate them to ensure that you always have access to the latest value.

Keep an archive of the encryption key values for each CredHub database backup you make. For example, if you maintain backups of the five most recent versions of your CredHub database, also save the five most recent encryption keys so you can access each backup.

Back Up the Database

CredHub stores the majority of its stateful data in the configured database. This database is not deployed or managed by CredHub, so backup procedures differ based on the selected database provider.

Note: After rotating the encryption key, test and verify a backup with the latest encryption key. This testing ensures that you are not locked out of your backups in the event of a rollback or other data loss.

For more information about database backups, see Chapter 7 Backup and Recovery in the MySQL documentation and Chapter 24. Backup and Restore in the PostgreSQL documentation.


Database best practices dictate that you perform backups regularly, to avoid losing data if your database cluster fails. The right frequency varies based on the needs of your deployment.

Create a pull request or raise an issue on the source for this page in GitHub