Upgrade Procedure for an AppFabric Cache Cluster (AppFabric 1.1)

This topic describes how to perform both an offline and online upgrades of the Microsoft AppFabric 1.1 for Windows Server Caching Service to a higher version for an existing cache cluster. An online upgrade involves upgrading each cache host in separately while the cache cluster remains running.

Each release of Microsoft AppFabric 1.1 for Windows Server is associated with a particular version number of the AppFabric Caching Service.

Offline Upgrade Process

An offline upgrade involves a cache cluster that has been shut down. While shut down, each cache host can be upgraded separately to the new version of AppFabric. At this point, the steps involved are a subset of the online upgrade steps and include the following.

1. Step 1: Update the Cache Administration feature on the administration machine

2. Step 5: Update the allowed Server Version range to only use the new version number

3. Step 6: Update the allowed Client Version range to include the new version number

4. Step 7: Update the cache configuration store

5. Step 8: Update the cache client applications

Online Upgrade Process

An online upgrade consists of the following steps:

• Step 1: Update the Cache Administration feature on the administration machine

• Step 2: Update the allowed Server Version range to include the new version number

• Step 3: Upgrade each cache host sequentially

• Step 4: Verify that all of the cache hosts have been upgraded

• Step 5: Update the allowed Server Version range to only use the new version number

• Step 6: Update the allowed Client Version range to include the new version number

• Step 7: Update the cache configuration store

• Step 8: Update the cache client applications

Step 1: Update the Cache Administration feature on the administration machine

To perform the update steps, you should first update the Cache Administration feature on a machine that is not a part of the target cache cluster. The Cache Administration feature allows you to run Windows PowerShell commands against a cache cluster. Upgrade the Cache Administration feature by running the AppFabric setup for the new version of Microsoft AppFabric 1.1 for Windows Server.

If you do not already have a separate machine for managing the cache cluster, you can install the Cache Administration feature of the new version of Microsoft AppFabric 1.1 for Windows Server on a machine outside the cache cluster.

In order to run the Windows PowerShell commands on an administration-only machine, you must first run the Use-CacheCluster command and specify both the Provider and ConnectionString parameters. This is described in the topic Common Cache Cluster Management Tasks (AppFabric 1.1 Caching).

Step 2: Update the allowed Server Version range to include the new version number

During the online upgrade, some servers will be running the old version of the Caching Service and others the upgraded version. To account for this, you must use the Update-CacheHostAllowedVersions Windows PowerShell command to increase the value of the EndServerVersion property. For example, if you were moving from version 1 to version 3, you would use the following command.

Update-CacheHostAllowedVersions –EndServerVersion 3

Then run the Get-CacheHost command without parameters to verify the version changes. The following example output shows this change on a three-node cache cluster.

HostName : CachePort Service Name            Service Status Version Info
-------------------- ------------            -------------- ------------
CACHESERVER1:22233 AppFabricCachingService UP             1 [1,3][1,1]
CACHESERVER2:22233 AppFabricCachingService UP             1 [1,3][1,1]
CACHESERVER3:22233 AppFabricCachingService UP             1 [1,3][1,1]

The Version Info column in this example contains the value 1 [1,3][1,1]. This corresponds to the following version details:

Before continuing, you must make sure that each cache host has been updated to the target allowed server range. If any cache hosts failed to have their server version range updated, then you must shut them down before proceeding. This can be done with the Stop-CacheNonUpdatedHosts Windows PowerShell command. The Get-CacheHost command can be used first to predict which servers have not been updated and will be stopped. The following example stops any cache hosts whose version range has not been changed to 1 and 3 and whose current service version is 1.

Stop-CacheNonUpdatedHosts -Version 1 -BeginServerVersion 1 –EndServerVersion 3

Step 3: Upgrade each cache host sequentially

To perform an online upgrade, each cache host is stopped and upgraded separately. The following steps describe the steps that must be taken for each cache host in the cache cluster.

1. On the Caching Administration machine, use Windows PowerShell to run the Stop-CacheHost command to stop the cache host.

   Warning

   If the High Availability feature is not in use, stopping a cache host can result in lost cached data. Even with High Availability, clients may get temporary exceptions that will resolve on retry attempts if the cluster remains running.

2. On the stopped cache host, upgrade the Microsoft AppFabric 1.1 for Windows Server to the new version by running the setup for the new version.

3. After the upgrade completes, use Start-CacheHost to restart the cache host.

4. Next run Get-CacheClusterHealth. Make sure that all numbers are in the "Healthy" category and that the cache fractions have stabilized across the cache hosts. Also, verify that there are no entries in the "Unallocated fraction" or "Unallocated named cache fractions". You can verify this by running Get-CacheClusterHealth multiple times until the cache fractions stabilize.

5. Repeat these steps for the next cache host in the cache cluster.

During this part of the process, the use of the following Windows PowerShell commands is unsupported. You should not use these commands until all cache hosts are updated to the new version and the begin server version range has been updated to the new version.

The commands that generate an error have text similar to the following: ErrorCode<ERRPS024>:SubStatus<ES0001>:This command is not currently allowed. Changes to the cache cluster configuration is restricted during a rolling upgrade of the caching service.

* Update-CacheHostAllowedVersions does not generate an error when all of the cache hosts in the cluster are running the same version of the AppFabric Caching Service.

Step 4: Verify that all of the cache hosts have been upgraded

After upgrading each cache host, use the Get-CacheHost command to view the version of the Caching Service on each cache host. They must all be equal to the new version before continuing. Consider the following example output from Get-CacheHost:

HostName : CachePort Service Name            Service Status Version Info
-------------------- ------------            -------------- ------------
CACHESERVER1:22233 AppFabricCachingService UP             3 [1,3][1,1]
CACHESERVER2:22233 AppFabricCachingService UP             3 [1,3][1,1]
CACHESERVER3:22233 AppFabricCachingService UP             1 [1,3][1,1]

In this example, the first two servers are now running the updated Caching Service with a version of 3. But the CACHESERVER3 machine is still running the old version of the Caching Service with a version of 1. This cache host must either be upgraded successfully using the previous step, or it must be stopped to continue in the upgrade process.

Step 5: Update the allowed Server Version range to only use the new version number

Use the Update-CacheHostAllowedVersions command to increase the BeginServerVersion to the new version.

Update-CacheHostAllowedVersions –BeginServerVersion 3

The following example shows the result of Get-CacheHost after this step has been completed in a three node cluster where the target version is 3.

HostName : CachePort Service Name            Service Status Version Info
-------------------- ------------            -------------- ------------
CACHESERVER1:22233 AppFabricCachingService UP             3 [3,3][1,1]
CACHESERVER2:22233 AppFabricCachingService UP             3 [3,3][1,1]
CACHESERVER3:22233 AppFabricCachingService UP             3 [3,3][1,1]

At this point, you can use any available Windows PowerShell commands as well as any new features provided by the upgrade.

Step 6: Update the allowed Client Version range to include the new version number

Applications built to use the new Cache Client features need to be able to communicate with the upgraded cache cluster. Use the Update-CacheHostAllowedVersions command to include the new version in the range of allowed cache client versions. The following example does this by increasing the EndClientVersion parameter to 3.

Update-CacheHostAllowedVersions -EndClientVersion 3

The following example shows the result of this change in the output of Get-CacheHost.

HostName : CachePort Service Name            Service Status Version Info
-------------------- ------------            -------------- ------------
CACHESERVER1:22233 AppFabricCachingService UP             3 [3,3][1,3]
CACHESERVER2:22233 AppFabricCachingService UP             3 [3,3][1,3]
CACHESERVER3:22233 AppFabricCachingService UP             3 [3,3][1,3]

At this point, you can update any applications to use the new cache client assemblies and features. If you want to restrict the cache clients to only be those of the new version, you can also use Update-CacheHostAllowedVersions to change the BeginClientVersion to the new version number. However, you also have the choice to leave a range of versions to allow both new and old clients to continue to use the cache cluster. If you do decide to restrict cache clients to a specific version, you must first update all of those clients to that version before increasing the BeginClientVersion value.

Step 7: Update the cache configuration store

Update the cache configuration store with the Update-CacheConfigurationStore command. This command can only be used after all cache hosts have been upgraded.

Update-CacheConfigurationStore

Among other internal changes, this command translates the host names in the cache cluster configuration to use their fully-qualified domain names (FQDN).

Step 8: Update the cache client applications

As mentioned in the previous step, cache client applications need to use the new AppFabric Caching assemblies to take advantage of new AppFabric Caching features or to communicate with a cache cluster that has a version range that is restricted to the latest version (for example, 3,3).

It is important to note that the AppFabric Caching assemblies are no longer registered in the Global Assembly Cache (GAC). This means that you have to locate both the cache client application binaries and the AppFabric Caching assemblies together. Or you can use the <assemblyBinding> section in the application configuration file. The <codeBase> element can point to the location of the assemblies.

  2012-10-26