Upgrading Applications Without Loss of Availability

Upgrading an application to a new version without loss of availability to users is called a rolling upgrade. Carefully managing the two versions of the application across the upgrade ensures that current users of the application complete their tasks without interruption, while new users transparently get the new version of the application. With a rolling upgrade, users are unaware that the upgrade occurs.

Application Compatibility

Rolling upgrades pose varying degrees of difficulty depending on the magnitude of changes between the two application versions.

If the changes are superficial, for example, changes to static text and images, the two versions of the application are compatible and can both run at once in the same cluster.

Compatible applications must:

• Use the same session information

• Use compatible database schemas

• Have generally compatible application-level business logic

• Use the same physical data source

You can perform a rolling upgrade of a compatible application in either a single cluster or multiple clusters. For more information, see Upgrading In a Single Cluster.

If the two versions of an application do not meet all the above criteria, then the applications are considered incompatible. Executing incompatible versions of an application in one cluster can corrupt application data and cause session failover to not function correctly. The problems depend on the type and extent of the incompatibility. It is good practice to upgrade an incompatible application by creating a “shadow cluster” to which to deploy the new version and slowly quiesce the old cluster and application. For more information, see Upgrading Incompatible Applications.

The application developer and administrator are the best people to determine whether application versions are compatible. If in doubt, assume that the versions are incompatible, since this is the safest approach.

Upgrading In a Single Cluster

You can perform a rolling upgrade of an application deployed to a single cluster, providing the cluster’s configuration is not shared with any other cluster.

To upgrade an application in a single cluster

1. Save an old version of the application or back up the domain.

   To back up the domain use the asadmin backup-domain command. For more information on the command, see backup-domain(1).

2. Turn off dynamic reconfiguration (if enabled) for the cluster.

   To do this with Admin Console:

   1. Expand the Configurations node.

   2. Click the name of the cluster’s configuration.

   3. On the Configuration System Properties page, uncheck the Dynamic Reconfiguration Enabled box.

   4. Click Save

   Alternatively, use this command:

   asadmin set --user user --passwordfile password-file cluster-name-config.dynamic-reconfiguration-enabled=false

3. Redeploy the upgraded application to the target domain.

   If you redeploy using the Admin Console, the domain is automatically the target. If you use asadmin, specify the target domain. Because dynamic reconfiguration is disabled, the old application continues to run on the cluster.

4. Enable the redeployed application for the instances using asadmin enable-http-lb-application. For more information on the command, see enable-http-lb-application(1).

5. Quiesce one server instance in the cluster from the load balancer.

   Follow these steps:

   1. Disable the server instance using asadmin disable-http-lb-server.For more information on the command, see disable-http-lb-server(1).

   2. Export the load balancer configuration file using asadmin export-http-lb-config. For more information on the command, see export-http-lb-config(1).

   3. Copy the exported configuration file to the web server instance’s configuration directory.

      For example, for Sun Java System Web Server, the location is web-server-install-dir/https-host-name/config/loadbalancer.xml. To ensure that the load balancer loads the new configuration file, be sure that dynamic reconfiguration is enabled by setting the reloadinterval in the load balancer configuration.

   4. Wait until the timeout has expired.

      Monitor the load balancer’s log file to make sure the instance is offline. If users see a retry URL, skip the quiescing period and restart the server immediately.

6. Restart the disabled server instance while the other instances in the cluster are still running.

   Restarting causes the server to synchronize with the domain and update the application.

7. Test the application on the restarted server to make sure it runs correctly.

8. Re-enable the server instance in load balancer.

   Follow these steps:

   1. Enable the server instance using asadmin enable-http-lb-server. For more information on the command, see enable-http-lb-server(1).

   2. Export the load balancer configuration file using asadmin export-http-lb-config. For more information on the command, see export-http-lb-config(1).

   3. Copy the configuration file to the web server’s configuration directory.

9. Repeat steps 5 through 8 for each instance in the cluster.

10. When all server instances have the new application and are running, you can enable dynamic reconfiguration for the cluster again.

Upgrading in Multiple Clusters

To Upgrade a Compatible Application in Two or More Clusters:

1. Save an old version of the application or back up the domain.

   To back up the domain, use the asadmin backup-domain command. For more information on the command, see backup-domain(1).

2. Turn off dynamic reconfiguration (if enabled) for all clusters.

   To do this with Admin Console:

   1. Expand the Configurations node.

   2. Click the name of one cluster’s configuration.

   3. On the Configuration System Properties page, uncheck the Dynamic Reconfiguration Enabled box.

   4. Click Save

   5. Repeat for the other clusters

   Alternatively, use this command:

   asadmin set --user user --passwordfile password-file cluster-name-config.dynamic-reconfiguration-enabled=false

3. Redeploy the upgraded application to the target domain.

   If you redeploy using the Admin Console, the domain is automatically the target. If you use asadmin, specify the target domain. Because dynamic reconfiguration is disabled, the old application continues to run on the clusters.

4. Enable the redeployed application for the clusters using asadmin enable-http-lb-application. For more information on the command, see enable-http-lb-application(1).

5. Quiesce one cluster from the load balancer

   1. Disable the cluster using asadmin disable-http-lb-server. For more information on the command, see disable-http-lb-server(1).

   2. Export the load balancer configuration file using asadmin export-http-lb-config. For more information on the command, see export-http-lb-config(1).

   3. Copy the exported configuration file to the web server instance’s configuration directory.

      For example, for Sun Java System Web Server, the location is web-server-install-dir/https-host-name/config/loadbalancer.xml. Dynamic reconfiguration must be enabled for the load balancer (by setting the reloadinterval in the load balancer configuration), so that the new load balancer configuration file is loaded automatically.

   4. Wait until the timeout has expired.

      Monitor the load balancer’s log file to make sure the instance is offline. If users see a retry URL, skip the quiescing period and restart the server immediately.

6. Restart the disabled cluster while the other clusters are still running.

   Restarting causes the cluster to synchronize with the domain and update the application.

7. Test the application on the restarted cluster to make sure it runs correctly.

8. Enable the cluster in the load balancer:

   1. Enable the cluster using asadmin enable-http-lb-server. For more information on the command, see enable-http-lb-server(1).

   2. Export the load balancer configuration file using asadmin export-http-lb-config. For more information on the command, see export-http-lb-config(1).

   3. Copy the configuration file to the web server’s configuration directory.

9. Repeat steps 5 through 8 for the other clusters.

10. When all server instances have the new application and are running, you can enable dynamic reconfiguration for all clusters again.

Upgrading Incompatible Applications

If the new version of the application is incompatible with the old version, use the following procedure. For information on what makes applications compatible, see Application Compatibility. Also, you must upgrade incompatible application in two or more clusters. If you have only one cluster, create a “shadow cluster” for the upgrade, as described below.

When upgrading an incompatible application:

• Give the new version of the application a different name from the old version of the application. The steps below assume that the application is renamed.

• If the data schemas are incompatible, use different physical data sources after planning for data migration.

• Deploy the new version to a different cluster from the cluster where the old version is deployed.

• Set an appropriately long timeout for the cluster running the old application before you take it offline, because the requests for the application won’t fail over to the new cluster. These user sessions will simply fail.

To Upgrade an Incompatible Application by Creating a Second Cluster

1. Save an old version of the application or back up the domain.

   To back up the domain use the asadmin backup-domain command. For more information on the command, see backup-domain(1).

2. Create a “shadow cluster” on the same or a different set of machines as the existing cluster. If you already have a second cluster, skip this step.

   1. Use the Admin Console to create the new cluster and reference the existing cluster’s named configuration.

      Customize the ports for the new instances on each machine to avoid conflict with existing active ports.

   2. For all resources associated with the cluster, add a resource reference to the newly created cluster using asadmin create-resource-ref. For more information on the command, see create-resource-ref(1).

   3. Create a reference to all other applications deployed to the cluster (except the current redeployed application) from the newly created cluster using asadmin create-application-ref. For more information on the command, see create-application-ref(1).

   4. Configure the cluster to be highly available using asadmin configure-ha-cluster. For more information on the command, see configure-ha-cluster(1).

   5. Create reference to the newly-created cluster in the load balancer configuration file using asadmin create-http-lb-ref. For more information on the command, see create-http-lb-ref(1).

3. Give the new version of application a different name from the old version.

4. Deploy the new application with the new cluster as the target. Use a different context root or roots.

5. Enable the deployed new application for the clusters using asadmin enable-http-lb-application. For more information on the command, see enable-http-lb-application(1).

6. Start the new cluster while the other cluster is still running.

   The start causes the cluster to synchronize with the domain and be updated with the new application.

7. Test the application on the new cluster to make sure it runs correctly.

8. Disable the old cluster from the load balancer using asadmin disable-http-lb-server. For more information on the command, see disable-http-lb-server(1).

9. Set a timeout for how long lingering sessions survive.

10. Enable the new cluster from the load balancer using asadmin enable-http-lb-server. For more information on the command, see enable-http-lb-server(1).

11. Export the load balancer configuration file using asadmin export-http-lb-config. For more information on the command, see export-http-lb-config(1).

12. Copy the exported configuration file to the web server instance’s configuration directory.

    For example, for Sun Java System Web Server, the location is web-server-install-dir/https-host-name/config/loadbalancer.xml. Dynamic reconfiguration must be enabled for the load balancer (by setting the reloadinterval in the load balancer configuration), so that the new load balancer configuration file is loaded automatically.

13. After the timeout period expires or after all users of the old application have exited, stop the old cluster and delete the old application.