You can perform in-place upgrades on roles that are running in the staging deployment slot or the production deployment slot, as long as the new service model is identical to that of the service you are upgrading.
Windows Azure organizes instances of your roles into virtual groupings called upgrade domains. When you upgrade one or more roles within your service in-place, Windows Azure upgrades sets of role instances according to the upgrade domain to which they belong. Windows Azure upgrades one domain at a time, stopping the instances running within the upgrade domain, upgrading them, bringing them back online, and moving on to the next domain. By stopping only the instances running within the current upgrade domain, Windows Azure ensures that an upgrade takes place with the least possible impact to the running service.
.gif) Note |
|
You cannot perform an in-place upgrade to add or remove roles from your service, to add or remove configuration settings, or otherwise modify the service definition. If you are upgrading your service's definition, you must perform a VIP swap upgrade instead. See Performing Virtual IP Swap Upgrades for more information.
Note that your service must define at least two instances of a role in order for it to be upgraded in-place. If the service defines only one instance of a role, that role will be taken offline while it is upgraded. |
Distribution of Roles Across Upgrade Domains
Windows Azure distributes instances of a role evenly across a set number of upgrade domains. You can specify the number of upgrade domains for your service in the service definition file. The default number of upgrade domains is 5. For more information on modifying the service definition file, see Service Definition Schema.
For example, if your role has ten instances, by default each upgrade domain contains two instances. If your role has fourteen instances, then four of the upgrade domains contains three instances, and a fifth domain contains two.
Upgrade domains are identified with a zero-based index: the first upgrade domain has an ID of 0, and the second upgrade domain has an ID of 1, and so on.
The following diagram illustrates how two roles comprising a service are distributed when the service defines two upgrade domains. The service is running eight instances of the web role and nine instances of the worker role.
.png)
|
Note |
|
Note that Windows Azure controls how instances are allocated across upgrade domains. It's not possible to specify which roles are allocated to which domain. |
How the Upgrade Proceeds
You can choose whether you wish to upgrade all of the roles in your service, or a single role within your service. In either case, all instances of each role that is being upgraded and that belong to the first upgrade domain are stopped, upgraded, and brought back online. Once they are back online, the instances in the second upgrade domain are stopped, upgraded, and brought back online.
The following diagram illustrates how the upgrade proceeds if you are upgrading all of the roles in the service:
.png)
This next diagram illustrates how the upgrade proceeds if you are upgrading only a single role:
.png)
In-Place Upgrades Via the Developer Portal
To perform an in-place upgrade via the Developer Portal, display the Summary page for your hosted service, then click the Upgrade… button for the deployment you wish to upgrade (staging or production). On Upgrade page, you have the following options:
-
Upgrade Mode: Select Automatic to upgrade all upgrade domains, or Manual to upgrade one domain at a time.
-
Application Package: You can upload an application package from your local file system, or point to an application package stored in the Blob service.
-
Configuration Settings: You can upload a new configuration file from your local file system, or point to a configuration file stored in the Blob service.
-
Service Deployment Name: Specify a name for the updated deployment.
-
Service Upgrade: Specify whether to upgrade the whole service, or just a single role within the service.
In-Place Upgrades Via the Service Management API
When you upgrade a service's roles using the Service Management API, you must first upload the service package to the Windows Azure Blob service. You will specify the Blob service address of the package to be used for the upgrade. For more information on the Blob service, see Blob Service API.
The Service Management API provides two REST operations for upgrading your roles. You call Upgrade Deployment to initiate the upgrade. With this operation you specify the following data:
-
The identifier of the service deployment to upgrade, or the deployment slot (staging or production).
-
The upgrade mode, which may be either automatic or manual. If you specify automatic, the upgrade proceeds without further input. If you specify manual, you then need to call the Walk Upgrade Domain operation to initiate the upgrade process for each upgrade domain.
-
The address of the package containing the new version of the service. The package must first have been uploaded to the Windows Azure Blob service.
-
The service configuration file for the new version of the service, encoded as Base64.
-
The name of the role to upgrade, if you are upgrading a single role. If you are upgrading all of the roles in the service, you can omit this parameter.
If you've specified manual for the upgrade mode, then you must also call the Walk Upgrade Domain operation to upgrade each domain. This operation stops the role instances within the specified upgrade domain, upgrades them, and restarts them.
To completely upgrade your role, you must call Walk Upgrade Domain twice, once for each upgrade domain. Note that you must walk the upgrade domains in sequence, beginning with the domain whose ID is 0. Attempting to walk upgrade domains out of sequence returns an error.
See Also