This document can help you create WebSphere Application Server configuration templates and apply them to WebSphere Application Server instances. Read through the following procedures to get an understanding of the mechanics of the process. After you learn the basic concepts, you can follow similar steps with your own WebSphere Application Server configurations. The process involves the following steps:
Before you begin
This example is written for WebSphere Application Server Network Deployment, with a single cluster configured.
Install the WebSphere Application Server – Deploy and WebSphere Application Server – Configure plug-ins for IBM UrbanCode Deploy on the IBM UrbanCode Deploy server.
Back up your WebSphere Application Server configuration data. For more information, see backupConfig command in the WebSphere Application Server Network Deployment help.
P1. Set up WebSphere Application Server as a base template
You create configuration templates by retrieving configuration information from an existing WebSphere Application Server instance. Configure a WebSphere Application Server instance to use as a base template for future instances. You can make changes to configuration files after they are created, but fewer changes are required if the initial WebSphere Application Server environment is already configured to a desired state.
Add a new top-level group to the resource tree. Add the IBM UrbanCode Deploy agent that is located on the WebSphere Application Server Deployment Manager host to the top-level group. Wait 10 to 30 seconds for the automatic discovery to run, and then verify that a WebSphereCell object is displayed as a child of the agent. Click the Edit icon for the WebSphereCell object and verify that the user name, password, and port number match your Deployment Manager credentials. The port number is 8879 for a default installation of WebSphere Application Server. Continue to step P2 after you verify all of the information.
P2. Retrieve WebSphere Application Server configuration data and convert the data to templates
For information on retrieving data and creating templates, see Converting WebSphere Application Server configuration data into templates. Use the supplied WebSphere – Example 1 – Pull & Templatize Configuration Data (WAS ND with Cluster) process.
P3. Import sample application
When you install the plug-in, a sample application named WebSphere Configuration – Example Application is imported. The application contains IBM UrbanCode Deploy components named Cell Config, Cluster Config, and Node Config.
The three components directly map to the three folders that were templatized in step P2. You will map the templatized JSON files into the three components.
P4. Create component versions
The following instructions describe using the versioned file system to create component versions from the templatized JSON configurations. Alternately, you can create component versions from the command line. To create component versions from the command line, see Creating components with the command-line client in the product help. Verify the imported directory structure against Figures 2 – 4 after you create component versions.
To learn more about the versioned file system, see Creating components from a versioned file system in the product help.
After completing this step, the Cell Config, Cluster Config, and Node Config components as displayed in IBM UrbanCode Deploy should look similar to Figures 2 – 4.
Note: The IBM UrbanCode Deploy agent must be installed on the same computer as the template folder. If you encounter problems while importing component versions, see the product help for more information.
Create versioned folders
Navigate to the template folder on the Linux computer. For each parent folder in the base template directory, create a version directory. For example, in the Cell folder, create a directory named 1.0. Move all other directories in the Cell folder into the 1.0 folder. Repeat this for the other two parent directories, Node-1, and Cluster-YourClusterName. After you move the folders, run the tree command and verify that the structure looks similar to Figure 1.
Import versioned folders to IBM UrbanCode Deploy
In IBM UrbanCode Deploy, navigate to the Components page and then select one of the three provided components. For example, select the Cell Config component. Click the Configuration tab, and then select File System (Versioned) in the Source Configuration Type list. Specify the full path to the Cell folder in the Base Path. Click Save. Click the Versions tab. Click Import Versions and verify that the 1.0 directory is detected, with the correct directory structure inside. Repeat this for the other two components, ensuring that you specify the correct base path to the parent folders.
Note: The sample component processes support the ability to combine multiple related JSON files before applying the configuration to the particular WebSphere Application Server scope. For example, if the Cell directory contained Cell.json and JDBCProvider.json files, those files are combined before calling the WebSphere Configuration Apply step for the cell level configuration. This is also true for the Cluster and Node components.
Figure 1. An example directory structure after creating versioned folders
Figure 2. An example version for the Cell Config component
Figure 3. An example version for the Cluster Config component
Figure 4. An example version for the Node Config component
P5. Run a topology discovery
Run a topology discovery to find relevant nodes and to create a basic framework on which to deliver the custom configuration to the WebSphere Application Server instance. You can use the full discovery from steps P1 and P2.
Create a resource group in the resource tree. Add the same agent that you used for the full WebSphere Application Server discovery to the resource group. Allow 10 to 30 seconds or more for the agent to discover the cell. After the cell resource is discovered, click the Edit icon for the cell and verify that your user name and password are correct. After verifying your credentials, click Actions and then select Configure Using WebSphere Topology Discovery. After the configuration process completes, the topology is displayed in the resource tree as shown in Figure 5. Next, verify that the user name, password, and port number are correctly configured by clicking the Edit icon for the Deployment Manager resource. Verify that the port number is set to 8879 or to another port number that you have configured.
Figure 5. Results of topology discovery displayed in the resource tree
P6. Add components to the resource tree
Add the Cell Config, Cluster Config and Node Config components to the resource tree. See Figures 7 – 9 later in this section for a visual reference to the resource tree structure.
Place the Cell Config component under the WebSphereNode resource of the node where the Deployment Manager, as shown in Figure 7. For example, if the Deployment Manager runs on a node named CloudBurstNode_1, add the Cell Config component to the Cell/Nodes/CloudBurstNode1 resource. Place the Cluster Config component under the WebSphereCluster resource. Place the Node Config component under any nodes where you plan to run WebSphere Application Server.
When you add the Cell Config component to the resource tree, you must enter a value for the VIRTUALHOSTALIASES resource property. Specify the virtual host aliases that are used in your WebSphere Application Server instance, in the format Hostname->Port. Separate hostname-port pairs with \n. You can find this information by searching for the default_host JSON object in the Cell/cell/Cell.json file. Enter the value of websphere.virtualhost.aliases for the VIRTUALHOSTALIASES property in IBM UrbanCode Deploy, as shown in Figure 13.
When you add the Cluster Config component to the resource tree, you must enter values for the SERVER_COUNT, NODELIST, and ENDPOINTPORTMAPPINGS resource properties.
The value of the NODELIST property is a comma-separated list of node names in the cluster.
The value of the SERVER_COUNT property specifies how many servers to create in the cluster on each node specified by the NODELIST property. For example, if the NODELIST property is 2, and the SERVER_COUNT property is 3, the cluster will have 6 servers, 3 servers on each of the 2 nodes listed.
For ENDPOINTPORTMAPPINGS, each mapping is a triplet in the following format: endPointName->endPointHost->endPointPort. Each triplet is separated by \n. For convenience, you can specify a “.” as endPointHost value, and the host name of the node will be used. The relevant endpoint port mappings can be found on the WebSphere Application Server Administrative Console. Log in to the console and open a server there. Expand the Ports list for the server. A table of port names and ports that need to be altered is displayed. Use the triplet notation and map these ports to known open values, as shown in Figure 10. The following code shows an example value of the ENDPOINTPORTMAPPINGS property:
Place the Node Config component under all nodes where you plan to apply the templatized JSON, as shown in Figure 9. Do not place the Node Config component under the Deployment Manager node. In this example, the Deployment Manager node is the CloudBurstNode_1 node.
Figure 6. The location of virtual host aliases for the default_host object
Figure 7. Cell Config component under the Deployment Manager resource in the resource tree that was created by topology discovery
Figure 8. Cluster Config component under the cluster resource in the resource tree that was created by topology discovery
Figure 9. Node Config underneath a node resource in the resource tree created by the topology discovery
Figure 10. The location of port names for endpoint port mappings
P7. Add base resources
A base resource can be a resource tree created by the initial configuration discovery process described earlier, or can be a resource tree created by a topology discovery process on the same WebSphere Application Server cell or a similar cell. Typically, if you use the resource tree from a topology discovery, there is less clutter in the user interface, and performance might be improved.
To add a base resource, select the sample application, and then select the TEST environment. Click Add Base Resource and then select the resource tree that you worked with in the previous step. The previous topology discovery is associated with the TEST environment for the application.
P8. Run the application process
To apply the configuration from resource tree in IBM UrbanCode Deploy to the live instance of WebSphere Application Server, run the Deploy application process and select the latest versions of all components, as shown in Figure 11. The application process takes the following actions:
Deploys the JSON files in the component versions to the WebSphere Application Server Deployment Manager host.
Substitutes parameters set in the JSON files and combines the cell, node and cluster JSON files.
Applies the cell, node, and cluster configuration data to the live WebSphere Application Server instance.
After you click Submit, a progress screen is displayed. The process typically completes in a few minutes.
Figure 11. Running the Deploy application process
Take the following steps to ensure that the previous procedures worked correctly.
V1. Verify in IBM UrbanCode Deploy
In IBM UrbanCode Deploy, navigate to the Applications page, and then click on the application. Click the History tab, and then select the last process that ran. If the process ran successfully, the history looks similar to Figure 12, later in this section. If a process is successful, all process steps have a successful status and are displayed in green. If a process is unsuccessful, one or more process steps are displayed in red.
If the process failed, review the procedure steps to ensure that you followed them exactly.
Figure 12. Successful application process
V2. Verify functional servers
Open the WebSphere Application Server Administrative Console. Navigate to Servers, and then click All Servers. Verify that there are the same number of servers for each node that you specified in the SERVER_COUNT property. Select the check boxes for all servers, and then click Start. Verify that all servers start up correctly, as shown in Figure 13. If the servers do not start, some of the server-related configurations may be set up incorrectly. Verify that all properties associated with the Cluster Config and Cell Config components are correct, and then run the Apply process again.
Figure 13. Server selection and Start button in the WebSphere Application Server user interface. If the apply process runs successfully, the status for all servers is displayed as a green arrow, as shown in the screen capture.