Renaming your Rational solution for Collaborative Lifecycle Management server (version 4.0 and 4.0.0.1)
Note:This article is outdated and is replaced by Renaming your Rational solution for Collaborative Lifecycle Management server (version 4.0.1 and later) in the Deployment wiki. In the future, all deployment guidance and best practices will be published in the Deployment wiki rather than as Jazz.net articles. Purpose
The purpose of this document is to provide the basic information for customers to decide when and when not to use the Jazz server rename feature introduced in version 4 of the Rational solution for Collaborative Lifecycle Management products. This includes Rational Team Concert, Rational Requirements Composer, and Rational Quality Manager. Currently only a limited set of user scenarios are supported for server rename. As more user scenarios are thoroughly tested by IBM and validated in partnership with our customers, this document will be updated to add those user scenarios. The intention over time is to add full support of server rename for your production installation.
In addition, this document provides links to other related documents on jazz.net. One such document (Impact of Server Rename and Integrated Products by Schacher and Weil) provides more detailed information on the various product integrations and which of these provide support for the CLM server rename functionality. Over time, most if not all of these products will accommodate CLM server rename. As each of these integrations is made fully functional and thoroughly tested, its status will be updated in that document.
Definitions
Renaming your CLM server:
A CLM (or Jazz) Server Rename is defined as changing the public URL for the Jazz Team Server and/or one or more of its registered applications. The URL change can include any or all of the following components: protocol, hostname, domain, port, or context root. An example of a public URL for a Jazz Team Server would be the string https://clm01.mycompany.com:9443/jts.
CLM server:
A CLM server is defined as a web application server hosting one or more Jazz applications that are part of the IBM Rational solution for Collaborative Lifecycle Management.
Background on Public URL
One of the most challenging aspects of using the IBM Rational Jazz products is dealing with “linked artifacts” which use absolute URL links to access the encapsulated data. From the beginning, these links were explicitly chosen to make use of the architecture of the web, which uses URLs to reference objects and expects permanent (or at least long lived) addresses. The base part of the URL is called the “public URL”. This is the part that must stay consistent to permit assess to the artifacts hosted by that Jazz application.
The advantage of this approach is that it gives you the ability to access the artifact from any context including a browser bookmark or a hot link on a web page or in an email message. The disadvantage is the inability to move the artifact to a new server, change DNS hostnames or domains, or freely update your IT infrastructure to support change in project or organizational structure.
Other traditional, monolithic, database server-based SDLC products in the industry permit this freedom of movement, and the users also expect that from the Collaborative Lifecycle Management solution.
Since the nature of software and systems development shops is dynamic and constantly changing, there is a critical need for the CLM solution to support these changing environments with the product flexibility to permit the renaming of Jazz servers. Note, however, that changing the public URLs of existing CLM deployments can be disruptive, so it’s always best if you can plan ahead and use stable URLs.
Primary user scenarios for server rename
There are a number of reasons why server rename may be desired. Listed here are a few of the representative user scenarios with a note about whether they will be supported by the server rename concept that is currently under development. Each user scenario is marked as supported or not supported.
- Production to Staging: Copying a production server to a staging environment (some customers use the term “test sandbox”) so that new or not yet used functionality can be checked before it is introduced into the production environment. This also provides a way to try out product functionality such as administration or maintenance operations without using the production environment. Examples might include testing new project and process templates, work item customizations, integration with non-CLM tools, or trying out other CLM functions not yet used in the production environment. (Supported using Server Rename feature. Note: Only a limited subset of integrations are currently supported.)
- Pilot to Production: The CLM server was first used as a pilot implementation and now needs to be moved to the production IT environment. There are production rules that the current public URL do not meet. The IT department demands adherence to their standards. This may include moving to a secure connection or a different server name/domain/port. (Supported using Server Rename feature)
- Production to Production: The initial server name does not reflect the current environment. There may be a desire to use a server name based on the product’s function rather than use the name of the host machine or an IP address. Also the customer may want to move to a default port so non-local access is permitted without corporate firewall exceptions. (Not supported using Server Rename feature at this time)
Non-supported data reorganization scenarios
There are other user scenarios that customers are very interested in performing to modify the configuration of their production CLM installations. A few of the most common are listed below. These user scenarios are not in any way supported nor will they work. If either of these scenarios is attempted, it will result in a non-functional production environment. The development team will be reviewing these use cases for possible solutions in the future.
- CLM Consolidation – Merging JTS servers: The CLM products were implemented as multiple pilot or production installations and were originally hosted and managed separately. Now there is a desire to have the products integrated and centrally managed as a single CLM system. This would involve combining the multiple JTS instances and registering the applications with the combined JTS. (Not supported using Server Rename feature)
- CLM server split: The user population and/or number of projects has grown to the point where customer IT wants to split the projects across two CLM instances so that they can be separately administered and managed. Through some analysis of affinities, project areas are put on server A or server B with as few cross server linkages as can be managed for performance reasons. The strategy is to clone the production server and archive projects that are to be run from the other server. (Not supported using Server Rename feature)
- Project Move from one CLM server to another: The user wants to move project contents out of one CLM deployment and into the repositories of another. This is one of the top requests for enterprise deployments, but is also the most complex of the data reorganization scenarios. (Not supported using Server Rename feature)
- CLM server cloning: Replicating servers so that you can reuse the existing system to seed a “ready to run” fully configured new system. (Not supported using Server Rename feature) However, there are new command line setup capabilities that may help build newly configured systems more efficiently.
Server rename considerations
WARNING: Before deciding to use the Server Rename feature, there are some additional factors to consider. Because artifact links are used externally to the CLM system, any existing externally held links will no longer be valid. This would include all links that were included in email messages, web pages, and in integrated non-CLM products (unless they explicitly support CLM server rename) that may be in use in the customer’s environment.
Other products making use of OSLC linkages will require an implementation of a rename feature that scans for CLM links and adjusts them based on source/target (old/new) public URL pairs. However, you may have to upgrade those products or delay the rename operation until all of the integrated products can handle the renaming of the CLM system. For example, you must have Rational ClearQuest version 8.0.0.3_2012B in order to apply the server rename function for the bridged integration to the CLM system. Basically all of those links must be updated so that the integrated applications can continue to work properly and make use of all the functionality afforded by the linked data architecture of the CLM system and other applications using OSLC linkages.
Consult the Server Rename Integrations document to find the required version for each of your integrated systems and verify that all are available before using server rename.
Impact of a server rename
Once you have determined what use case applies to your use of the server rename feature and that it is supported, you can proceed to the product documentation that explains how to perform a server rename operation. There are three main steps in the rename process:
- Generating and editting the mapping file that contains all of the source/target URL mappings. This must be performed while the CLM servers are still online and it does not impact product functionality. (preparation step)
- Running an offline command to import the URL mappings into the JTS. All CLM servers in the topology must be shutdown prior to running this command. You will need to plan appropriately for the outage. (offline step)
- Bring up all CLM servers so that the applications can contact the JTS to synchronize their mappings. During this time, the JTS is in a special mode that blocks user access. All requests made to the JTS or any of its registered applications are redirected to a centralized server rename status page. When the rename completes on all applications and components, the JTS and applications will open for business. No server restart is required. (online step)
You will have to take your server offline to apply the rename mappings, and the applications then have to adapt their data to the new server names through either dynamic mappings or by rewriting all of the stored links in the database using a batch job. Both techniques are used depending on which database and application is involved.
For example, a batch update job is used to update the link tables in the data warehouse. Depending on the size of the data warehouse, this can take a few minutes. This link update process is done as part of the online step, and basic CLM service is not restored until this update process completes.
There are integrations with some subsystems within the CLM system that contain the CLM server’s public URL or at least the hostname of the server. While most of these are handled directly by the server rename operation, there are some that require manual updates. These include build engines and test adapters as well as some linkages such as live CLM data source feeds used by reporting tools. Instructions for updating these are included in the server rename instructions. Some of these steps can be manually intensive and require verification after the server rename operation.
If an error occurs during the second or third step of the server rename, or you made a mistake in the mapping input file, consult the product documentation to determine if the error is correctable. If it is not correctable, you will need to restore all of your databases and configuration files from your backups. Contact IBM Rational product support to determine how to rectify the problem.
Decision process
Once you have evaluated your server topology, integrations, and impact on your user community, you must make a decision whether to use server rename to accomplish your use case or whether to maintain the current public URL. Through the use of DNS mapping and hostname aliasing perhaps with a reverse proxy server, you may be able to maintain the current public URL. Leaving the public URL constant is certainly a preferred solution because it preserves all of the external references as well as those you can update through the server rename process. The linked data architecture used by the Jazz architecture (and the CLM system) expects the links to be stable and supported for a long period of time. Maintaining those links should be a high priority in setting up the CLM system.
Unlocking server rename
If maintaining the public URL is simply not an option for your CLM system, and you fit into one of the supported or possible use cases, you must contact IBM Rational product support to obtain a “Server Rename Feature Key File” to unlock the server rename feature.
During your discussion with product support, they will help you confirm that your rename usage pattern is consistent with a supported use of the server rename feature. They can also help you determine if IBM assistance is needed to help you perform the rename operation on your CLM system or if you need any additional fixes. The goal of this process is to make sure you are thoroughly informed of the process details. If you are not sure whether your user scenario is a “pilot to production” scenario or a “production to production” scenario, contact product support to engage help from IBM to help make the determination.
Server rename checklist
When you call IBM support, they will ask the following questions to ensure that you are ready to use server rename and understand it.
Server Rename Questions (All must be answered “Yes” to use this feature)
- Is the user scenario supported — either production to staging or pilot to production?
- IBM does not support renaming a production server using the server rename feature with v4.0 or v4.0.0.1.
- Are you sure that you are not attempting a different data reorganization scenario using the server rename feature?
- In no way does this feature permit the migration of project areas associated with one JTS to another, moving project areas from one application repository to another, or provide a way of creating two production environments in any form.
- Are all CLM applications and their JTS running the v4.0 GA (or later) product version. Is RRDI included and running v2.0 (or later)?
- If not, all applications must be upgraded to v4 before attempting a rename and v4.0.0.1 is strongly recommended.
- Note that you can not use server rename for staging a v3 to v4 upgrade.
- Version 3 to version 4 upgrade is a distinct, separate activity, and still requires stable URLs and an isolated network.
- However once you are running on version 4, you can use Server Rename in your staging environment for sandbox testing.
- Are all RTC client programs to be used to access the renamed system running the v4.0 GA (or later) product version?
- If not, you must upgrade all clients to v4 (or install separate v4 client instances) that will be used to access the renamed system.
- This is of primary importance for the pilot to production use case, so your users are warned when accessing a newly renamed CLM system.
- For the production to staging use case, the users of the staging (or test) system should use a separate client workspace and a separate v4 client to protect the production data against contamination from client interactions with the test system.
- Is the renamed CLM system isolated from all integrated applications other than RRDI, ClearCase, ClearQuest, Jazz build engines, and RQM test adapters?
- For the production to staging user scenario, the renamed CLM server should “stub out” (ie, set to a null system name) any other integrated system. If this is done, the newly renamed test system is effectively isolated from those integrated systems (including ClearCase and ClearQuest). See the product documentation for a complete explanation of this concept.
- For the production to staging user scenario to provide additional safety as a best practice, the /etc/hosts file on the renamed test server should redirect those previously integrated production system names to a bogus IP address so no automatic communication takes place between the renamed test system and the production integrated system.
- For the pilot to production user scenario, if there are integrated applications that do not yet support the CLM server rename, they will be broken after a server rename. For this reason, server rename can not be used when these integrations exist.
- Do not use the RQM Lab Management functionality, which does not yet support CLM server rename in v4.0.
- If you are using a Derby database in your pilot to production use case, do you understand the need to migrate the existing data repositories to a production database server?
- All production CLM systems are expected to use production quality databases that handle the scalability, robustness, and maintainability required in a production environment. This implies that the pilot Derby database will be migrated to DB2 or Oracle during the server rename to the new production CLM system. You will need to perform the “repotools –export” and “repotools –import” operations to migrate your data to the production database server as part of the CLM server rename procedure. See the topic “Changing the database vendor” in the Information Center for details.
- Are you planning to use SQL Server database for the CLM server after the server rename operation is completed?
- There is a critical defect that prevents CLM server rename from functioning properly on SQL Server based repositories in v4.0. This issue has been corrected in v4.0.0.1 and version 4.0.0.1 or later is required when using SQL Server databases.
- Will only one of these systems ever be used in the production environment?
- In the pilot to production use case, you are expected to NEVER restore to production service the original server image from before the CLM server rename. It has been replaced by the renamed CLM server.
- In the production to staging use case, you are expected to run both the staging and production versions of the system, but the staging version will not be integrated with production applications nor be used as a production system. It should remain in an isolated staging (or test) environment.
- Because of expected technical design limitations, the staging system and the production system can never be linked through a Jazz friend relationship or have linked data between the systems.
- There can be no linked data between the renamed system and the original system. Is this acceptable to you and for your intended use of the CLM servers?
- In the pilot to production user scenario, the pilot system with the original public URL is retired and never used again.
- In the production to staging user scenario, the staging system will never integrate with production applications but both remain active.
- By walking through the intended purposes for both the original and renamed CLM servers, it should be clear that the systems will not be linked nor used together in any way.
- Have you requested a Server Rename Feature Key to unlock the server rename feature from IBM product support?
- The server rename will fail if it can not find the feature key file in the directory specified in the email from IBM support.
Server rename usage instructions
This feature is fully documented in the CLM information center that can be found at: http://pic.dhe.ibm.com/infocenter/clmhelp/v4r0/topic/com.ibm.jazz.install.doc/topics/c_redeploy_server_server_rename_history.html
It is important to understand the impact and plan for the server rename event before actually performing the server rename operation. Here are some high level steps to follow:
- Plan your CLM topology (pre and post rename operation) including the current and future public URLs for each CLM application.
- Assess your non-CLM application integrations and whether CLM links will be updated by these applications.
- Make sure all of your user’s CLM clients are updated to version 4 in order to handle a server rename.
- For the production to staging user scenario, communicate to your user community that they should use a separate staging client workspace when connecting to the new staging environment and never connect to the production system with that workspace.
- For the pilot to production user scenario, communicate to your users that as a best practice they should check in all of their outstanding code before the rename occurs. For the version 4 clients, you do not have to start with a fresh workspace after the rename operation as the clients support a server rename. Include in the communication instructions the steps for updating their connection strings for the new server location.
- Plan your CLM system outage for the rename operation which needs to include some preparation time, actual down time, rename operation, and validation of linkages after rename.
- Communicate to the user community about the CLM system outage.
- Perform the steps described in the information center to complete the server rename.
- Validate that all CLM and integrated systems are fully functional after the rename. (See the information center for the recommended validation steps).
Summary
Renaming a server can be accomplished with proper planning and by carefully following the server rename instructions. Remember that there will be external links to CLM artifacts that are broken by performing a server rename. You should confirm that your purpose in doing a server rename is a supported use case for the rename operation as it is supported only for a limited set of scenarios. Assessment of integrations with other applications is crucial to prevent a loss of integrated system functionality. There are a number of CLM subsystems that depend on the public URL that may not be obvious and must be updated to accommodate the rename operation. Communication of the server rename with the CLM user community is very important and should be planned ahead of time and done carefully to reduce lost work or productivity as a result of the rename operation.
For more information
- CLM Information Center — Server Rename instructions
- Impact of Server Rename and Integrated Products — Article about CLM server rename integration support
- [Release Note]: WI 212875 – Inconsistent mappings applied during server rename (213295)
- [Release Note]: WI 212115 – Server Rename failed in SQL Server because of an index length error (212353)
- [Release Note]: WI 210004 – generateURLMappings does not filter URLs from the same application (213942)
About the author
David Chadwick is the technical lead of the Jazz Jumpstart Team for IBM Rational. He can be contacted at dchadwick@us.ibm.com.
Copyright © 2012 IBM Corporation.