Upgrading Pivotal Cloud Foundry

Page last updated:

Warning: Pivotal Cloud Foundry (PCF) v2.4 is no longer supported because it has reached the End of General Support (EOGS) phase as defined by the Support Lifecycle Policy. To stay up to date with the latest software and security updates, upgrade to a supported version.

This topic describes upgrading Pivotal Cloud Foundry (PCF) to v2.4. The upgrade procedure below describes upgrading Pivotal Cloud Foundry Operations Manager (Ops Manager), Pivotal Application Service (PAS), and product tiles.

Breaking Changes: Read the Release Notes and Breaking Changes for this release, including the Known Issues sections, before starting the upgrade process.

Warning: Pivotal does not recommend that you skip minor versions when upgrading PCF. Skipping minor versions when upgrading PCF may result in breaking changes. To avoid additional breaking changes, upgrade PCF to the minor version that directly follows your current version of PCF.

The apps in your deployment continue to run during the upgrade. However, you cannot write to your deployment or make changes to apps during the upgrade.

For details about how upgrading PCF impacts individual PAS components, see What Happens During PAS Upgrades.

Prepare to Upgrade

If you have not already, complete the steps in the Upgrade Preparation Checklist for PCF v2.4.

Upgrade Ops Manager and Installed Products to v2.4

Follow these steps to upgrade Ops Manager and Installed Products to PCF v2.4.

Import Installation to Ops Manager v2.4 VM

  1. Download the Ops Manager VM Template v2.4 from the Pivotal Network site.

  2. Record the FQDN address of the existing Ops Manager VM.

  3. To avoid conflicts, power off the existing Ops Manager VM.

  4. Deploy the new Ops Manager VM by following the steps in one of these topics:

  5. When redirected to the Welcome to Ops Manager page, select Import Existing Installation.


  6. When prompted, enter the Decryption Passphrase for this Ops Manager installation. You set this passphrase during your initial installation of Ops Manager.

    Note: If lost, the Decryption Passphrase cannot be recovered.

  7. Click Choose File and browse to the installation ZIP file exported in the Export Your Installation step of your upgrade preparation.

    Decryption passphrase

  8. Click Import.

    Note: Some browsers do not provide feedback on the status of the import process, and might appear to hang.

  9. A Successfully imported installation message appears upon completion.


Import New PAS and Product Tiles

After upgrading to Ops Manager v2.4, upgrade your product versions:

  1. Import the product file to your Ops Manager Installation Dashboard.

  2. Hover over the product name in Available Products and click Add.

  3. Click the newly-added tile to review any configurable options.

  4. (Optional) If you use other service tiles, you can upgrade them following the same procedure. See the Upgrading PAS and Other Pivotal Cloud Foundry Products topic for more information.

Perform Your Upgrade

Warning: If the installation fails or returns errors, contact Support. Do not attempt to roll back the upgrade by restarting the previous (v2.3) Ops Manager VM.

  1. Navigate to the Ops Manager Installation Dashboard.

  2. Click Review Pending Changes, then Apply Changes. This immediately imports and applies upgrades to all tiles in a single transaction.

  3. Click each service tile, select the Status tab, and confirm that all VMs appear and are in good health.

  4. After confirming that the new installation functions correctly, remove the Ops Manager v2.3 VM.

Monitor Upgrade

During the upgrade, you can do the following to monitor your PCF foundation and help troubleshoot any issues.

Check Status and Performance

Monitor the progress of the upgrade, checking the status of the foundation at various locations.

Pivotal recommends live-monitoring your upgrade with PCF Healthwatch, which monitors and alerts on the current health, performance, and capacity of PCF. Healthwatch captures, calculates, stores, visualizes, and alerts on PCF platform metrics, including:

For more information, see the PCF Healthwatch documentation.

If you are not using PCF Healthwatch, you can do some or all of the following to monitor upgrade progress:

  • Run BOSH CLI status checks:
    • bosh -e ALIAS task TASK_NUMBER
    • bosh -e ALIAS vms --vitals, bosh -e ALIAS instances --ps
  • Check app availability
  • Run cf CLI Commands
  • Check the availability of the Ops Manager UI
  • Check NAS performance (if using NAS)
  • Check vSphere performance (if on vSphere)

Check Diego State

See the cfdot documentation on GitHub for details.

Use the CF Diego Operator Toolkit (cfdot) to check Diego component instance count by current state.

(Optional) Take Snapshots of Storage Metrics

Pivotal recommends this if you have a large foundation and have experienced storage issues in the past.

Periodically take snapshots of storage metrics.

(Optional) Collect Logs

This information helps determine the cause of upgrade issues.

If you encounter problems during upgrade, collect the following information:

  • All job logs
  • Task debug logs for VM upgrade tasks
  • Installation log from Ops Manager

After Upgrade

After your upgrade, do the following to prepare for use of your new environment, check its health status, and clean up.

Re-create BOSH Alias

Re-create your alias using BOSH: bosh alias-env ALIAS -e DIRECTOR_IP

  • Reason: To log in to BOSH after upgrading PCF, you need to re-create your alias.
  • Product/Component: BOSH

Install New cf CLI

Download the version of the Cloud Foundry Command Line Interface (cf CLI) packaged with the PAS tile on Pivotal Network.

Check the Health of Your Deployment

  1. Run BOSH CLI commands to check system status:

    1. bosh -e ALIAS -d DEPLOYMENT_NAME instances --ps
    2. bosh -e ALIAS vms --vitals
    3. bosh -e ALIAS -d DEPLOYMENT_NAME cck --report

    Note/Reason: To ensure that all jobs and process are running as expected
    Product/Component: PCF and all tiles

  2. Push and horizontally scale a test application.

    • Reason: This is a performance test for PAS.
    • Product/Component: PCF
  3. If you are running PAS MySQL as a cluster, run the mysql-diag tool to validate health of the cluster.

    • Reason: See the BOSH CLI v2 instructions in the Running mysql-diag topic.
    • Product/Component: PAS

Check Resource Settings

If you added custom VM Type or Persistent Disk Type options, ensure that these values are correctly set and were not overwritten.

  • Note/Reason: Verify that the Ops Manager Resource Config pane still lists your custom options.
  • Product/Component: PCF

Run BOSH Clean-Up

Run bosh -e ALIAS clean-up --all to clean up old stemcells, releases, orphaned disks, and other unused resources.

  • Product/Component: Tiles

Run BOSH Restart on Your On-Demand Service Brokers

If you have installed any product tiles that use on-demand service brokers, such as MySQL for PCF, Redis for PCF, or RabbitMQ for PCF, then you must restart the broker for each tile. Restarting the broker ensures that the broker can communicate with the new version of CredHub.

To restart the broker for a tile, run the following command:


For example:

$ bosh -d my-deployment restart redis-on-demand-broker