Introduction

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.

Back to top

Virtual applications vs. virtual system patterns

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?.

Back to top

When to use Advanced Middleware Configuration

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?.

Back to top

Overview of the onboarding process

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

Back to top

Creating the framework server

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.

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 AMCFrameworkServer. After the pattern has been deployed, the console automatically loads the new instance.

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.

1. 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".
2. Expand Virtual machines.
3. 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.

Creating a user for the framework server

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.

1. Log in to the framework server.
2. Click Administration > Users.
3. Enter the data for the new user, including an email address and password.
4. Save the user.
5. Select the new user from the list of users to load the details pane.
6. Click the Change Groups tab.
7. 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
   
   
   
8. Click Save.

Back to top

Creating a model VSP

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:

1. In the web interface of Advanced Middleware Configuration, click the EnvGen tab.
2. Click Read an Existing Cell Configuration as shown in Figure 3.
   
   Figure 3. The Environment Generation wizard
   
   
   
3. 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.

4. Click Next to display the VSP questions. The next page of the wizard is displayed.
5. 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.

6. Click Next. The VSP is created automatically.

Back to top

Provisioning and deploying the new VSP

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.

1. 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).
2. Click Deploy.
3. 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 HitCountModelServer.
4. 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.
5. 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 is named VirtualHitCountEnv.
6. 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.

Back to top

Installing and configuring the application

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.

Adding clusters or servers

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.

1. Use the Administrative Console to create the proxy server or other non-standard cluster or server on your virtual instance.
2. Run the Import script package as described in the next section, Capturing the application in Advanced Middleware Configuration.
3. 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 named 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.

Back to top

Capturing the application in Advanced Middleware Configuration

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.

Customizing the automation plan

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:

1. In the Advanced Middleware Configuration web client, click the Console tab.
2. Click Projects in the left menu.
3. Click the name of the project with your environment and cell name and the "import" suffix, such as "RAFW_VirtualHitCountEnv_was71_cell_import".
4. 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 disabled.
   
   Figure 5. Steps in a project
   
   
   
5. Save the project and exit.

Running the script package

To run the Import script package, complete the following steps:

1. In the model server instance, where you just installed your application (HitCountModelServer in this article), expand Virtual machines.
2. Expand the Deployment Manager part (or Server part if it is a standalone server).
3. Scroll to the Script Packages section at the bottom of the page.
4. 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.

Back to top

Deploying new instances of the application

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:

1. From the Virtual Systems display, click the name of your VSP (HitCountPattern in this example).
2. Click Deploy.
3. Provide a unique name for the new server instance.
4. Click OK.

Back to top

Optimizations

The following sections describe best practices for using the onboarding process.

Avoid configuring application servers directly

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.

Avoid scopes without 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.

Back to top

Restrictions

• Do not change your passwords.
• Do not change your external system dependencies, such as database/mq servers.
• 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.
• Specify RAFW_HOME_PATH as /tmp/RAFW.

Back to top

Additional information on deploying an application to a VSP

This section provides details on what happens during deployment. Normally, a deployment requires no input or interaction from you.

Process Flow

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.

1. Creates an instance of the virtual server (see Figure 7).
   
   Figure 7. Process flow step 1
   
   
   
2. Installs and initializes WebSphere Application Server (see Figure 8).
   
   Figure 8. Process flow step 2
   
   
   
3. 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.

Artifacts

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.

Back to top

Troubleshooting the script packages

This section describes how the Integration script package works and how to approach any problems you encounter when you run it.

Integration script package flow

The Integration script package completes the following steps:

1. Extracts the packaged files in the directory specified in the RAFW_HOME_PATH parameter.
2. Runs the Advanced Middleware Configuration client. It establishes a connection to the framework server.
3. 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.

Viewing the logs

You can use the script package logs and automation plan logs to help you with troubleshooting.

Script package logs

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.

The remote_std_err.log file contains the log information for each script package.

Automation plan logs

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:

1. In the Consoles section of the framework server instance, click AMC to open the Advanced Middleware Configuration web interface.
2. 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".

Troubleshooting tips

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.

Back to top

Additional information on capturing an application from a VSP into Advanced Middleware Configuration

This section describes the workings of the Import script package

Understanding the Import script package flow

The Import script package completes the following steps:

1. Contacts the framework server and attempts to locate the cell definition associated with the virtual system to which it is attached.
2. Creates a new job in the Advanced Middleware Configuration web client using the RAFW_env_cell_import project.
3. 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.

Back to top

Conclusion

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.

Resources

• 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
  
  
• IBM PureApplication System Information Center
  
  
• IBM PureSystems Centre
  
  
• IBM PureSystems resources on developerWorks
  
  

About the authors

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.

John Gough is an Information Developer at the IBM Austin, Texas lab. He works on Rational Automation Framework, Advanced Middleware Configuration, and Rational Build Forge.

Lewis Shiner is a contract technical writer in Raleigh, North Carolina. He works on Rational Automation Framework and Advanced Middleware Configuration.

Rate this article

Comments

Back to top

Table of contents

• Introduction
• Virtual applications vs. virtual system patterns
• When to use Advanced Middleware Configuration
• Overview of the onboarding process
• 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
• Optimizations
• Restrictions
• Additional information on deploying an application to a VSP
• Troubleshooting the script packages
• Additional information on capturing an application from a VSP into Advanced Middleware Configuration
• Conclusion
• Resources
• About the authors
• Comments

Next steps from IBM

Learn more, join the cloud community

---

• Community: Cloud computing conversations led by IBM community members
• Buy: Try IBM software on IBM SmartCloud Enterprise

Dig deeper into WebSphere on developerWorks

IBM SmartCloud trial. No charge.

Unleash the power of hybrid cloud computing today!

---

Public and private solutions in one trial.

Special offers