# System Administrator’s Guide

# Hitless Upgrade Using Production Redeployment

Oracle Communications Services Gatekeeper supports seamless upgrades of Communication Services and Service Interceptors without service interruption. The upgrades are performed without disruptions in the traffic flow, without any need to restart servers, which means that the full processing capacity of the Oracle Communications Services Gatekeeper cluster is preserved during the hitless upgrade.

Hitless upgrades are performed using the Production Redeployment strategy, also referred to in WebLogic Server as side-by-side redeployment. For more information, see Oracle WebLogic Server Deploying Applications to WebLogic Server at http://download.oracle.com/docs/cd/E12840_01/wls/docs103/deployment.

Upgrades of container services provided by Oracle Communications Services Gatekeeper can not be done using production redeployment. Rolling upgrades should be used instead. See Oracle WebLogic Server Upgrading WebLogic Application Environments at http://download.oracle.com/docs/cd/E12840_01/wls/docs103/upgrade.

## Production Redeployment Overview

Production redeployment involves deploying a new version of an application alongside an older version of the same application. Weblogic Server automatically manages client connections so that only new client requests are directed to the new version. Clients already connected to the application during the redeployment continue to use the older version of the application until it has processed any pending request, at which point WebLogic Server automatically retires the older application. In this context, applications are network protocol plug-ins.

To support the production redeployment strategy, a plug-in must graceful shutdown. This means that it tracks any in-flight requests, and makes sure that it does not get undeployed while having any pending unprocessed requests. The WebLogic Server container takes care of parts of this, but all plug-ins need to perform protocol specific clean-up of any connections used for network traffic, and assert that all traffic is diverted to a new version of the module.

Production redeployments are performed on EAR file level, which means that all network protocol plug-ins that are tied to an application-facing interface are updated.

Service interceptors supports production redeployment.

## Production Redeployment Sequence

Below is a description of the Production Redeployment sequence:

1. The redeployment operation is triggered. It is performed on the administration server and targeted to all servers in the cluster.
2. The old version of the plug-in stops accepting new requests at the same time as the new version of the plug-in starts accepting them. At this point, both plug-ins are operational, the old version does not accept new requests. It only processes pending requests.
3. When the old version has no pending requests, it is undeployed automatically.

While both the new and the old version of version of the plug-in are active, both plug-ins are registered in the plug-in manager, with the version of the plug-in indicated. See Managing and Configuring the Plug-in Manager.

## Requirements for Production Redeployment

For production redeployment to work:

- The old version of the plug-in must:

- Perform protocol-specific clean-up of any connections or sessions towards the network nodes
- Assert that all traffic is diverted to the new version of the module.
- Track pending requests, if the network protocol used by the plug-in is not based on HTTP or RMI. Pending requests over HTTP and RMI are tracked by WebLogic Server mechanisms.

WARNING: | If this is not done properly, the old version could be undeployed prematurely.

- Report back to the container when ready to be undeployed.

- The new version of the plug-in must not:

- Change the schema used to define the data model for the named store in the StorageService
- Change the interface used between the Access Tier and the Network Tier in the communication service

## Typical Scenarios for Production Redeployment

- Communication services using HTTP-based network protocol plug-ins:

HTTP based network protocol plug-ins do not establish HTTP sessions when sending or receiving requests to the underlying network nodes. In the absence of sessions the Weblogic Server servlet container simply chooses the most recent/active version of a particular WAR module whenever new network triggered requests arrive. In-progress network triggered request are allowed to complete through the shutdown of EAR-scoped work managers. Before the older version of the EAR is retired, all of the pending work related to handling of the network triggered traffic is completed.

- Parlay X 2.1 Short Messaging-Binary SMS/SMPP communication service:

The Parlay X 2.1 Short Messaging-Binary SMS/SMPP plug-in handles graceful transition to ADMIN state as part of the server life-cycle or during EAR upgrade. Draining both application-initiated and network triggered traffic out of the older version is handled internally by the plug-in. Once a new version of the plug-in becomes available, the older version begins the process of completing the processing of all application initiated traffic it is responsible for. When all of the application-initiated traffic has switched to the newer version of the plug-in, the suspension of the network-triggered traffic in the older version is initiated. During the suspension of network triggered traffic, all new requests from the SMSC are rejected with `ESME_RSYSERR` error code in the responses. The in-progress network-triggered requests are acknowledged to the SMSC as they are processed by the application or are stored for later retrieval/processing. For requests that have received the `ESME_RSYSERR` response, the SMSC is expected to fail-over to the newer plug-in version. Application-initiated traffic is handled first in order to minimize the window during which the `ESME_RSYSERR` command status error codes are sent to the SMSC.

The new version of the plug-in will bind new receiver connections before the old version disconnects its receiver connections. This will ensure continuous network triggered traffic. No state is associated with the bind itself and any plug-in on any server is able to handle any network triggered traffic regardless of what server created the notifications. Only the volatile conversational state needs to be handled before the plug-in unbinds any of the ongoing connections toward the SMSC.

Hitless upgrade of both Transmitter/Receiver and Transceiver bind types are supported.

- Communication services using OSA/Parlay type plug-ins

The OSA access functionality is embedded in the Network Tier communication service EAR file, and any upgrades or updates to this part will follow the new EAR.

All application initiated traffic is switched to the newer version of a plug-in as soon as it becomes available. This prevents newer call sessions from being started against the older version. For application initiated traffic, the new OSA/Parlay plug-in might get traffic that concerns sessions started with the previous version in the case of long-lived sessions, such as call control. In this case, the old version must still be able to handle all call-backs from the OSA/Parlay Gateway that might be related to the traffic handled by the new version.

The OSA/Parlay plug-in counts the number of unfinished active sessions handled when it is being retired, and uses a barrier to inform the WebLogic Server container when all sessions have finished. This is the case for the Parlay X 2.1 Third Party Call/MPCC, Call Notification/MPCC, and Audio Call/MPCC-CUI plug-ins, where there are long lived sessions.

Each plug-in also has a time-out to provide a reasonable boundary for the overall graceful retirement duration.

The OSA/Parlay plug-ins use the managers replicated by the OSA Access module to create new notifications and set new call-backs.

- Communication services using SIP type plug-ins

SIP based Communication Services consists of an Oracle Communications Services Gatekeeper plug-ins and a SIP application. The Oracle Communications Services Gatekeeper side plug-ins can be hitlessly upgraded the same way as other Oracle Communications Services Gatekeeper plug-ins.

Graceful retirement is not supported for SIP applications. For the SIP Servlet part of the plug-ins, Oracle Communications Services Gatekeeper supports the same `-retiretimeout` option as WebLogic SIP Server.

- Extended Web Services Subscriber Profile/LDAP communication service

The Subscriber Profile/LDAP plug-in uses synchronous application-initiated traffic only. In-flight traffic is tracked and use a barrier is used to notify the WebLogic Server container when all traffic is completed.

The Subscriber Profile/LDAP plug-in uses synchronous application-initiated traffic only. In-flight traffic is tracked and use a barrier is used to notify the WebLogic Server container when all traffic is completed.

- Native SMPP communication service does not support hitless upgrades. The communication service needs to be undeployed and deployed to be updated.
- Native MM7 communication service handles hitless upgrades as described for HTTP-based network protocol plug-ins.

The EAR names for each communication service and the JAR names for the specific network protocol plug-in(s) contained within it can be found under the heading “Properties for <Communication service>” in the section of Oracle Communications Services Gatekeeper Administration Guide (this guide). See Deployment Model for Communication Services and Container Services for a description of how individual communication services are packaged.

## Performing a Hitless Upgrade

Oracle Communications Services Gatekeeper uses the WebLogic Server mechanism for production redeployment.

Below is the syntax for using weblogic.Deployer to do the upgrade:

    java weblogic.Deployer -adminurl <adminhost>:<adminport> -user <admin user> -password <password> -graceful -rmiGracePeriod <grace period> -redeploy -name <name> -source <EAR file> -targets <Cluster name>

In addition to the -graceful and -rmiGracePeriod flags, the -retiretimeout`<time period>` flag can be used to force stop the application after the given time period.

In the code snippet below the Network Tier part of the Parlay X 2.1 Multimedia Messaging communication service on a cluster named WLNG_NT_Cluster is redeployed:

    java weblogic.Deployer -adminurl <adminhost>:7001 -user weblogic -password weblogic -redeploy -rmiGracePeriod 30 -name wlng_nt_multimedia_messaging_px21 -source ./wlng_nt_multimedia_messaging_px21.ear -targets WLNG_NT_Cluster

The EARs are version-controlled, so the `meta-inf\MANIFEST.MF` file in the EAR must be updated with which version the EAR has:

    Manifest-Version: 1.0

    Ant-Version: Apache Ant 1.6.5

    Created-By: R27.5.0-101-94136-1.5.0_14-20080116-2103-windows-ia32 (BEA

      Systems, Inc.)

    Bundle-Name: wlng_at_multimedia_messaging_px21

    Bundle-Version: $<version>

    Bundle-Vendor: BEA Systems, Inc

    Weblogic-Application-Version: $<version>