Overview of migration, coexistence, and interoperability

Migrating to a new version of WebSphere® Application Server requires careful consideration of factors such as your product edition, profile types, server configuration, and application deployment. This overview introduces the concepts, terminology, tools, and strategies to help you successfully migrate the product.

Common migration terminology

The following terms are frequently used to discuss migration:

Version or release: An update to the product that includes significant new function.
Edition: Within a version, product packaging that includes certain sets of features. For example, Network Deployment.
Profile: A set of files that defines the runtime environment for an application server process, such as a deployment manager or an application server. Profiles contain the configuration for how the application server behaves and where applications are deployed.
Source: The origin of the data and objects for the migration, such as source profile or source machine.
Target: The destination of the data and objects for the migration, such as target profile or target machine.
Node: A grouping of managed or unmanaged servers or server clusters. Each node that is managed by a cell can have a unique configuration.
Cell: A group that contains a deployment manager that manages one or more nodes or configurations. Nodes in the cell are federated to the deployment manager. The cell-level configuration is common across all nodes.
Mixed-cell environment: When the release of at least one federated node is older than the release of the deployment manager that manages the cell. Nodes cannot be more than three releases older than the deployment manager.

Basic migration concepts

Migration is the process of moving the configuration from an older release to a new release, such that the new configuration behaves as closely as possible to the old configuration. The main unit for a migration is the profile, which is migrated in 3 basic steps:

Take a snapshot of the source profile from the old installation.
Create a compatible target profile in the new installation.
Merge the data from the snapshot into the target profile.

Migrating a cell, which contains the deployment manager and federated nodes, requires special attention. Because the deployment manager controls the configuration in the cell, each node must be synchronized with the new deployment manager as it is migrated.

Migration strategies

When you plan your migration, consider the following possible migration strategies:

Standard vs. clone migration

Standard: The source configuration is disabled after it is migrated to the target configuration.
Clone: The source configuration remains functional after it is migrated to the target configuration.

Local vs. remote migration

Local: The configuration is migrated on the same machine. For clone migrations, the result is two coexisting environments.
Remote: The configuration is migrated to virtual machines hosted by the IBM Cloud® using remote and clone migration strategies.

On-prem vs. cloud migration

On-prem: The configuration is migrated to locally-owned machines using any of the previous migration strategies.
Cloud: The configuration is migrated to a new machine.

Migration tools

The tools that you use to migrate your product configuration must be run from the new installation at the target release. If possible, update the new installation to the latest available fix pack before you begin your migration. The WebSphere Application ServerVersion 9.0 migration tools support migration only from Version 7.0 or later and do not support migrating within the same release, for example from Version 9.0 to Version 9.0. To replicate your configuration across machines of the same version or release, see the information about property-based configuration or use the wsadmin scripting exportWasprofile command in the ConfigArchiveOperations command group for the AdminTask object.

Migration uses the following main command-line tools:

WASPreUpgrade: Takes a snapshot of the source profile from the old installation and places it in a backup directory. For remote migrations, the WASPreUpgrade command collects additional artifacts that are referenced by your configuration in the backup directory.
manageprofiles: Creates the target profile. The target profile must be the same type as the source profile; for example, you cannot migrate a deployment manager profile to a stand-alone application server profile. Depending on the type of profile, you must also match the cell name, node name, or both of the source profile.
WASPostUpgrade: Merges the data in the migration backup directory into the target profile. You can specify additional options control whether the old configuration is disabled, whether to postpone installing the applications, and more.

The Configuration Migration Management Tool, or migration wizard, is a graphical user interface (GUI) tool that guides you through running the command-line tools.

The configuration migration tools deploy your applications as they existed in the source profile onto the target profile. Before you migrate your configuration, test your applications in a non-production WebSphere Application Server Version 9.0 environment. Then, make any changes to the applications that are necessary to ensure that they run in that environment. To quickly identify any required changes, you can scan your applications by using the Migration Toolkit for Application Binaries and the WebSphere Application Server Migration Toolkit.

You can run the WASMigrationAppInstaller command as many times as necessary to install any applications that were not installed by the WASPostUpgrade command.

For remote migrations, you can use the createRemoteMigrJar command to create a .jar file that enables you to run the WASPreUpgrade command on a system that does not have WebSphere Application Server installed.

Use the migration tools to migrate applications and configuration information to the new version as described in Migrating product configurations. Read Using the migration tools for more information.

Mixed-cell environments

Note: Only standard migrations support mixed-cell environments. Clone migrations do not support mixed-cell environments.

A cell can contain nodes from different WebSphere Application Server versions. A WebSphere Application Server Version 9.0 mixed cell can contain nodes that support WebSphere Application Server Version 9.0 and Version 7.0 or later. In a mixed-cell environment, if a member of a cell is older than Version 7.0, the tools cannot migrate the deployment manager. The administrator must either migrate the nodes to at least Version 7.0 or remove them from the cell.

A mixed cell environment can exist in two ways:

You perform incremental node migration of your existing system.
1. You migrate the deployment manager to Version 9.0. The deployment manager has to be at the level of the highest node version. If you have nodes of the previous version, then this migration of the deployment manager creates a mixed cell at the highest version of WebSphere Application Server.
2. Then when you migrate one node at a time to this new highest version, the cell becomes a cell at the highest version of WebSphere Application Server.
  Note: This cell cannot be at a higher version than the deployment manager.
You migrate the deployment manager to Version 9.0 and then federate older version nodes to the new version deployment manager. This form of migration is supported for only Version 7.0 or later nodes.
1. First, you migrate the deployment manager to Version 9.0. The deployment manager has to be at the level of the highest node version.
2. You then can federate nodes from Version 7.0 or later to the new highest deployment manager version.
Avoid trouble: This method of incremental migration leaves your system in a mixed cell environment with nodes administered by a Version 9.0 deployment manager. Your migration planning should eventually include migrations of all nodes to the Version 9.0 level to ensure consistent administration of the nodes.

Existing functions continue to work in a mixed-cell environment. You should be able to perform reasonable operations, such as run existing applications, perform management operations, such as addNode, create mixed cluster, configure the system, call Mbeans, and deploy applications. New function support in a mixed cell environment can be decided on a case by case basis - based on function, priority and available resources.

Avoid trouble: When running in a mixed-cell environment, clients might suddenly encounter a situation where the port information about the cluster members of the target cluster has become stale. This situation most commonly occurs when all of the cluster members have dynamic ports and are restarted during a time period when no requests are being sent. The client process in this state will eventually attempt to route to the node agent to receive the new port data for the cluster members, and then use that new port data to route back to the members of the cluster.

If any issues occur that prevent the client from communicating with the node agent, or that prevent the new port data being propagated between the cluster members and the node agent, request failures might occur on the client. In some cases, these failures are temporary. In other cases you need to restart one or more processes to resolve a failure.

To circumvent the client routing problems that might arise in these cases, you can configure static ports on the cluster members. With static ports, the port data does not change as a client process gets information about the cluster members. Even if the cluster members are restarted, or there are communication or data propagation issues between processes, the port data the client holds is still valid. This circumvention does not necessarily solve the underlying communication or data propagation issues, but removes the symptoms of unexpected or uneven client routing decisions.

If you neither migrate nor coexist with an earlier version of WebSphere Application Server, you are choosing to ignore the previous installation and you can run only one version at a time because of conflicting default port assignments. It is possible for both versions to run at the same time without conflict if you use non-default ports in one version.

Potential migration issues

Consider the following issues in a migration or coexistence scenario:

Conflicting context roots when attempting to share the same web server.
Follow the procedure in Migrating web server configurations to learn how to configure a web server for sharing between WebSphere Application Server versions.
If your deployment manager is configured to run as non-root, follow the instructions in Migrating non-root configurations to root to change the ownership and file permissions of the deployment manager directories after running the WASPostUpgrade command.
This task must be completed before you start the WebSphere Application ServerVersion 9.0 deployment manager.

Read WASPostUpgrade command for more information.
If your node agent or application server has been configured to run as non-root, follow the instructions in Migrating non-root configurations to root to change the ownership and file permissions of the node directories after running the WASPostUpgrade command.
This task must be completed before you start the WebSphere Application Server Version 9.0 node agent or application server.

Read WASPostUpgrade command for more information.

Other information

WebSphere Application Server Version 9.0 can coexist with Version 7.0 or later. Depending on the previous version of WebSphere Application Server, port conflicts might exist that must be resolved. See Running coexisting application servers and Configuring port settings for more information.

WebSphere Application Server migration leverages the existing configuration and applications and changes them to be compatible with the WebSphere Application Server Version 9.0 environment. Existing application components and configuration settings are applied to the Version 9.0 environment during the migration process.

If you use an earlier version of WebSphere Application Server, the system administrator might have fine-tuned various application and server settings for your environment. It is important to have a strategy for migrating these settings with maximum efficiency.

You can perform incremental migration of your WebSphere Application Server Version 7.0 or later configuration by running the migration tools multiple times, each time specifying a different set of profiles. Incremental migration of your WebSphere Application Server usually involves operating your system in a mixed-cell release environment. Migration in this environment involves node migrations at various times and as such, may result in mixed cells running for extended periods of time until migration is complete.