Skip to content

How Platform Automation Upgrades Ops Manager

This topic provides a high level overview of upgrading an Ops Manager using Platform Automation, including command requirements and common version check and IaaS CLI errors.

It's important to note when upgrading your Ops Manager:

  • always perform an export installation
  • persist that exported installation
  • installation is separate from upgrade
  • an initial installation is done, which maintains state

Always export your installation


It is recommended to persist the zip file exported from export-installation to an external file store (eg S3) on a regular basis. The exported installation can restore the Ops Manager to a working state if it is non-functional.

Upgrade Flowchart

The upgrade-opsman task follows the flow based on state of an Ops Manager VM. This flowchart gives a high level overview of how the task makes decisions for an upgrade.

graph TD; versionChk[Is the existing Ops Manager version less than the Ops Manager image?]; versionError[Version Check Error]; delete[Delete the existing Ops Manager VM]; create[Create a new Ops Manager VM]; iaasErr[IAAS CLI error]; import[Import the provided Installation]; iaasErr2[IAAS CLI error]; versionChk -- No --> versionError; versionChk -- Yes --> delete; delete -- Success --> create; delete -- Failure --> iaasErr; create -- Success --> import ; create -- Failure --> iaasErr2;

On successive invocations of the task, it will offer different behaviour of the previous run. This aids in recovering from failures (ie: from an IAAS) that occur.

Command Requirements

The upgrade-opsman task will delete the previous VM, create a new VM, and import a previous installation. It requires the following to perform this operations:


When you are upgrading your Ops Manager you may get version check or IaaS CLI errors. For information about troubleshooting these errors, see Version Check Errors and IaaS CLI Errors below.

Version Check Errors

1) Downgrading is not supported by Ops Manager (Manual Intervention Required)

  • Ops Manager does not support downgrading to a lower version.
  • SOLUTION: Try the upgrade again with a newer version of Ops Manager.

2) Could not authenticate with Ops Manager (Manual Intervention Required)

  • Credentials provided in the auth file do not match the credentials of an already deployed Ops Manager.
  • SOLUTION: To change the credentials when upgrading an Ops Manager, you must update the password in your Account Settings. Then, you will need to update the following two files with the changes: auth.yml env.yml

3) The Ops Manager API is inaccessible (Recoverable)

  • The task could not communicate with Ops Manager.
  • SOLUTION: Rerun the upgrade-opsman task. The task will assume that the Ops Manager VM is not created, and will run the create-vm and import-installation tasks.


1) When the CLI for a supported IAAS fails for any reason (i.e., bad network, outage, etc) we treat this as an IAAS CLI error. The following tasks can return an error from the IAAS's CLI: delete-vm, create-vm

  • SOLUTION: The specific error will be returned as output, but most errors can simply be fixed by re-running the upgrade-opsman task.