Search the VMware Knowledge Base (KB)
Products:
View by Article ID

Upgrading to VMware vCloud Director 5.5.x best practices (2059464)

  • 13 Ratings

Purpose

To upgrade vCloud Director to a new version, you must install the new version on each server in the vCloud Director server group, upgrade the vCloud Director database, and then restart vCloud Director services.
 
This article outlines the basics of performing the upgrade and assumes you have also read the vCloud Director Installation and Upgrade Guide.
 
Note: For more information, see the vCloud Director documentation. The documentation contains definitive information. If there is a discrepancy between the documentation and this article, assume that the documentation is correct.

Resolution

When you upgrade a vCloud Director server, you must also upgrade its vCloud Director database. The database stores information about the runtime state of the server, including the state of all vCloud Director tasks it is running. To ensure that no invalid task information remains in the database after an upgrade, you must ensure that no tasks are active on the server before you shut it down for the upgrade.

Note: The upgrade process requires you to upgrade vCloud Director, vShield Manager, vCenter Server, and your ESXi hosts. You must prevent users from accessing vCloud Director until the vShield Manager upgrade step is complete.

The upgrade preserves these artifacts:
  • Local and global properties files are copied to the new installation.
  • Microsoft sysprep files used for guest customization are copied to the new installation.

If you use a load balancer to distribute client requests across members of your vCloud Director server group, you can upgrade a subset of the server group, while keeping existing services available on the others. If you do not have a load balancer, the upgrade requires sufficient vCloud Director downtime to upgrade the database and at least one server. You might also have to upgrade registered vCenter Servers if they are not running a compatible version of vCenter software. Upgrading vCenter servers and ESXi hosts can incur additional vCloud Director downtime because virtual machines are inaccessible while their hosts or vCenter server are being upgraded. Details on how to perform these procedures are listed below.

Note: It is not possible to convert a previous vCloud Director Oracle database to Microsoft SQL. If you want to switch over to Microsoft SQL, you need to start a fresh database.

Before performing an upgrade, ensure you have met the minimum requirements before proceeding with the installation. For more information, see Installing vCloud Director 5.5.x best practices (20594510)

Upgrading a vCloud Director server group

To upgrade a vCloud Director server group:

  1. Disable user access to vCloud Director. You can also display a maintenance message while the upgrade is underway. For more information, see Configuring the VMware vCloud Director cell maintenance message (1026337).
  2. Use the cell management tool to quiesce all cells in the server group and shut down vCloud Director services on each server. For more information, see Using the Cell Management Tool to shut down a vCloud Director cell (1033575)
  3. Upgrade vCloud Director software on all members of the server group. For more information, see Upgrading vCloud Director software on any member of a server group. You can upgrade the servers individually or in parallel, but you must not restart vCloud Director services on any upgraded member of the group before you upgrade the vCloud Director database.
  4. Upgrade the vCloud Director database. For more information see, Upgrading the vCloud Director database.
  5. Restart vCloud Director on the upgraded servers. For more information, see Stopping, starting, or restarting the VMware vCloud Director service (1026310).
  6. Upgrade vShield Manager. All vShield Manager installations registered to this server group must be upgraded to a version of vShield Manager software that is compatible with the version of vCloud Director installed by the upgrade. If the upgrade program detects an incompatible version of vShield Manager, upgrading is not allowed. You must upgrade to the latest version of vShield manager listed in Supported Platforms to use networking features introduced in this release of vCloud Director. For more information, see Best practices for upgrading to VMware vCloud Networking and Security 5.5 (2055673).
  7. Enable user access to vCloud Director.
  8. Upgrade vCenter Server and your ESX/ESXi hosts. Current information about supported vCenter Server and ESX/ESXi is available from the VMware Product Interoperability Matrixes. For more information on performing the upgrade, see Upgrading vCenter Server, ESX/ESXi hosts, and vShield Edge Appliances for vCloud Director 5.1 (2035001).

Using a load balancer to reduce service downtime

  1. Use the load balancer to redirect vCloud Director requests to a subset of the servers in the group. Follow the procedures recommended by your load balancer.
  2. Use the cell management tool to quiesce the cells that are no longer handling requests and shut down vCloud Director services on those servers.

    Note: Console sessions routed through a server's console proxy are interrupted when the server shuts down. Clients can refresh the console window to recover. For more information, see Using the Cell Management Tool to shut down a vCloud Director cell (1033575).

  3. Upgrade vCloud Director software on the members of the server group on which you have stopped vCloud Director, but do not restart those services. For  more information, see Upgrade vCloud Director software on any member of a server group.
  4. Use the cell management tool to quiesce the cells that you have not yet upgraded and shut down vCloud Director services on those servers.
  5. Upgrade the vCloud Director database. For more information, see Upgrading the vCloud Director database.
  6. Restart vCloud Director on the upgraded servers. For more information, see Stopping, starting, or restarting the VMware vCloud Director service (1026310).
  7. Upgrade vShield Manager. For more information, see Best practices for upgrading to VMware vCloud Networking and Security 5.5 (2055673).
  8. Upgrade vCenter servers and hosts. For more information, see Upgrading vCenter Server, ESX/ESXi hosts, and vShield Edge Appliances for vCloud Director 5.1 (2035001).
  9. Use the load balancer to redirect vCloud Director requests to the upgraded servers.
  10. Upgrade vCloud Director software on the remaining servers in the group and restart vCloud Director on those servers as the upgrades complete. For  more information, see Upgrading vCloud Director Software on Any Member of a Server Group.

Upgrading vCloud Director software on any member of a server group

The vCloud Director installer verifies that the target server meets all upgrade prerequisites and upgrades the vCloud Director software on the server. vCloud Director software is distributed as a Linux executable file named vmware-vcloud-director-5.5.0-nnnnnn.bin, where nnnnnn represents a build number. After the upgrade is installed on a member of a server group, you must run a tool that upgrades the vCloud Director database that the group uses before you can restart vCloud Director services on the upgraded server.

Prerequisites

  • Verify that you have superuser credentials for the target server.
  • To have the installer verify the digital signature of the installation file, download and install the VMware public key on the target server. If you already verified the digital signature of the installation file, you do not need to verify it again during installation. For more information, see the Download and Install the VMware Public Key section in the vCloud Director Installation and Upgrade Guide.
  • Use the cell management tool to quiesce and shut down vCloud Director services on the server's cell.

To upgrade vCloud Director software on any member of a server group:

  1. Log in to the target server as root.
  2. Download the installation file to the target server. If you purchased the software on a CD/DVD-ROM or other media, copy the installation file to a location that is accessible to all target servers.
  3. Verify that the checksum of the download matches the one posted on the download page. Values for both MD5 and SHA1 checksums are posted on the download page. Use the appropriate tool to verify that the checksum of the downloaded installation file matches the one shown on the download page. A command with this form validates the checksum for installation-file using the MD5 checksum-value copied from the download page:

    md5sum -c checksum-value installation-file

  4. The installation file requires the execute permission. To be sure that it has this permission, open a console, shell, or terminal window and run this command:

    chmod u+x installation file

    Whereinstallation-file is the full path name to the vCloud Director installation file.

  5. In a console, shell, or terminal window, run the installation file. To run the installation file, type its full path name, for example ./installation-file. The file includes an installation script and an embedded RPM package.
  6. Use the cell management tool to quiesce the cell and shut down vCloud Director services on the server. For more information, see Using the Cell Management Tool to shut down a vCloud Director cell (1033575).
What to do next

Upgrading the vCloud Director database

After you upgrade a server in your vCloud Director server group, you must upgrade the group's vCloud Director database before you restart vCloud Director services on the server.

Note: During the upgrade you can run into SQL commands which can take a long time to execute. A best practice, before you upgrade the database, increase the database connection timeout from 90 to 900.

To increase the database connection timeout:
  1. Back up the global.properties file using this command:

    cp /opt/vmware/vcloud-director/etc/global.properties /opt/vmware/vcloud-director/etc/global.properties.bak

  2. Open the file using a text editor:

    vi /opt/vmware/vcloud-director/etc/global.properties
  • Locate this entry within the file:

     database.jdbcUrl = jdbc:jtds:sqlserver:\/\/10.131.77.81:1433\/vcloud;socketTimeout=90

  • Change this entry to:

     database.jdbcUrl = jdbc:jtds:sqlserver:\/\/10.131.77.81:1433\/vcloud;socketTimeout=900

Note: After the upgrade completes, it is recommended to revert the timeout value. 

Prerequisites

To Upgrade the vCloud Director database:

  1.  Open a console, shell, or terminal window and run this command to run the database upgrade script:

    opt/vmware/vcloud-director/bin/upgrade

    Note: If the database upgrade script detects that an incompatible version of vShield Manager is registered to this installation of vCloud Director, it displays a warning and cancel the upgrade.

    You see this database upgrade prompt:

    Welcome to the vCloud Director upgrade utility

    This utility will apply several updates to the database. Please ensure you have created a backup of your database prior to continuing.

    Do you wish to upgrade the product now? [Y/N]: y

  2. Perform one of these steps:
  • To continue the upgrade, press Y.
  • To exit to the shell without making any changes in the current vCloud Director database, press N.

The database upgrade tool now runs and displays progress messages.

Upgrading vShield

To upgrade vShield :

  1. Upgrade vShield Manager. For more information, see the Upgrading vShield section in the vShield Installation and Upgrade Guide. After this upgrade completes, vShield notifies vCloud Director that it has a new version. It can take several minutes before vShield sends the notification and vCloud Director processes it.
  2. Upgrade all vShield Edge appliances that the upgraded vShield manages. Use the vShield user interface to manage this upgrade.
Note: If you use the vCloud Director Web console or REST API to reset a network that vShield Edge protects, this upgrade occurs automatically. Using the vShield user interface to manage the vShield Edge provides better administrative control over the upgrade process and related network downtime.

Upgrading vCenter Server and ESXi hosts

After you upgrade vCloud Director and its database, you can upgrade the vCenter Servers and ESXi hosts attached to your cloud to enable new vCloud Director features.

This upgrade is optional, but several vCloud Director features depend on it. For a list of vCloud Director features that depend on new versions of vCenter Server and ESXi, see the vCloud Director Installation and Upgrade Guide.

Procedure

  1. Upgrade the vCenter Server system. For more information, see Methods of upgrading to vCenter Server 5.5 on a Windows operating system (2053130).
  2. Upgrade each ESXi host that the upgraded vCenter Server supports.

    1. Use vCenter Server to put the host into maintenance mode and allow all the virtual machines on that host to migrate to another host.
    2. Upgrade the host. For more information, see Methods for upgrading to ESXi 5.5 (2058352).
    3. Take the host out of maintenance mode.

      Note: To ensure that you have enough upgraded host capacity to support the virtual machines in your cloud, upgrade hosts in small batches. When you do this, host agent upgrades can complete in time to allow virtual machines to migrate back to the upgraded host.

After the host is upgraded, vCloud Director detects the new version and upgrades the host agent.


See Also

Request a Product Feature

To request a new product feature or to provide feedback on a VMware product, please visit the Request a Product Feature page.

Feedback

  • 13 Ratings

Did this article help you?
This article resolved my issue.
This article did not resolve my issue.
This article helped but additional information was required to resolve my issue.

What can we do to improve this information? (4000 or fewer characters)




Please enter the Captcha code before clicking Submit.
  • 13 Ratings
Actions
KB: