BOSH Backup and Restore
This guide documents BOSH Backup and Restore (BBR), a framework for backing up and restoring BOSH deployments and BOSH Directors.
To use BBR to back up and restore Pivotal Cloud Foundry (PCF) v1.11 and later, see the Backing Up Pivotal Cloud Foundry with BBR and Restoring Pivotal Cloud Foundry from Backup with BBR topics.
BBR orchestrates triggering the backup or restore process on the BOSH deployment or BOSH Director, and transfers the backup artifacts to and from the BOSH deployment or BOSH Director.
For more information about installing and using BBR, see the Installing BOSH Backup and Restore, Backing Up with BOSH Backup and Restore, and Restoring with BOSH Backup and Restore topics. Information for release authors and developers is also available in the BOSH Backup and Restore Developer’s Guide.
BBR is a binary that can back up and restore BOSH deployments and BOSH Directors. BBR requires that the backup targets supply scripts that implement the backup and restore functions.
BBR is not dependent on a particular version of BOSH. However, a BOSH deployment must have its backup and restore scripts packaged in the releases to be backed up and restored with BBR. For more information, consult the documentation for the deployment.
You can back up and restore the following BOSH deployments with BBR:
- Elastic Runtime (Pivotal Cloud Foundry 1.11+): To use BBR with PCF v1.11+, see the Backing Up Pivotal Cloud Foundry with BBR and Restoring Pivotal Cloud Foundry from Backup with BBR topics.
- BOSH Director, including UAA and CredHub
BBR supports BOSH Directors which use one of the following:
- Basic Auth
- Client/Client-Secret UAA Authentication
BBR sets out a contract with BOSH release authors to call designated backup and restore scripts in a specific order.
This approach has the following advantages:
- The deployment itself encapsulates the knowledge of how to back up and restore the deployment.
- Because responsibility for writing and maintaining scripts sits with the release author, scripts can change as the deployment changes and do not get out of sync.
For more information about how PCF tile authors can implement the BBR contract, see the PCF Tile Developers Guide.
- pre-backup-lock: The pre-backup lock script locks the job so backups are consistent across the cluster.
- backup: The backup script backs up the release.
- post-backup-unlock: The post-backup unlock script unlocks the job after the backup is complete.
- pre-restore-lock: The pre-restore-lock script locks the job so the restore is consistent across the cluster.
- restore: The restore script restores the release.
- post-restore-unlock: The post-restore-unlock script unlocks the job after the restore is complete.
Operators download the BBR binary and transfer it to a jumpbox. Then they run BBR from the jumpbox, specifying the name of the BOSH deployment or BOSH Director to back up.
BBR examines the jobs in the BOSH deployment or BOSH Director, and triggers the pre-backup lock, backup, and post-backup unlock scripts.
Scripts in the same stage are all triggered together. For instance, BBR triggers all pre-backup lock scripts before any backup scripts. Scripts within a stage may be triggered in any order.
The backup artifacts are drained to the jumpbox where the operator can transfer them to storage and use them to restore the BOSH deployment or BOSH Director.
The following diagram shows a sample backup flow.
This section provides syntax information for the BBR binary. For detailed procedures on how to use BBR to back up and restore a BOSH Director or BOSH deployment, see the Backing Up with BOSH Backup and Restore and Restoring with BOSH Backup and Restore topics.
The syntax for the BBR binary is:
bbr [command] [arguments...] [subcommand]
The options for
deployment: Specifies that the target of BBR is a BOSH deployment
director: Specifies that the target of BBR is a BOSH Director
help: Prints help text
version: Prints the version of the
[arguments] are specific to the command.
The arguments to specify when running BBR for a BOSH Director are:
$ bbr director \ --debug (OPTIONAL) \ --private-key-path PATH_TO_PRIVATE_KEY \ --username USER_NAME \ --host HOST \ SUB-COMMAND [--artifact-path PATH_TO_ARTIFACT_TO_RESTORE]
The parameters are:
--debug: This is an optional flag to display debug output.
--private-key-path: This is the path to the SSH private key used to connect to the BOSH Director.
--username: This is the SSH username of the BOSH Director.
--host: This is the address of the BOSH Director with an optional port that defaults to 22. If the BOSH Director is public, this is a URL, such as
https://my-bosh.xxx.cf-app.com. Otherwise, this is the BOSH Director IP address.
--artifact-path: This is the path to the BOSH Director backup you want to restore.
The arguments to specify when running BBR for a BOSH deployment are:
$ BOSH_CLIENT_SECRET=BOSH_CLIENT_SECRET \ bbr deployment \ --debug (OPTIONAL) --target BOSH_TARGET \ --username BOSH_CLIENT \ --deployment DEPLOYMENT_NAME \ --ca-cert PATH_TO_BOSH_SERVER_CERTIFICATE \ SUB-COMMAND [--artifact-path PATH_TO_ARTIFACT_TO_RESTORE]
The arguments are:
--debug: This is an optional flag to display debug output.
BOSH_CLIENT_SECRET: If you have a BOSH Director with User Account and Authentication (UAA) as the authentication provider, use a UAA client as the username and a UAA client secret as the password. If you have a BOSH Director with basic auth configured, use your username and password.
--target: This is the FQDN or IP address of your BOSH Director.
--deployment: This is the name of the deployment you want to back up. For a list of deployments, run
--ca-cert: This is the path to the BOSH Director’s Certificate Authority (CA) certificate if the certificate is not verifiable by the local machine’s certificate chain.
--artifact-path: This is the path to the BOSH deployment backup you want to restore.
BBR supports five subcommands: