Using IBM PureApplication System, you can create and deploy virtual servers in the cloud that represent middleware topologies and application configurations. However, you still face the challenge of moving existing application installation processes onto the cloud and automating them.
The following detailed instructions show you how to capture and automate the deployment of a middleware topology and application by using Advanced Middleware Configuration. This process is known as "onboarding."
Before you begin, read through the instructions and make sure you have the necessary permissions for all the steps you need to complete.
For more information about choosing between virtual application patterns and virtual system patterns, see the first two parts of this series, Part 1: Onboarding applications overview and Part 2: Is your application ready to become virtual?.
PureApplication System includes Advanced Middleware Configuration as a workload. Advanced Middleware Configuration stores configuration data on a framework server and uses the AMC Import Script Package to update that data. The AMC Integration Script Package incorporates that configuration data, including applications, in new virtual system patterns.
Use Advanced Middleware Configuration when more than one of the following conditions applies to you:
- You want to deploy applications as virtual system patterns.
- You do not have reliable end-to-end automation for the installation and configuration of applications.
- Your existing automation is specific to a single topology.
- You want to reduce your investment in low-level automation.
- You want to migrate WebSphere products into the cloud.
For more information about which applications can and cannot run as virtual applications, see Part 2 of this series, Is your application ready to become virtual?.
The onboarding process:
- Copies the topology of an existing WebSphere Application Server cell into the cloud.
- Creates a model server image from that pattern.
- Installs your application and configures the cell on the model server.
- Saves the new information in both the pattern and in Advanced Middleware Configuration.
- Deploys multiple instances of the model server.
Detailed instructions for this process are broken down into the following sections:
- Creating the framework server
- Creating a model VSP
- Provisioning and deploying the new VSP
- Installing and configuring the application
- Capturing the application in Advanced Middleware Configuration
- Deploying new instances of the application
In the Workload Console, click Patterns > Virtual Systems. From the Virtual System Patterns list on the left, click the supplied pattern named Advanced Middleware Configuration 1.0.
Figure 1. Deploying the framework server into the cloud
To deploy this pattern, simply click Deploy, or click the
accompanying icon, showing a green arrow above a cloud. Assign a name to
the new instance, such as
After the pattern has been deployed, the console automatically loads the
The next step is to set up a unique user ID and password for the virtual system pattern (VSP) you created. This ID is used for communication between the script packages and the framework server.
- Wait until you see a "ready" icon (white arrow in a green box) next to the instance name, or the Current status field shows "Virtual system is ready".
- Expand Virtual machines.
- Expand the first machine displayed. Scroll to the bottom of the display for the machine, find the Consoles section, and click AMC. A new browser window opens with the web client for Advanced Middleware Configuration.
The default user and password for the automation engine is root/root. Make a note of the host name of the framework server as well as the user credentials because you will need them to configure the Integration script package later.
- Log in to the framework server.
- Click Administration > Users.
- Enter the data for the new user, including an email address and password.
- Save the user.
- Select the new user from the list of users to load the details pane.
- Click the Change Groups tab.
- In the list of available groups on the left hand side, select
Build Engineer and click the Add
button as shown in Figure 2.
Figure 2. Adding the Build Engineer group
- Click Save.
On the Advanced Middleware Configuration framework server, configuration information is organized by environments, which are containers for one or more WebSphere cells. Advanced Middleware Configuration provides an Environment Generation wizard that you can use to create not only an environment on the framework server, but also a VSP in PureApplication System.
Your next step is to import the topology of the external cell that supports the application that you want to bring onboard. This article uses the HitCount application, part of the DefaultApplication package that is available for WebSphere Application Server, to provide a simple example. Note that you have to bring the topology and the application into the cloud separately and combine them there to create your model server.
If you leave the Virtual System Pattern Name blank, the wizard creates a configuration environment only and does not create a VSP.
To import the topology of the HitCount server:
- In the web interface of Advanced Middleware Configuration, click the EnvGen tab.
- Click Read an Existing Cell Configuration as shown in
Figure 3. The Environment Generation wizard
- Use the following values shown in Table 1 to complete the wizard fields. Not all the fields are included here. The example values are intended to be representative rather than definitive.
Table 1. Example values for completing the Environment Generation wizard
|Product or User Template||product|
|Existing Server Host Name||
| OS Username|
|These are the credentials that you need to connect to the host in the previous field.|
|Profile Root Directory||
|Create a pattern from this environment?||Yes|
|Place this environment under source control?||No. This article does not discuss issues of source control management.|
- Click Next to display the VSP questions. The next page of the wizard is displayed.
- Use the following values in Table 2 to complete the wizard fields on the VSP page. Not all of the fields are included here. The example values shown in Figure 4 are intended to be representative rather than definitive.
Table 2. Example values for completing the VSP generator page of the Environment Generation wizard
|Virtual System Pattern Name||
|Deployment Console Hostname||
|Framework Server User||The name of a unique user on the framework server that the wizard can use to log in. A password is also required. The LDAP domain is optional.|
|Database Details||Optional fields that you can use to update the hostname, user, password, and port number in the JDBC configuration.|
Figure 4. The VSP generator page
- Click Next. The VSP is created automatically.
The VSP that you created in the last step comes with two script packages that are specific to Advanced Middleware Configuration:
- AMC Import Script Package: Updates the cell definition on the framework server with the current state of the corresponding VSP.
- AMC Integration Script Package: Updates a new VSP with information from the corresponding cell definition on the framework server.
You will see the Import script package later. At this point, you are only concerned with the Integration script package, which is used when you deploy a new instance of a VSP. When you use the Environment Generation wizard to generate a VSP, the wizard provisions the Integration script package with the information you entered on the VSP page, including the name of the configuration environment you set up to represent the external server whose topology you copied.
When you deploy the new VSP to create a model server instance, you want to create a new configuration environment on the framework server. You can do this dynamically at deployment time.
- In the Workload Console, click Patterns > Virtual Systems and then click the name of the VSP that the Environment Generation wizard just created (HitCountPattern in this example).
- Click Deploy.
- Provide a name for the new instance you are creating. This instance
serves as a model for future instances you will create, so for the
purposes of this article we name it
- Click Configure virtual parts. If any parameters used in creating the new instance are unlocked, you have the option to change them at this point.
- Change the value of the RAFW_ENVIRONMENT parameter to a new value. You
previously created a configuration environment to represent the
external server. Now you want a second environment to represent the
virtual server you are creating. In this example, the new environment
- Click OK. The new instance and the new environment are created.
The RAFW_ENVIRONMENT field is concatenated with the cell name to determine if a set of configuration data and automation plans exists by that name. Because that data set does not yet exist, Advanced Middleware Configuration creates it.
Later in this article, you will see the case where the environment already exists. In that case, the script package uses the existing configuration information to update the instance it is creating.
The HitCountPattern VSP automatically deploys WebSphere Application Server
to the new instance. Use the Administrative Console to install your
application, or use any existing wsadmin scripts. Once the application
is installed, complete any configuration required. Typically, there is a
text file or an email with manual configuration instructions. Make sure
the new instance (
HitCountModelServer in this article) is set up the
way you want for all future systems that host the application.
The process for adding clusters or servers to the new instance, including proxy servers, requires an additional manual step. The extra step is required because of the way the workload console hands off the configuration work to Advanced Middleware Configuration.
- Use the Administrative Console to create the proxy server or other non-standard cluster or server on your virtual instance.
- Run the Import script package as described in the next section, Capturing the application in Advanced Middleware Configuration.
- Edit the Execute project for your environment in the Advanced
Middleware Configuration web client. This is one of three projects
that the Environment Generation wizard created for you. The project is
RAFW_env_cell_execute. Add steps that call Advanced Middleware Configuration actions to create the cluster or server, such as
was_common_configure_create_cluster. For a list of all actions, see the PureApplication Information Center under Working with virtual system patterns > Onboarding existing WebSphere applications > Working with onboard systems > Action command help.
Use the Import script package to update the cell definition on the framework server with the new information you added to the instance, that is, the information on how to install your application. The EAR file, all of the deployment options, and the WebSphere Application Server resources are captured. Changes to the clustering topology are not captured and are controlled by the VSP clustering settings.
The Import script package runs an Advanced Middleware Configuration automation plan named RAFW_env_cell_import. The Environment Generation wizard created this plan, and two others, in the same process that created the HitCountPattern VSP. You can use the project as-is, or you can save time by reducing the scope of the default project to exclude steps that are not used.
To edit an automation plan, complete the following steps:
- In the Advanced Middleware Configuration web client, click the Console tab.
- Click Projects in the left menu.
- Click the name of the project with your environment and cell name and the "import" suffix, such as "RAFW_VirtualHitCountEnv_was71_cell_import".
- On the Project page, check the box next to any steps that are not
required by the application (see Figure 5). An X indicates the step is
Figure 5. Steps in a project
- Save the project and exit.
To run the Import script package, complete the following steps:
- In the model server instance, where you just installed your application (HitCountModelServer in this article), expand Virtual machines.
- Expand the Deployment Manager part (or Server part if it is a standalone server).
- Scroll to the Script Packages section at the bottom of the page.
- Under the AMC Import Script Package heading, click
Execute now as shown in Figure 6.
Figure 6. Running the Import script package
When the script package completes, the configuration information on the framework server is updated.
When you deploy a new instance of your VSP (HitCountPattern in this example), the Integration script package runs the RAFW_env_cell_execute automation plan. As with the Import script package, you can edit the automation plan in the Advanced Middleware Configuration web client to streamline the process.
You are now ready to create as many exact copies of your model server (HitCountModelServer in this example) as you want. For each instance, complete the following steps:
- From the Virtual Systems display, click the name of your VSP (HitCountPattern in this example).
- Click Deploy.
- Provide a unique name for the new server instance.
- Click OK.
The following sections describe best practices for using the onboarding process.
Each application server contains a large amount of configuration data. By default, Advanced Middleware Configuration pulls in the entire application server configuration by making a connection to the node hosting the application server. Often only a small portion of the application server needs to be configured, such as enabling the Service Integration Bus (SIB) service or adding a JVM argument. In this case, you can store the settings at the cluster scope and apply them uniformly to each application server in the cluster by making a single connection to the deployment manager (per cluster). This single connection to the deployment manager and managing only the portions of the application servers requiring configuration changes decreases the time required to manage the configuration.
If the resource configuration data is all maintained at the cell or cluster scope, there is no need to waste time running actions at the node and server scopes. Disable the appropriate steps in the the the automation plan.
- Do not change your passwords.
- Do not change your external system dependencies, such as
- Do not change the number of nodes.
- Do not change any cell, cluster, or node names.
- Do not alter the topology of the clusters provided by the VSP.
This section provides details on what happens during deployment. Normally, a deployment requires no input or interaction from you.
When you deploy the model VSP, the Integration script package completes the following steps. The separate servers shown in Figure 7 represent virtual servers, that is, compute nodes within PureApplication System.
- Creates an instance of the virtual server (see Figure 7).
Figure 7. Process flow step 1
- Installs and initializes WebSphere Application Server (see Figure 8).
Figure 8. Process flow step 2
- Passes the details of the configuration environment to the framework
server, as shown in Figure 9.
Figure 9. Process flow step 3
The framework server then checks to see if the configuration environment exists.
If not, it sets up the environment using information it discovers on the new instance, and also creates three automation plans (see Figure 10).
Figure 10. No existing configuration environment
If the environment exists, the framework server pushes any applications and configuration information from the cell definition to the new instance (see Figure 11).
Figure 11. Configuration environment exists
See the Troubleshooting section for more information about the Integration script package flow.
The Integration script package creates the following artifacts in the Advanced Middleware Configuration web client (see Figure 12), which you can use to make changes to a running virtual system, capture changes in a running virtual system, or make a comparison between the cell definition on the framework server and the running configuration on the virtual system.
Figure 12. Artifacts created by the Integration script package
This section describes how the Integration script package works and how to approach any problems you encounter when you run it.
The Integration script package completes the following steps:
- Extracts the packaged files in the directory specified in the RAFW_HOME_PATH parameter.
- Runs the Advanced Middleware Configuration client. It establishes a connection to the framework server.
- Determines whether the configuration environment exists.
- If not, it is created on the framework server, as are three automation plans. Two of the three automation plans (import and execute) are shown in this article. The third plan compares values stored in the framework server with the live cell data. None of these automation plans are run.
- If an existing environment and cell name combination is found, the host name of each of the deployed systems is updated and the execute automation plan is run to configure resources and deploy applications to the newly created virtual system cell.
You can use the script package logs and automation plan logs to help you with troubleshooting.
You can view the logs for the script packages by expanding the dmgr part in the Instances > Virtual Systems view for your newly deployed VSP. Near the bottom of the expanded section is a listing of all the script packages run, as shown in Figure 13.
Figure 13. Script packages listing
remote_std_err.log file contains the log
information for each script package.
To view the results of the automation plan that was used to configure resources and applications in the VSPs, log on to the framework server using the web client:
- In the Consoles section of the framework server instance, click AMC to open the Advanced Middleware Configuration web interface.
- Within the web interface, click the Jobs menu item. Locate the job within the list. The job is named RAFW_env_cell_*, where the asterisk represents the word "execute", "import", or "compare".
The most common sources of errors are as follows:
- An incorrect hostname for the framework server, or incorrect credentials for the framework server user.
- The RAFW_HOME_PATH entry fails to correspond to the value specified
for OS_RAFW_HOME on the framework server. The default for AIX
or Linux is
/tmp/RAFW. If the value on the framework server differs from the value of the RAFW_HOME_PATH entry, a problem might occur in creating the required directories on the VSPs.
This section describes the workings of the Import script package
The Import script package completes the following steps:
- Contacts the framework server and attempts to locate the cell definition associated with the virtual system to which it is attached.
- Creates a new job in the Advanced Middleware Configuration web client using the RAFW_env_cell_import project.
- Continues to contact the framework server to check the status of that job until it completes.
If a user accidentally interrupts the network connection by logging into the Advanced Middleware Configuration web interface directly, the script continues to wait and then reconnects.
The script package invokes the import automation plan to capture all of the resources configured and applications installed in the cell into the cell definition on the framework server.
Note: As mentioned earlier, each user can only have a single logon session. Log on to the web user interface as a different user than the one that was identified in the virtual system script package.
In the course of this article, you have seen how to start with a WebSphere application and use IBM PureApplication System and Advanced Middleware Configuration to create a virtual system pattern that includes the application, and that you can repeatedly deploy in the cloud.
Part 1: Onboarding applications overview
Part 2: Is your application ready to become virtual?
Part 3: Choosing a database option
Part 5: Developing virtual application patterns for IBM Workload
Deployer with Rational Application Developer
PureApplication System Information Center
- IBM PureSystems
PureSystems resources on developerWorks
Barton Akeley is a Software Developer for Rational Enterprise Modernization and Compilers at the IBM Austin, Texas lab. He works on Rational Automation Framework, Advanced Middleware Configuration, and Rational Build Forge.