How to Migrate PCF to a New Datastore in vSphere

Page last updated:

This topic describes how to migrate your Pivotal Cloud Foundry (PCF) installation to a new vSphere datastore.


Both the new and existing vSphere datastores must reside in the same datacenter.

To avoid service disruption, Pivotal recommends that you configure your overall PCF deployment for high availability. In addition, check for configurations necessary to achieve high availability in each of your installed product tiles.

If your environment has any single points of failure, service may be disrupted as a result of the migration.

Before You Begin

This section describes the steps you should perform prior to the migration.

Step 1: Back Up Your Environment

Ensure that your PCF environment is fully backed up.

For more information about how to backup PCF, see Backing up Pivotal Cloud Foundry.

Step 2: Document Current Environment Settings

Document your current environment settings before proceeding with the datastore migration. Record which VMs are running and in which datastore they reside. If you experience any issues during or after the migration, you must have this information to restore your environment.

To obtain this information, perform the following steps:

  1. Run the bosh instances command.

    • If you use the original version of the BOSH CLI, run the following command:
      $ bosh instances --details > instances.txt
    • If you use BOSH CLI v2, run the following command, replacing MY-ENV with the alias you assigned to your BOSH Director:
      $ bosh2 -e MY-ENV instances --details > instances.txt
  2. Save the resulting file instances.txt to a safe location.

  3. Note the datastore where each VM resides in vSphere.

Step 3: Modify CPI Timeout Value (Optional)

The default timeout for the BOSH CPI is 60 minutes. When performing a datastore migration, BOSH must copy all of the data from the old disks to the new disks within this time limit. In general, most copy operations should fit within this time limit, but it ultimately depends on the hardware in your deployment and the size of your existing persistent disks.

To determine whether 60 minutes is sufficient for the datastore migration, estimate how long it takes to copy 100 GB of data. Then, based on the size of your persistent disks, determine whether 60 minutes is sufficient time to copy that amount of data.

If you have previously encountered out of sync errors when modifying your PCF deployment, you should increase the timeout value of the CPI before migrating the datastores.

To modify the default BOSH CPI timeout, follow the instructions in the following KB article.

For more information about resolving the error after migrating your datastore, see After the Migration.

Step 4: Check System Health

In Elastic Runtime, check the Status tab and make sure there are no errors or reported issues.

Step 5: Check Installed Products Health

In each tile installed in your PCF deployment, check the Status tab and make sure there are no errors or reported issues.

Step 6: Check Ops Manager Director Status

  1. Check that there are no pending changes and that the status of all tiles is green.

  2. Make sure the last Installation Log does not contain any errors.

  3. Before proceeding with the migration, click Apply Changes to make sure there are no errors in the Installation Log.

Procedure: Migrate PCF to a New Datastore

  1. In Ops Manager Director, navigate to the vCenter Config page.

  2. Update the Ephemeral Datastore Names and Persistent Datastore Names field to reflect the new datastore names, then click Save.

    Note: If you use the Datastore Clustering feature in vSphere, provide only the individual names of the datastores in the cluster. Do not provide the name of the cluster that contains them.

  3. Click Apply Changes.

  4. Confirm that the Ops Manager Director VM has persistent disk on the new datastore.

    1. Navigate to vCenter Resource Pools and select the Resource Pool that contains your PCF deployment VMs and new datastore.
    2. Click the Related Objects and Virtual Machines.
    3. Locate the Ops Manager VM and verify that the VM has an expected value in the Provisioned Space column. Vsphere web client
  5. In Ops Manager Director, navigate to the Director Config page, and select the Recreate all VMs option.

  6. Click Apply Changes.

After the Migration

When BOSH moves disks, it waits for up to 60 minutes for the operation to complete. If the operation does not complete in time, BOSH can enter a state where it claims that the disks are out of sync.

Fix Failed BOSH Deployment with Out-of-Sync Error

If your PCF deployment gets into this state, you can resolve the issue by performing the steps in the KB article How to recover from a failed bosh deployment when VMs are out of sync on vSphere.

Prevent Out-of-Sync Error

You can also prevent the out of sync BOSH error by increasing the CPI timeout to a larger value before performing the migration. Follow the instructions in the KB article How to Increase the Timeout on Bosh CPI Command Calls.

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