Production redeployment Design Spec 1. Introduction 1.1 Project/Component Working Name Production redeployment 1.2 Name(s) and e-mail address of Document Author(s)/Supplier Marian Muller : marian.muller@serli.com
Serge Petit : serge.petit@serli.com
Pierre-Henry Soulaneix : pierre-henry.soulaneix@serli.com 1.3 Date of This Document 12/19/2012 1.4 Highlevel features overview See the one pager for a higher-level specification. 2. Implementation 2.1 Principle To support the deployment of two concurrent enabled versions, a private context-root is used to deploy each version of an application. This is called the tagged context-root, as it is prefixed by the version identifier. Requests targeting the public context-root (a.k.a. untagged context-root) are simply routed to the right version by switching to the tagged context-root. The right version to be used is chosen using the rules exposed in the one pager. 2.2 Domain.xml An attribute will be added to the application-ref element : retirement-time. This attribute will hold the date and time when the retirement period of a version ends. An example of application version stored with its retirement period end time in domain.xml:
<application-ref ref="foo:1.0" virtual-servers="server" retirement-time="2012-12-19 03:40:29"></application-ref>
The date and time of the retirement period end are computed using the retirement timeout and the current date/time when enabling a version. 2.3 Deployment Related Admin Classes The production redeployment must be triggered when enabling a version. The impacted commands are deploy, undeploy , disable and enable. All the impacted classes will evolve so they can trigger the production redepoyment and accept the associated configuration options. To manage the active and retired versions of all the deployed applications, a production redeployment service will be added, or the versioning service will be extended. 2.3.1 Production redeployment classes The production redeployment service will store the state of the active and retired versions for each enabled application. It will provide an API to access and maintain this state. The API will consist of 7 operations :
- Enable an application version without using production redeployment. This marks the given version as active. No version is kept as retired.
- Enable an application version using production redeployment. This marks the given version as active, and keeps the previous active version as retired.
- Disable an application version, whether it was active or retired.
- Get the tagged context-root of the active version of an application.
- Get the tagged context-root of the retired version of an application.
- Get the tagged context-root of the version attached to a given session id. If no version is attached to the session id, get the tagged context-root of the active version.
- Set the session manager for an application version. This is mandatory for the service to be able to find the version attached to a given session id.
On top of this service API, utility classes will provide two operations :
- Get the tagged context-root from the given untagged context-root and version identifier.
- Get the untagged context-root from a given tagged context-root.
2.3.2 Deploy command The deploy command will be adapted to maintain the application versions state, each time an enabled version is deployed. This means the command will have to set the deployed version as active in the production redeployment service whenever deploying an enabled version. This is true even when the production redeployment is not used. The deploy command will also have to modify the application context-root so it is actually deployed using the tagged context-root. Finally, the deploy command will be adapted to trigger production redeployment when used with the --retiretimeout option. This means the previous version is not disabled before deploying. The previous active version is simply marked as retired in the production redeployment service, and therefore planned to be disabled later. If there is already a retired version, the production redeployment cannot be used as per limitations stated in the one pager. In this case, the command simply displays an error telling the user to explicitely disable the retired version before deploying a new one. 2.3.3 Enable command The enable command will be adapted similarly to the deploy command. It will maintain the application versions state, each time a version is enabled. The command will have to set the deployed version as active in the production redeployment service whenever enabling a version. This is true even when the production redeployment is not used. The enable command will be adapted to trigger production redeployment when used with the --retiretimeout option. This means the previous version is not disabled before enabling. The previous active version is simply marked as retired in the production redeployment service, and therefore planned to be disabled later. If there is already a retired version, the production redeployment cannot be used as per limitations stated in the one pager. In this case, the command simply displays an error telling the user to explicitely disable the retired version before enabling a new one. However, if the version being enabled is the retired version, the version will simply be marked as active, while the previous active version is marked as retired. The retirement period of the version being enabled is cancelled, while the newly retired version will have a retirement period of the time specified using --retirementtimeout. This allows to roll the retired version back without losing any client session. 2.3.4 Disable command The disable command is less impacted by production redeployment. It simply needs to maintain the application versions state, each time a version is disabled. The command will have to remove the disabled version from the production redeployment service, whether it was active or retired. As the command may target several versions using a wildcard, both active and retired versions may be disabled using a single command call. 2.3.5 Undeploy command The undeploy command is less impacted by production redeployment. It simply needs to maintain the application versions state, each time a version is undeployed. The command will have to remove the undeployed version from the production redeployment service whenever an enabled version is undeployed, whether it was active or retired. As the command may target several versions using a wildcard, both active and retired versions may be undeployed using a single command call. 2.3.6 List-applications command The list-applications command must be enhanced to display production redeployment related informations when used with the --long option. Following the best practices, this information is read from the domain.xml file. The command will display two additional columns in its output:
- EXTENDED_STATUS specifies if an enabled version is either active or retired.
- RETIRES_ON specifies the retirement period end date and time of a retired version.
2.3.7 Disabling the retired version A version that is kept as retired (because of production redeployment) is automatically disabled after a certain time, depending on the --retiretimeout value :
- If --retiretimeout is negative, the retired version is disabled only when all its sessions have expired. This requires to keep track of the number of valid or expired sessions for a given version.
- Otherwise, the retired version is disabled after the given timeout, in seconds. A timer is set right after the version is retired, and is triggered when the given timeout is reached.
A retired version is simply disabled by running the disable command with the application name, the version identifier and the target used when it was enabled. 2.4 Web Container Classes Production redeployment requires to be able to deploy two versions of the same application concurrently. Web container will have to provide a way to support this, and a mechanism to route incoming HTTP requests depending on their session information. 2.4.1 ContainerMapper class Web application versions are deployed using their tagged context-root. The ContainerMaper class will be adapted to route the requests targeting the untagged context-root (that is, the public context-root) to the right tagged context-root (that is, the private context-root). One main purpose of the ContainerMapper is to determine which application should serve an incoming request. But once the application is known, it will have to determine which version should serve the request.
To get the tagged context-root of the right version to use, the ContainerMapper will start by extracting the requested session id from the request cookies and/or path parameters. The production redeployment service can be called to get the tagged context-root of the right application version from a given session id. If a tagged context-root is found, the mapping data of the incoming request are overwritten so that the right application is called to serve the request. 2.4.2 Catalina container classes 2.4.2.1 Session manager When the catalina container of a web application version is initialized, its session manager must immediately be sent to the production redeployment service, so it is able to link a session id to its application version. 2.4.2.2 Context-root correction As all application versions are deployed using a tagged context-root, there are some places where the untagged context-root must be restored :
- When setting a cookie, it must be set using the untagged context-root in its path.
- When redirecting a request to an application default resource (e.g. redirecting 'contextroot/' to 'contextroot/index.jsp'), the redirection must use the untagged context-root.
2.5 GUI GUI will be affected, to allow users to trigger production redeployment when deploying or enabling a version. |
