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

Upgrading to vCloud Director 5.1.x best practices (2034980)

  • 8 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.

NoteThe upgrade process requires you to upgrade vCloud Director, vShield Manager, vCenter Server, and your ESX/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
  • In-progress uploads of OVF packages and media images are suspended before the upgrade begins and resumed after the upgrade is complete
If your cloud uses a load balancer, 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 the vCenter Server. Upgrading vCenter Servers or ESX/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 new 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.1 best practices (2034092).
 
 
Upgrading a vCloud Director server group
 
To upgrade a vCloud Director server group:

  1. Disable user access to vCloud Director. If you want, you can also display a maintenance message when the upgrade is in progress. 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 in vCloud Director to quiesce and shut down a server (2034994).
  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 do not restart vCloud Director services on any 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, the upgrade is not allowed. The latest version of vShield Manager is required to use networking features introduced in this release of vCloud Director. For more information on upgrading vShield, see Upgrading to vShield 5.1.1 best practices (2034699).
  7. Re-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).
  9. Review the changes in your upgraded networks and reconfigure firewall rules as needed.


Using a load balancer to reduce service downtime

 
If you are using a load balancer or other tool that can force requests to go to specific servers, you can upgrade a subset of the server group while keeping existing services available on the remaining subset. This approach reduces vCloud Director service downtime to the length of time required to upgrade the vCloud Director database.
  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. For more information, see Using the Cell Management Tool in vCloud Director to quiesce and shut down a server (2034994).
  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 Upgrading 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 Upgrading to vShield 5.1.1 best practices (2034699).
  8. Upgrade vCenter Server and the ESX/ESXi hosts. For more information on performing the upgrade, 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.
  11. Upgrade vCloud Director on the remaining servers in the group and restart vCloud Director on those servers as the upgrades complete.
  12. Review the changes in your upgraded networks and reconfigure firewall rules as needed. 

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.1.0-xxxxxx.bin , where xxxxxx 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 all organizations in the system that contain an organization network also contain an organization vDC. Because the upgrade process converts existing organization networks to organization vDC networks, organizations that contain organization networks but do not contain an organization vDC cannot be upgraded, and the database upgrade fails.
  • Verify that you have superuser credentials for the target server.
  • If you want the installer to verify the digital signature of the installation file, download and install the VMware public key on the target server. If you have already verified the digital signature of the installation file, you do not need to verify it again during installation. For more information, see Downloading and installing the VMware Public Key to validate a vCloud Director installation (2005832).
  • Use the Cell Management Tool to quiesce and shut down vCloud Director services on the server's cell.
Procedure
 
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

    Where installation-file is the full pathname to the vCloud Director installation file.

  5. 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 in vCloud Director to quiesce and shut down a server (2034994).
  6. In a console, shell, or terminal window, run the installation file. To run the installation file, type its full pathname, for example ./installation-file. The file includes an installation script and an embedded RPM package.

    Note: You cannot run the installation file from a directory whose pathname includes any embedded space characters.

  7. Follow the wizard prompts to perform the upgrade.  When the vCloud Director software upgrade is complete, the installer displays a message indicating where the old configuration files are stored, then reminds you to run the database upgrade tool.
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. Take a backup of 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
  • Change this entry:

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

    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

Procedure

 

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.

  2. 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

    Perform one of these options:
    • 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 vCenter Server and ESX/ESXi Hosts

 
After you upgrade vCloud Director and its database, you can upgrade the vCenter Servers and ESX/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 and ESX/ESXi, see the vCloud Director Installation and Upgrade Guide.
 
Procedure
 
To upgrade:
  1. Upgrade the vCenter Server system. For more information, see Upgrading to vCenter Server 5.1 best practices (2021193).
  2. Upgrade each ESX/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 of upgrading to ESXi 5.1 (2032757).
    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.

 

Upgrade vShield

 
After you upgrade vCloud Director and its database, you can upgrade the vShield servers attached to your cloud to enable new vCloud Director features.
 
Note: A new installation of vShield cannot work with an existing version of vCloud Director.
 
After you upgrade a vCenter Server attached to vCloud Director, you should upgrade the vShield server associated with the upgraded vCenter server. Upgrading vShield interrupts access to vShield administrative functions, but does not interrupt network services. Upgrading a vShield Edge appliance briefly interrupts service on the networks that the appliance protects.
 
Prerequisites
  • At least one upgraded cell in your vCloud Director installation must be running before you begin this upgrade. The cell is responsible for writing data about the upgraded vShield to the vCloud Director database.
Procedure
 
To upgrade vShield:
  1. Upgrade vShield Manager. For more information, see Upgrading to vShield 5.1.1 best practices (2034699). 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.

See Also

Update History

03/14/2013 - Minor title change.

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

  • 8 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.
  • 8 Ratings
Actions
KB: