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.

Overview

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.

Supported Components

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:

BBR supports BOSH directors which use one of the following:

  • Basic Auth
  • Client/Client-Secret UAA Authentication

Contract

BBR sets out a contract with BOSH release authors, to call specific 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.

Backup Scripts

  1. pre-backup-lock: The pre-backup lock scripts locks the job so backups are consistent across the cluster.
  2. backup: The backup script backs up the release.
  3. post-backup-unlock: The post-backup unlock script unlocks the job after the backup is complete.

Restore Scripts

  1. pre-restore-lock: The pre-restore-lock scripts locks the job so the restore is consistent across the cluster.
  2. restore: The restore script restores the release.
  3. post-restore-unlock: The post-restore-unlock script unlocks the job after the restore is complete.

Workflow

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.

Backup flow

Syntax

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 [command] are:

  • 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 bbr binary

The [arguments] are specific to the command.

BOSH Director

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.

BOSH Deployment

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, 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 user name and a UAA client secret as the password. If you have a BOSH Director with basic auth configured, use your user name 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 bosh deployments.
  • --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.

Subcommands

BBR supports four subcommands:

  • backup
  • restore
  • pre-backup-check
  • backup-cleanup
Create a pull request or raise an issue on the source for this page in GitHub