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 applications onto the cloud and automating them.
This article describes 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.
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, Onboarding migrations overview and Is your application ready to become virtual?.
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. An AMC Cleanup Script Package is also available to delete configuration data.
Use Advanced Middleware Configuration when more than one of the following conditions applies to you:
- You want to deploy JEE 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?.
Overview of the onboarding process
The onboarding process:
- Creates a configuration definition based on an existing WebSphere Application Server cell.
- Inserts the resources and applications from the existing cell.
- Creates a template that is the model for the virtual servers you will create.
- Generates a virtual system pattern (VSP) from the template.
- Deploys multiple instances of the pattern in the cloud.
Detailed instructions for this process are broken down into the following sections:
- Creating the framework server
- Creating a configuration definition from the existing cell
- Creating a template from a configuration definition
- Creating a VSP from a template
- Deploying the new VSP
- Deploying new instances of the application
- Updating the template
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.1. The pattern name includes a platform designation, either x86 or Power, as shown in Figure 1.
Figure 1. Deploying the framework server into the cloud
To deploy this pattern, 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 displayed virtual machine. Scroll to the bottom of the display for the machine, find the Consoles section, and click AMC. A new browser window opens with the console for Advanced Middleware Configuration.
Creating a user for the framework server
The default user and password for the console is root/root. Make a note of the host name of the framework server as well as the user credentials you are about to create because you will need them for the VSP generator later.
- Log in to the console as root.
- Click Administration > Users.
- Click the green plus sign above the user list to create a user.
- Enter the data for the new user, including an email address and
password, as shown in Figure 2.
Figure 2. Entering new user data
- Click Create to save the user. The new user is displayed in the edit pane.
- In the edit pane, expand the Access groups heading and click the Add button at the bottom of the Access group display.
- In the list of available groups, select Build
Engineer and click the Add button as
shown in Figure 3.
Figure 3. Adding the Build Engineer group
- Click Save.
- Click Logout and then log in again with the credentials you just created. In the examples, this is the tutorial user.
Creating a configuration definition from the existing cell
On the Advanced Middleware Configuration framework server, the configuration information is organized by environments, which are containers for one or more configuration definitions. A configuration definition typically represents a WebSphere cell. The Advanced Middleware Configuration console contains an editor that you can use to create a configuration definition.
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.
To import the topology of the HitCount server:
- In the Advanced Middleware Configuration console, click Configuration.
- Click the icon for Read existing configuration as
shown in Figure 4.
Figure 4. The configuration definition editor
- Use the values shown in Table 1 to respond to the prompts in the editor. Not all the prompts are included here. The example values are intended to be representative rather than definitive.
Table 1. Example values for the configuration definition editor
|Existing server host name|
| OS username|
|These credentials are used to connect to the host in the previous field.|
|Test connection||Click to verify your connection to the existing server.|
|Profile Root Directory|
|Use soap.client.props file for authentication|
For increased security, you can pass credentials to the wsadmin scripting client through the soap.client.props file. See the documentation for the WebSphere Application Server workload for more information on whether this feature is enabled by default.
|Read configuration topology||Click when you have completed the preceding fields. This process must complete before you generate the new definition.|
After you see a "Passed" message for reading the topology, select the name of either a product template or a user template (if available). The process of reading the existing configuration determines the version number of the middleware that the existing server is running, and only matching templates are displayed. For this initial discovery of the existing topology, use a template with no built-in applications or configuration data. Later you will see how to construct a custom template that uses the data from the existing cell.
- When all fields are complete, click Generate
If you see an error message that includes the sentence "Ensure the integrateToBF script has been run", you might need to log in to the framework server and run the
integrateToBF createAllcommand from the command line.
You might see an error message that says, "Error: Could not load resource. The resource might have been deleted, or you do not have access to view the resource." Make sure the current user is a member of the Build Engineer group.
If you see a result of "Passed", close the Results window by clicking the X in the upper right corner. The Read existing configuration window is displayed again. Click OK to close.
- If you need to customize the configuration definition, click Edit and make changes in the edit pane. You can add clusters or servers or make any other changes to the configuration topology that you might need.
Importing configuration data
You have captured the topology of the system you want to bring into the cloud. Now you need to import the configuration information from the existing cell, including the application you are onboarding.
To import the data from the HitCount server:
- In the Advanced Middleware Configuration console, click Configuration and locate the configuration definition that you just created.
- Expand Plans.
- Expand the RAFW_env_config_import plan.
- The Run plan window is displayed, showing the context variables for
this configuration definition. You can change these variables here,
but you should not need to. Click Run, as shown in
Figure 5. Running the import plan
- A job is created in the automation engine to run the plan.
The job results are displayed in the console and periodically
refreshed until the job completes, as shown in Figure
Figure 6. Import plan passed
You have now created a configuration definition for the server that you want to bring into the cloud. This is sometimes called the "Golden" configuration.
Setting up the Eclipse client
The next steps are creating a template from your configuration definition and generating a VSP from the template. Both these steps require the Advanced Middleware Configuration Eclipse client.
If you have already set up your Eclipse client, skip ahead to Creating a template from a configuration definition.
- In the Advanced Middleware Configuration console, on the Welcome page, click Download the rich client. Select either the Windows or the Linux client.
- Save the archive file, extract it to a directory of your choice, and then launch the Eclipse client by double-clicking the amcui.exe icon.
- In the Eclipse client, right-click the blank space in the Configuration Explorer window and then click Create > Framework Server Connection. The Framework Connection window is displayed.
- In the Framework Connection window, complete the fields shown in Table 2.
Table 2. Example values for the framework server connection
|Label||Enter a free-form label, such as "Framework Server", to identify this connection.|
|Hostname||Enter the name of the framework server you created earlier in this process. One way to obtain this name is to select your framework server from the Virtual Systems Instances page of the Workload Console and expand Virtual machines. Expand the AMC Part. Scroll down to the Network interface 1 field and copy either the host name or the IP address from this field.|
|Username||Enter the name of the user you created earlier in the Workload Console. For example, this article uses "tutorial".|
|Password||Enter the password for the user in the previous field.|
|Remember Password||Leave this field selected if you do not want to reenter your password every time you connect.|
- Click Test Connection to verify the information you just entered. You see a "Server validated" message near the top of the window if the test is successful.
- Click Finish. The label you assigned your framework server now appears in the Configuration Explorer view.
- In the Configuration Explorer view, right-click your framework server
and then click Connect. You can now expand your
framework server and see the configuration definition you created
earlier, as shown in Figure 7.
Figure 7. The Configuration Explorer view
Creating a template from a configuration definition
By using templates, you can standardize the process of creating configuration definitions and VSPs and ensure that they are pre-filled with data, including application EAR or JAR files. Templates can also contain custom questions, which are added to a script package when you generate a VSP from the template. The custom questions correspond to the tokens that replace configuration-specific data. For more information, see Configuration template overview in the PureApplication System Information Center. This topic also explains how to use the promote.properties file to identify configuration-specific values that you want to be tokenized.
- In the Eclipse client, drag your configuration definition from the
Configuration Explorer view to the Configuration Workspace view, as
shown in Figure 8. Be sure to drag the cell name, not the environment
Figure 8. Dragging the configuration definition to the Configuration Workspace view
- Create a
promote.propertiesfile to enable custom tokenization. In the Configuration Workspace view, right-click the configuration (cell) name and click Add New > Promote Properties File.
promote.propertiesfile defines tokens that replace configuration-specific values. The Eclipse client creates a new
promote.propertiesfile at the cell scope (meaning it affects all nodes except those with their own
promote.propertiesfiles that override it). The file is opened for editing.
- List a set of token names and the configuration-specific values they
replace. Do not include at-signs in the token names. Using the example
in Figure 9, when the template is created, any occurrences of
"DEV.db.domain.com" in the configuration data are replaced by
"@dbHostName@". When you deploy the VSP, you are asked to provide the
appropriate value for the new configuration.
Figure 9. Creating the promote.properties file
For more information, see Tokens and tokenization in the PureApplication System Information Center.
- In the Configuration Workspace, right-click the configuration (cell) name and click New > Configuration Template.
- In the Configuration Template window, enter the information shown in Table 3.
Table 3. Example values for the configuration template window
|Configuration Template Name||Template names are typically in uppercase letters and include a product acronym and version. User-created templates typically include a few characters to distinguish them from the system-supplied templates, such as WAS85_HITCOUNT_TEMPLATE.|
|Use Template Meta-Data from Template||Select an existing template as a basis for any additional questions or topology data you need during the configuration edit process, such as WAS85_TEMPLATE. The product version of the template you choose must match the version of WebSphere Application Server that you specify in the VSP. It does not need to match the version of the existing cell.|
- Click OK. A list of the files in the template is displayed in the editor pane.
- Expand any of the objects in the Scope Type column.
Clear the check box for any objects that you want to remove from the
template, as shown in Figure 10. You cannot clear the check box for a
required file. You must make these changes before saving the template.
Figure 10. Removing objects from the template
- Save the template by clicking File > Save or
pressing Ctrl-S. The Save Template window is
displayed, as shown in Figure 11.
Figure 11. The Save Template window
- If you use any
promote.propertiesfiles, default questions are created to solicit new values for those properties in the configuration editor. Click Modify Questions and provide more user-friendly prompts in the Display Name fields, as shown in Figure 12.
Figure 12. The User Defined Questions window
Click OK when finished and then click OK to save the template.
- In the Template Workspace view, right-click the new template name and click Team > Save Changes to Server.
Creating a VSP from a template
The first step is to verify that you have the required script packages available in the IBM PureApplication System catalog. If all three packages are available, the VSP generation is virtually automatic.
Verifying required script packages
In the Workload Console, click Catalog > Script Packages. Make sure you see the packages shown in Figure 13.
Figure 13. Catalog of script packages
If any packages are missing, complete the following steps for each package:
- Click the green plus sign to create a new script package.
- Assign the name of the missing package. The name must exactly match
one of the following:
- AMC Cleanup Script Package
- AMC Import Script Package
- AMC Integration Script Package
- Upload the appropriate archive file for the package from your local
system. The files are available on the Welcome page of the Advanced
Middleware Configuration console. Click Download script
packages and select the file you want. The following
files are available:
- rafwScriptPackage.zip (contains AMC Integration Script Package)
Generating the VSP
- In the Advanced Middleware Configuration Eclipse client, Configuration Explorer view, right-click the name of your framework server and click Refresh to show the latest templates.
- Expand Configuration Templates. Right-click the
template you just created and click Generate VSP, as
shown in Figure 14.
Figure 14. Generating the VSP
The Generate Virtual System Pattern window is displayed.
- Provide the information shown in Table 4.
Table 4. Example values for VSP generation
|Pattern Name|| The name that the VSP will have in the
Workload Console catalog. This example uses
|Cloud Hostname||The host name or IP address of the IBM PureApplication System Workload Console.|
|Cloud Username||The name of the user on the Workload Console who owns the pattern.|
|Cloud Password||The password for the user in the previous field.|
- Click Verify to test the connection to the PureApplication System host. When the connection is verified, click Generate. A VSP is created in PureApplication System and a custom script package is created with the name RAF_template_name_Integration. This script package is a copy of the standard Integration script package, with parameters added for any custom tokens that you created earlier.
Deploying the new VSP
The Integration script package, mentioned earlier, runs when you deploy a new instance of a VSP. The VSP generation process adds some values to the package, but you must provide others at deployment time. In Figure 15, green check marks indicate the parts that are complete. The Virtual system name field is originally not checked, but the check mark is displayed once a name is entered. Note that the Configure virtual parts section requires user input.
Figure 15. Deploying an instance of the HitCount VSP
When you deploy the new VSP, you want to create a new configuration environment on the framework server at the same time. A field is provided for the environment name in the Integration script package.
- In the Workload Console, click Patterns > Virtual
Systems and then click the name of the VSP that the VSP
generator just created (
HitCountVSPin this example).
- Click Deploy.
- Provide a name for the instance you are creating. For the purposes
of this article, it is named
- Click Configure virtual parts > Standalone server. You must fill any required parameters that are blank. You can also change any completed parameters that are unlocked. For example, you might be required to provide passwords for the root user and virtuser on the instance being created.
- Enter a value for the RAFW_ENVIRONMENT parameter. 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
If you used the
promote.propertiesfile to create custom tokens, enter values for them here. Figure 16 shows the dbHostName parameter created earlier.
Figure 16. Setting the environment parameter
- Click OK. The new instance and the new environment are created.
The RAFW_ENVIRONMENT field is concatenated with the cell name to determine the name of the configuration definition that models this new instance. If the configuration definition already exists, the script package updates the topology and host names based on the new instance. If not, a new configuration definition is created.
After creating the new configuration definition, Advanced Middleware Configuration runs the Execute automation plan to push the application and configuration data into the new running instance.
The new HitCountInstance includes the HitCount application because it is part of the template that is applied to each new instance of the HitCountVSP.
The HitCount instance is ready to use. For more information regarding this process, see Integration script package flow later in this article.
Deploying new instances of the application
You can now create as many exact copies of your finished instance (HitCountInstance in this example) as you want. For each instance, complete the following steps:
- From the Virtual Systems display, click the name of your VSP (HitCountVSP in this example).
- Click Deploy.
- In the deployment window, provide the following information:
- A unique name for the new server instance
- A unique environment name (RAFW_ENVIRONMENT) for the configuration definition to be created for this instance
- Values for any custom tokens from the
- Click OK.
Updating the template
You will typically make changes to the instance that is now running in the cloud. These changes might include updating the application, reconfiguring the topology, or installing new middleware. If you want to save these changes to the template, complete the following steps:
- Import the changes from the live configuration to the configuration
definition. In the PureApplication System Workload Console, click
Instances > Virtual Systems and then click the
name of your instance (HitCountInstance in this example). Expand
Virtual Machines. Expand the Deployment Manager
part (or Server part if it is a standalone server) and scroll down to
Script Packages. Locate the AMC Import Script
Package and click Execute now, as shown in Figure 17.
A product administrator User name and
Password are requested, but you can leave these
Figure 17. The Import script package
When the import is complete, a green check mark and the current date and time are displayed next to the script package name.
- In the Advanced Middleware Configuration Eclipse client, Configuration
Explorer view, locate the configuration definition for your instance.
Figure 18. Configuration definition for the instance
Drag the configuration name to the Configuration Workspace view.
- In the Configuration Workspace view, right-click the configuration name, and then click Add New > Update Configuration Template.
- In the Configuration Template window, select the template to update and click OK.
- The template is displayed. Save the template.
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 automation plan as shown in Figure 19.
Figure 19. Clearing steps for scopes with no configuration
- Do not change your passwords.
- The WebSphere Application Server major version that you use to seed the template at creation time must match the WebSphere Application Server major version of the virtual system parts in the VSP.
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.
When you deploy the VSP, the Integration script package completes the following steps. The separate servers in the diagram represent virtual servers, that is, instances of virtual system patterns in PureApplication System.
- The user deploys an instance of the virtual server (see Figure
Figure 20. Process flow step 1
- The Workload Console installs and initializes WebSphere Application
Server (see Figure 21).
Figure 21. Process flow step 2
- The script package passes the minimum information needed to discover
the topology of the new instance and create a configuration definition
for it (see Figure 22).
Figure 22. Process flow step 3
- The framework server then looks up the specified template and uses it
to create or update a configuration definition that contains all of
the application and configuration data from the template. Then the
framework server pushes any applications and configuration information
from the configuration definition to the new instance (see Figure
Figure 23. Process flow step 4
See the Troubleshooting section for more information about the Integration script package flow.
The Integration script package creates the artifacts shown in Figure 24 in the Advanced Middleware Configuration console:
- RAFW_env_config, which creates or recreates a live cell that corresponds to the configuration definition.
- RAFW_env_config_compare, which records differences between a configuration definition and a live cell.
- RAFW_env_config_execute, which makes changes to a running virtual system.
- RAFW_env_config_import, which captures changes from a running virtual system.
Figure 24. Artifacts created by the Integration script package
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:
- Extracts the packaged files in the directory
- Runs the Advanced Middleware Configuration client. It establishes a connection to the framework server.
- Passes information to the framework server so that the framework server can discover the topology of the new instance.
The framework server then completes the following steps:
- Copies any needed scripts into the directory specified by the RAFW_platform_HOME_PATH parameter.
- Discovers the topology of the new instance.
- Creates or updates a configuration definition to represent the new instance, based on the specified custom template.
- Pushes any configuration information or applications in the template to the new instance.
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 (or the standalone 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, similar to the one in Figure 17.
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:
- In the Consoles section of the framework server Virtual System Pattern 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 following errors are common:
- There is an incorrect hostname for the framework server, or incorrect credentials for the framework server user.
- The RAFW_HOME_PATH script package parameter 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.
- A non-unique RAFW_ENVIRONMENT parameter value is specified in the Integration script package, which can result in the incorrect configuration being pushed to the deployed cell.
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:
- 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 automation engine 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
- IBM PureApplication System Information Center
- IBM PureSystems Centre
- IBM PureSystems resources on developerWorks
Dig deeper into Rational software on developerWorks
Get samples, articles, product docs, and community resources to help build, deploy, and manage your cloud apps.
Experiment with new directions in software development.
Software development in the cloud. Register today to create a project.
Evaluate IBM software and solutions, and transform challenges into opportunities.