Backing Up Pivotal Cloud Foundry with BBR

This topic describes the procedure for backing up your critical backend Pivotal Cloud Foundry (PCF) components with BOSH Backup and Restore (BBR), a command-line tool for backing up and restoring BOSH deployments. To restore your backup, see the Restoring Pivotal Cloud Foundry from Backup with BBR topic.

To view the BBR release notes, see the Cloud Foundry documentation.

During the backup, BBR stops the Cloud Controller API and the Cloud Controller workers to create a consistent backup. Only the API functionality, like pushing applications or using the Cloud Foundry Command Line Interface (cf CLI) are affected. The deployed applications do not experience downtime.

Warning
  • Security: Backup artifacts can contain secrets. Secure backup artifacts by using encryption or other means.
  • Compatibility: A BBR backup can only be restored to environments matching its source environment. To ensure that a restore environment is compatible with a backup see Compatibility of Restore.
  • Failed Restore: Restore is a destructive operation. BBR is designed to restore PCF after a disaster. If a restore fails, the environment might be left in an unusable state and require re-provisioning. For more information, see Restoring Pivotal Cloud Foundry from Backup with BBR.
  • Service Data: BBR does not back up any service data.
  • API Outage: The Cloud Controller API does not send or receive calls during PCF restoration<.

Recommendations

Pivotal recommends the following:

  • Follow the full procedure documented in this topic when creating a backup. This ensures that you always have a consistent backup of Ops Manager and PAS to restore from.
  • Back up frequently, especially before making any changes to your PCF deployment, such as the configuration of any tiles in Ops Manager.

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 can communicate securely with external blobstores and databases, using TLS, if these are configured accordingly.

BBR can back up the following components:

PAS

BBR can back up and restore PAS configured with the following:

  • An internal MySQL database or a supported external database. For a list of supported external databases, see the Supported External Databases section of Configuring Cloud Foundry for BOSH Backup and Restore in the Cloud Foundry documentation.

  • An internal WebDAV/NFS blobstore, an external Amazon S3 or S3-compatible blobstore, or an external Azure blobstore.

For guidance about backing up unsupported databases and blobstores, see Unsupported External Blobstores and Databases in PAS below.

BOSH Director

BBR can back up and restore the BOSH Director configured with the following:

  • An internal PostgreSQL database or a supported external database. As part of backing up the BOSH Director, BBR backs up the BOSH UAA database and the CredHub database. For a list of supported external databases, see the Supported External Databases section of Configuring Cloud Foundry for BOSH Backup and Restore in the Cloud Foundry documentation.

  • An internal blobstore or an external versioned S3 blobstore.

Note: BBR support for backing up and restoring external databases and blobstores varies across PCF versions. For more information, see External Storage Support Across PCF Versions below.

External Storage Support Across PCF Versions

The following table shows what types of external databases and blobstores you can back up and restore with BBR.

Ops Manager Version
Deployment Type
2.2 2.3 2.4 2.5
PAS with External Database Yes Yes Yes Yes
BOSH Director with External Database No Yes Yes Yes
PAS with Amazon S3 Blobstore* Yes Yes Yes Yes
BOSH Director with Amazon S3 Blobstore* No No No No
PAS with S3-Compatible Blobstore Yes Yes Yes Yes
BOSH Director with S3-Compatible Blobstore No No No No
PAS with Azure Blobstore Add-on Yes Yes Yes
PAS with GCS Blobstore No No No No
BOSH Director with GCS Blobstore No No No No
* Any S3 clone that supports the versioning API.

Unsupported External Blobstores and Databases in PAS

If you configured an unsupported external blobstore or an unsupported external database in PAS, see the following guidelines to perform a backup successfully:

Scenario Action
You configured a supported database and an unsupported external blobstore in PAS. Follow the PCF backup process and copy the external blobstore by using the IaaS-specific tool.
You configured an unsupported external database and a supported blobstore in PAS. Follow the PCF backup process and copy the external database by using the IaaS-specific tool.
You configured both an unsupported external database and an unsupported external blobstore in PAS. Follow the PCF backup process but skip Back Up Your PAS Deployment. Copy the external database and blobstore by using the IaaS-specific tool.

Warning: You might encounter inconsistencies between the blobstore and database. If apps do not appear during a restore, re-push those apps.

Backing Up Services

Warning: BBR does not currently back up any service data.

Keep in mind the following when backing up services:

  • BBR backs up and restores the service bindings, but not the service data.
  • You can redeploy on-demand service instances manually during restore, but the data in the instance is not backed up.
  • BBR does not back up managed services or their data.
  • You can back up and restore brokered services with the procedures documented in this topic and in the Restoring Pivotal Cloud Foundry from Backup with BBR topic.

Backup Workflow

BBR examines the jobs in the BOSH deployment, and triggers the scripts in the following stages:

  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.

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 can 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 PCF.

The following diagram shows a sample backup flow.

Backup flow

Preparing to Create Your Backup

Step 1: Set Up Your Jumpbox

You must have a jumpbox before you can install BBR to the jumpbox. A jumpbox is a separate, hardened server on your network that provides a controlled means of access to the VMs other computers on your network.

Pivotal recommends using the Ops Manager VM as your jumpbox. If you use the Ops Manager VM as your jumpbox, the path to the root Certificate Authority (CA) certificate is:

/var/tempest/workspaces/default/root_ca_certificate

You must have this path to run BBR commands.

As an alternative to using the Ops Manager VM as your jumpbox, you can do the following:

Step 2: Record the Cloud Controller Database Encryption Credentials

Perform the following steps to retrieve the Cloud Controller database encryption credentials from the PAS tile:

  1. Navigate to Ops Manager in a browser and log in to the Ops Manager Installation Dashboard.

  2. Select PAS Credentials and locate the Cloud Controller section.

  3. Record the Db Encryption Credentials. You must provide these credentials when you contact Pivotal Support for help restoring your installation.

    Ccdb encrypt creds

Step 3: Retrieve BOSH Director Credentials

To use BBR, you must retrieve and record the following credentials:

  • Bosh Director Credentials
  • Bbr Ssh Credentials
  • Uaa Bbr Client Credentials

There are two ways to retrieve BOSH Director credentials:

  • Ops Manager Installation Dashboard
  • Ops Manager API

Option 1: Ops Manager Installation Dashboard

To retrieve your BOSH Director credentials using the Ops Manager Installation Dashboard, perform the following steps:

  1. Navigate to the Ops Manager Installation Dashboard.
  2. Click the BOSH Director tile.
  3. Click the Credentials tab.
  4. Locate Director Credentials.

    1. Click Link to Credentials next to it.
    2. Verify the value of the identity field. It should be director.
    3. Copy and record the value of the password field.
  5. Locate Bbr Ssh Credentials.

    1. Click Link to Credentials next to it.
    2. Copy the value of the private_key_pem field.
    3. Run the following command to reformat the copied value, and save it in the current directory to a file named PRIVATE-KEY-FILE:

      printf -- "YOUR-PRIVATE-KEY" > PRIVATE-KEY-FILE
      

      Where:

      • YOUR-PRIVATE-KEY is the text of your private key.
      • PRIVATE-KEY-FILE is the path to the private key file you are creating.

      For example:

      $ printf --  "-----BEGIN RSA PRIVATE KEY----- MIIEkeycontents ----END RSA PRIVATE KEY-----" > bbr_key.pem
      
  6. Locate the Uaa Bbr Client Credentials

    1. Click Link to Credentials next to it.
    2. Verify the value of the identity field. It should be bbr_client.
    3. Record the value of the password field.

Option 2: Ops Manager API

To retrieve BOSH Director credentials using the Ops Manager API, perform the following steps:

  1. Obtain your UAA access token. For more information, see Access the API.
  2. Retrieve the Director Credentials by performing the following steps:

    1. Run the following command:

      curl "https://OPS-MAN-FQDN/api/v0/deployed/director/credentials/director_credentials" \
      -X GET \
      -H "Authorization: Bearer UAA-ACCESS-TOKEN"
      

      Where:

      • OPS-MAN-FQDN is the fully-qualified domain name (FQDN) for your Ops Manager deployment.
      • UAA-ACCESS-TOKEN is your UAA access token.
    2. Verify the value of the identity field. It should be director.

    3. Record the value of the password field.

  3. Retrieve the Bbr Ssh Credentials by performing the following steps:

    1. Run the following command:

      curl "https://OPS-MAN-FQDN/api/v0/deployed/director/credentials/bbr_ssh_credentials" \
      -X GET \
      -H "Authorization: Bearer UAA-ACCESS-TOKEN"
      

      Where:

      • OPS-MAN-FQDN is the fully-qualified domain name (FQDN) for your Ops Manager deployment.
      • UAA-ACCESS-TOKEN is your UAA access token.
    2. Copy the value of the private_key_pem field.

    3. Run the following command to reformat the copied value, and save it in the current directory to a file named PRIVATE-KEY-FILE:

      printf -- "YOUR-PRIVATE-KEY" > PRIVATE-KEY-FILE
      

      Where:

      • YOUR-PRIVATE-KEY is the text of your private key.
      • PRIVATE-KEY-FILE is the path to the private key file you are creating.

      For example:

      $ printf --  "-----BEGIN RSA PRIVATE KEY----- MIIEkeycontents ----END RSA PRIVATE KEY-----" > bbr_key.pem
      
  4. Retrieve the Uaa Bbr Client Credentials by performing the following steps:

    1. Run the following command:

      curl "https://OPS-MAN-FQDN/api/v0/deployed/director/credentials/uaa_bbr_client_credentials" \
      -X GET \
      -H "Authorization: Bearer UAA-ACCESS-TOKEN"
      

      Where:

      • OPS-MAN-FQDN is the fully-qualified domain name (FQDN) for your Ops Manager deployment.
      • UAA-ACCESS-TOKEN is your UAA access token.
    2. Verify the value of the identity field. It should be bbr_client.

    3. Record the value of the password field.

For more information about using the Ops Manager API, see the Using the Ops Manager API topic.

Step 4: Retrieve BOSH Director Address

Perform the following steps to retrieve the IP address of your BOSH Director from the BOSH Director tile:

  1. If you are not using the Ops Manager VM as your jumpbox, install the latest BOSH CLI on your jumpbox.
  2. From the Installation Dashboard in Ops Manager, select BOSH Director > Status and record the IP address listed for the Director. You access the BOSH Director using this IP address.

  3. From the command line, log into the BOSH Director, using the IP address that you recorded above, by running the following command:

    bosh -e DIRECTOR-IP \
    --ca-cert PATH-TO-BOSH-SERVER-CERTIFICATE log-in
    

    Where:

    • DIRECTOR-IP is the BOSH Director IP address recorded above.
    • PATH-TO-BOSH-SERVER-CERTIFICATE is the path to the root Certificate Authority (CA) certificate as outlined in Step 1: Set Up your Jumpbox, above.
  4. When prompted for Email (), specify director.

  5. When promted for Password (), enter the Director Credentials that you obtained in Retrieve BOSH Director Credentials.

    For example:

    $ bosh -e 10.0.0.3 \
    --ca-cert /var/tempest/workspaces/default/root_ca_certificate log-in
    Email (): director
    Password (): *******************
    Successfully authenticated with UAA
    Succeeded
    

Step 5: Check Your BOSH Director

Perform the following steps to confirm that your BOSH Director is reachable and can be backed up.

Connect to Your Jumpbox

You can establish a connection to your jumpbox in one of the following ways.

Note: These procedures require you have a jumpbox configured for SSH access. If you do not have a jumpbox, see Enabling SSH Access and Tunneling in the BOSH documentation.

Connect with SSH

There are two options available to you to connect to your jumpbox with SSH:

  • Ops Manager VM.
  • SSH through the command line.
  1. To connect to your jumpbox through an Ops Manager VM, perform the following steps:
    1. Log in to the Ops Manager VM:
    2. If you are using the Ops Manager VM as your jumpbox, see the Log in to the Ops Manager VM with SSH section of Advanced Troubleshooting with the BOSH CLI for information about how to use SSH to connect to the Ops Manager VM.
  2. To connect to your jumpbox through the command line, perform the following steps:

    1. Run the following command to SSH into your jumpbox:

      ssh -i LOCAL-PATH-TO-JUMPBOX-PRIVATE-KEY JUMPBOX-USER@JUMPBOX-ADDRESS
      

      Where:

      • LOCAL-PATH-TO-JUMPBOX-PRIVATE-KEY is the local path to your private key file for the jumpbox host.
      • JUMPBOX-USER is your jumpbox username.
      • JUMPBOX-ADDRESS is the IP address of your jumpbox.

Note: If you connect to your jumpbox with SSH, you must run the BBR commands in the following sections from within your jumpbox.

Connect with BOSH_ALL_PROXY

Set and use BOSH_ALL_PROXY. Using BOSH_ALL_PROXY opens an SSH tunnel with SOCKS5 to the jumpbox. This tunnel enables you to forward requests to the BOSH Director through the jumpbox from your local machine.

Use one of the following methods to create the tunnel:

  • Tunnel created by BOSH CLI: To provide the BOSH CLI with the SSH credentials it needs to create the tunnel, run the following command:

     export BOSH_ALL_PROXY=ssh+socks5://JUMPBOX@JUMPBOX-IP:SOCKS-PORT?private_key=JUMPBOX-KEY-FILE
    

    Where:

    • JUMPBOX is the name of your jumpbox.
    • JUMPBOX-IP is the IP address of the jumpbox.
    • SOCKS-PORT is the local SOCKS port.
    • JUMPBOX-KEY-FILE is the local SSH private key for accessing the jumpbox.
  • Tunnel established separately:

  1. To establish the tunnel and make it available on a local port, run the following command:

    ssh -4 -D SOCKS-PORT -fNC JUMPBOX@JUMPBOX-IP -i JUMPBOX-KEY-FILE
    

    Where:

    • SOCKS-PORT is the local SOCKS port.
    • JUMPBOX is the name of your jumpbox.
    • JUMPBOX-IP is the IP address of the jumpbox.
    • JUMPBOX-KEY-FILE is the local SSH private key for accessing the jumpbox.
  2. To provide the BOSH CLI with access to the tunnel through use of the BOSH_ALL_PROXY environment variable, run the following command:

    export BOSH_ALL_PROXY=socks5://localhost:12345
    

Note: Ensure the SOCKS port is not already in use by a different tunnel/process.

Note: Using BOSH_ALL_PROXY can result in longer backup and restore times due to network performance degradation. Because all operations must pass through the proxy, moving backup artifacts can be significantly slower.

Check Your BOSH Director

  1. Run the BBR pre-backup-check command:

    bbr director \
    --private-key-path PRIVATE-KEY-FILE \
    --username bbr \
    --host HOST \
    pre-backup-check
    

    Where:

    • PRIVATE-KEY-FILE is the path to the private key file that you created from Bbr Ssh Credentials in Step 3: Retrieve BOSH Director Credentials.
    • HOST is the address of the BOSH Director. If the BOSH Director is public, HOST is a URL, such as https://my-bosh.xxx.cf-app.com. Otherwise, HOST is the BOSH-DIRECTOR-IP which you retrieved in the Step 4: Retrieve BOSH Director Address section of this topic.

      Note: Use the optional --debug flag to enable debug logs. See the Logging section of this topic for more information.

  2. After the pre-backup check succeeds, continue to Step 5: Confirm Backup Restore Node is Deployed below.
    If the pre-backup check fails, the BOSH Director might not have the correct backup scripts, or the connection to the BOSH Director might have failed.

Step 6: Confirm Backup Restore Node is Deployed

When BBR backs up PAS, it needs a Backup Restore node. This procedure confirms that the Backup Restore node is deployed.

  1. In Ops Manager, open the Pivotal Application Service (PAS) tile.

  2. In the Resource Config pane, find the Backup Restore Node job and check if the Instances dropdown is set to 1. Backup restore node

  3. If the Instances dropdown is not set to 1:

    1. Set the Instances dropdown to 1.
    2. Click Save.
    3. Navigate to the Ops Manager Installation Dashboard.
    4. Click Review Pending Changes.
    5. Review your changes. For more information, see Reviewing Pending Product Changes.
    6. Click Apply Changes.

Step 7: Identify Your Deployment

  1. Log in to your BOSH Director.

  2. To identify the name of the BOSH deployment that contains PCF, run the following command:

    bosh -e BOSH-DIRECTOR-IP --ca-cert PATH-TO-BOSH-SERVER-CERTIFICATE deployments
    

    Where:

    • BOSH-DIRECTOR-IP is the BOSH Director IP retrieved in Step 4: Retrieve BOSH Director Address.
    • PATH-TO-BOSH-SERVER-CERTIFICATE is the path to the Certificate Authority (CA) certificate for the BOSH Director.
    $ bosh -e BOSH-DIRECTOR-IP --ca-cert PATH-TO-BOSH-SERVER-CERTIFICATE deployments
    
    Name                     Release(s)
    cf-example               push-apps-manager-release/661.1.24
                             cf-backup-and-restore/0.0.1
                             binary-buildpack/1.0.11
                             capi/1.28.0
                             cf-autoscaling/91
                             cf-mysql/35
                             ...
    

    In the above example, the name of the BOSH deployment that contains PCF is cf-example.

Step 8: Check Your Deployment

Perform the following steps to check that your BOSH Director is reachable and has a deployment that can be backed up:

  1. Run the BBR pre-backup check:

    bbr deployment \
    --target BOSH-DIRECTOR-IP \
    --username BOSH-CLIENT \
    --password BOSH-PASSWORD \
    --deployment DEPLOYMENT-NAME \
    --ca-cert PATH-TO-BOSH-SERVER-CERTIFICATE \
    pre-backup-check
    

    Where:

  2. After the pre-backup check succeeds, continue to Create Your Backup below.
    If the pre-backup check fails, the deployment you selected might not have the correct backup scripts, or the connection to the BOSH Director might have failed.

Creating Your Backup

Step 9: Export Installation Settings

Pivotal recommends that you back up your Ops Manager installation settings by exporting frequently.

When exporting your installation settings, keep in mind the following:

  • This option is only available after you have deployed at least once.

  • Always export your installation settings before following the steps in the Deploy Ops Manager and Import Installation Settings section of the Restoring Pivotal Cloud Foundry from Backup with BBR topic.

  • Exporting your installation settings only backs up the settings you configured in Ops Manager. It does not back up your VMs or any external MySQL databases.

  • Your Ops Manager settings are encrypted. Make sure you keep track of your Decryption Passphrase because this is needed to restore the Ops Manager settings.

Note: When exporting installation settings for Ops Manager v1.12 and later, releases are not included in the output file. Releases are now included in the BOSH Director backup, therefore, the output file is much smaller than in previous Ops Manager versions.

There are two ways to export Ops Manager installation settings:

Option 1: Use the Ops Manager UI

To export your installation settings using the Ops Manager UI, do the following:

  1. From the Installation Dashboard in the Ops Manager interface, click your username at the top right navigation.

  2. Select Settings.

  3. Select Export Installation Settings.

  4. Click Export Installation Settings. Settings

Option 2: Use the Ops Manager API

If you want to automate the back up process, you can use the Ops Manager API to export your installation settings.

  1. To export your installation settings using the Ops Manager API, run the following command:

    curl https://OPS-MAN-FQDN/api/v0/installation_asset_collection \
      -H "Authorization: Bearer UAA-ACCESS-TOKEN" > installation.zip
    

    Where:

    • OPS-MAN-FQDN is the fully-qualified domain name (FQDN) for your Ops Manager deployment.
    • UAA-ACCESS-TOKEN is your UAA access token. For more information, see Access the API.

Step 10: Back Up Your BOSH Director

Notes:
  • The BOSH Director backup can take more than 10 minutes.
  • Because the BBR backup command can take a long time to complete, Pivotal recommends you run it independently of the SSH session so that the process can continue running even if your connection to the jumpbox fails.
    Use nohup, a screen, or a tmux session.
  1. Run the BBR backup command to back up your BOSH Director:

    bbr director \
    --private-key-path PRIVATE-KEY-FILE \
    --username bbr \
    --host HOST \
    backup
    

    Where:

    Note: Use the optional --debug flag to enable debug logs. See the Logging section of this topic for more information.

If your backup terminates early or fails you need to perform a cleanup.

  1. To clean up, run the following backup-cleanup command:

    bbr director \
    --private-key-path PRIVATE-KEY-FILE \
    --username bbr \
    --host HOST \
    backup-cleanup
    

    Where:

Step 11: Back Up Your PAS Deployment

Notes:
  • Backing up PAS can take more than 5 minutes, and can take considerably longer with larger blobstores or slow network connections. The backup also incurs Cloud Controller downtime during which users are unable to push, scale, or delete apps. Your apps are not affected.
  • Because the BBR backup command can take a long time to complete, Pivotal recommends you run it independently of the SSH session, so that the process can continue running even if your connection to the jumpbox fails. The command above uses nohup but you could also run the command in a screen or tmux session.
  1. (Optional) If you are not using an internal blobstore or a versioned S3-compatible external blobstore, create a copy of the blobstore with your IaaS specific tool. Your blobstore backup might be slightly inconsistent with your PAS backup depending on the duration of time between performing the backups.

  2. Run the BBR backup command to back up your PAS deployment:

    bbr deployment \
    --target BOSH-DIRECTOR-IP \
    --username BOSH-CLIENT \
    --password BOSH-PASSWORD \
    --deployment DEPLOYMENT-NAME \
    --ca-cert PATH-TO-BOSH-SERVER-CERTIFICATE \
    backup
    

    Where:

    • BOSH-DIRECTOR-IP is the BOSH Director IP retrieved in Step 4: Retrieve BOSH Director Address.
    • BOSH-CLIENT, BOSH-PASSWORD are the Uaa Bbr Client Credentials, identity and password, that you retrieved in Step 3: Retrieve BOSH Director Credentials.
    • DEPLOYMENT-NAME is the deployment name retrieved in Step 6: Identify Your Deployment.
    • PATH-TO-BOSH-SERVER-CERTIFICATE is the path to the Certificate Authority (CA) certificate for the BOSH Director.
    • Use the optional --debug flag to enable debug logs. For more information, see Logging below.
    • Use the optional --with-manifest flag to ensure that BBR downloads your current deployment manifest when backing up. These manifests are included in the Ops Manager export, but are useful for reference.
  3. After the command successfully completes, continue to Step 11: Transfer Backup Artifacts.
    If the command fails, perform the following steps:

    1. Run the BBR backup-cleanup command:

      bbr deployment \
      --target BOSH-DIRECTOR-IP \
      --username BOSH-CLIENT \
      --password BOSH-PASSWORD \
      --deployment DEPLOYMENT-NAME \
      --ca-cert PATH-TO-BOSH-SERVER-CERTIFICATE \
      backup-cleanup
      

      Where:

      • BOSH-DIRECTOR-IP is the BOSH Director IP retrieved in Step 4: Retrieve BOSH Director Address.
      • BOSH-CLIENT, BOSH-PASSWORD are the Uaa Bbr Client Credentials, identity and password, that you retrieved in Step 3: Retrieve BOSH Director Credentials.
      • DEPLOYMENT-NAME is the deployment name retrieved in Step 6: Identify Your Deployment.
      • PATH-TO-BOSH-SERVER-CERTIFICATE is the path to the Certificate Authority (CA) certificate for the BOSH Director.
      • Use the optional --debug flag to enable debug logs. For more information, see Logging below.
      • Use the optional --with-manifest flag to ensure that BBR downloads your current deployment manifest when backing up. These manifests are included in the Ops Manager export, but are useful for reference.
    2. Run the BBR backup command again after checking the following:

      • All the parameters in the command are set.
      • The BOSH Director credentials are valid.
      • The specified deployment exists.

After Taking Your Backup

Step 12: Transfer Backup Artifacts

After creating your backup successfully, perform the following steps:

  1. Move the backup artifacts off the jumpbox to your preferred storage space. The backup created by BBR consists of a directory with the backup artifacts and metadata files. Pivotal recommends compressing and encrypting the files.

  2. Make redundant copies of your backup artifacts and store them in multiple locations to minimize the risk of losing backups in the event of a disaster.

  3. Attempt to restore every backup to validate the artifacts. Perform the procedures in the next step, Step 12: Validate Your Backup.

Note: Backup artifacts might contain data covered by the European Union’s General Data Protection Regulation (GDPR).

Step 13: (Optional) Validate Your Backup

After backing up PCF, consider validating your backup by restoring it and checking the applications. BBR is designed for disaster recovery and BBR backups are only compatible with environments matching their source environment’s configuration.

Warning:
  • The VMs and disks from the backed-up BOSH Director must not be visible to the new BOSH Director when validating your backup. As a result, Pivotal recommends that you deploy the new BOSH Director to a different IaaS network and account than the VMs and disks of the backed-up BOSH Director.
  • Data services outside of PCF might produce unexpected side effects during restoration. Restored apps and services might attempt to connect to data services when you restore to a new environment. For example, consider an app that processes mail queues and connects to an external database. When you validate your backup in a test environment, the app might start processing the queue, and this work might be lost.

Validate Your Backup in a Second Environment

To spin up a second environment and test the backup, perform the following steps:

  1. Export your Ops Manager installation by performing the steps in the Step 8: Export Installation Settings section above.

  2. Create a new Ops Manager VM in a different network to the original. Ensure that the Ops Manager VM has enough persistent disk to accommodate the files exported in the previous step. Consult the topic for deploying PCF on your IaaS.

  3. Ensure that the restore environment is compatible with the backup. For more information, see Compatibility of Restore.

  4. Follow the instructions in the Restoring Pivotal Cloud Foundry from Backup with BBR topic.

Validate Your PAS Backup Only

For a sandbox or other non-production environment, you can optionally perform an in-place restore of PAS only. In this case, you restore the PAS backup to the same PCF environment that the backup was created from. Follow the procedures in Restoring PCF from Backup with BBR.

Logging

BBR outputs logs to stdout. By default, BBR logs:

  • The backup and restore scripts that it finds
  • When it starts or finishes a stage, such as pre-backup scripts or backup scripts
  • When the process is complete
  • When any error occurs

If you require additional logging, use the optional --debug flag to print the following information:

  • Logs about the API requests made to the BOSH server
  • All commands executed on remote instances
  • All commands executed on local environment
  • Standard in and standard out streams for the backup and restore scripts when they are executed

Canceling a Backup

If you need to cancel a backup, perform the following steps:

  1. Enter CTRL-C to terminate the BBR process, then enter yes to confirm.

  2. Run the BBR backup-cleanup command.

    • For a canceled director backup, run the following:

      bbr director \
      --private-key-path PRIVATE-KEY-FILE \
      --username bbr \
      --host HOST \
      backup-cleanup
      

      Where:

    • PRIVATE-KEY-FILE is the path to the private key file that you created from Bbr Ssh Credentials in Step 3: Retrieve BOSH Director Credentials.

      • HOST is the address of the BOSH Director:
        • If the BOSH Director is public, HOST is a URL, such as https://my-bosh.xxx.cf-app.com.
        • If the BOSH Director is not public, HOST is the BOSH-DIRECTOR-IP retrieved in Step 4: Retrieve BOSH Director Address.
    • For a canceled deployment backup, run the following:

      bbr deployment \
      --target BOSH-DIRECTOR-IP \
      --username BOSH-CLIENT \
      --password BOSH-PASSWORD \
      --deployment DEPLOYMENT-NAME \
      --ca-cert PATH-TO-BOSH-SERVER-CERTIFICATE \
      backup-cleanup
      

      Where:

      • BOSH-DIRECTOR-IP is the BOSH Director IP retrieved in Step 4: Retrieve BOSH Director Address.
      • BOSH-CLIENT, BOSH-PASSWORD are the Uaa Bbr Client Credentials, identity and password, that you retrieved in Step 3: Retrieve BOSH Director Credentials.
      • DEPLOYMENT-NAME is the deployment name retrieved in Step 6: Identify Your Deployment.
      • PATH-TO-BOSH-SERVER-CERTIFICATE is the path to the Certificate Authority (CA) certificate for the BOSH Director.
      • Use the optional --debug flag to enable debug logs. For more information, see Logging below.
      • Use the optional --with-manifest flag to ensure that BBR downloads your current deployment manifest when backing up. These manifests are included in the Ops Manager export, but are useful for reference.

European Union’s General Data Protection Regulation (GDPR)

Backup artifacts might contain personal and other data covered by the European Union’s General Data Protection Regulation (GDPR). For example, a PAS backup could contain user email addresses. As such, handle backup artifacts in accordance with organizational policies and applicable laws as they pertain to security, confidentiality, and privacy.

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