Configuring provisionable clusters for Liberty elasticity

You can configure a collective to support Liberty elasticity. With Liberty elasticity, the scaling controller can install Liberty software onto a registered host and create a new server. Also, because support for Liberty elasticity includes support for JVM elasticity, the scaling controller can start or stop Liberty servers based on resource use and optional scaling policies. The number of available servers grows when application demand is high and shrinks when application demand is low.

Before you begin

Determine the target hosts onto which you want to install Liberty software and the Liberty software to install. Minimally, you want the scaling controller to install the following installable and package files on a target host:

A package that provides a stand-alone Liberty server with one application. Step 5c explains how to create the server package.
An installable that provides a Liberty server that contains the wlp directory, but does not contain the usr directory. Step 5a explains how to create the Liberty runtime archive installable.

Each target host needs RXA or SSH and a Java Runtime Environment (JRE) installed that meets the minimum requirements of the Liberty server. See Setting up RXA for Liberty collective operations and Setting the JAVA_HOME variable for Liberty collective members and controllers.

If a target host does not have a JRE installed with its JAVA_HOME variable and System PATH variable providing a path to the JRE, the scaling controller can install the JRE on the target host. Step 5b explains how to create a JRE archive, an installable.

Multimedia Watch: The Configuring an auto-scalable cluster for Liberty elasticity video shows how to configure a provisionable cluster. [Transcript]

Procedure

Configure a collective to support Java virtual machine (JVM) elasticity. Ensure that the collective has at least one dynamic cluster member.

For details on configuring scaling controllers with dynamic cluster members, see Configuring auto-scalable clusters for JVM elasticity.
Ensure that each existing dynamic cluster member belongs to a cluster named with the StackGroupName.PackageName naming convention.
Existing dynamic cluster members and servers that the scaling controller will provision will be members of this cluster. StackGroupName is the name of a shared directory which will hold installables and packages that a scaling controller will provision to target hosts based on scaling policies. PackageName is the name of the server package that the scaling controller will provision to target hosts.

For a cluster named myStackGroup.cluster1, put the following statement into the server.xml file of each existing dynamic cluster member:
```
<clusterMember name="myStackGroup.cluster1"/>
```
You will use the cluster name for steps 5c and 7 of this topic. In step 5c, use cluster1.zip for the server package name. In step 7, create the myStackGroup directory for the installables and packages to be deployed.
Optional: Add scaling policies to the scaling controller. See Defining scaling policies.
Register each target host with a scaling controller.
Registering a host enables the scaling controller to transfer files to that host, as well as access files, commands, and other resources on the host. Use the registerHost command to register a target host. Look at the server.xml file of the scaling controller to find the values for the --host, --port, --user, and --password parameters. To not use an SSH private key file, such as for target hosts on Linux® or Windows operating systems, include an operating system login user and password by setting --rpcUser and --rpcUserPassword parameters. The user specified by --rpcUser must have operating system rights to the target deployment location.
```
wlp/bin/collective registerHost targetHost --host=controllerHost --port=controllerHTTPSPort --user=controllerAdmin --password=controllerAdminPassword --rpcUser=osUser --rpcUserPassword=osUserPassword
```
To transfer files to target hosts, you do not need to include a --hostWritePath parameter in the command; the stack provisioning code sets write paths for you. If a host is already registered, you can use the updateHost command to reset registration information. For more information, see Registering host computers with a Liberty collective.

If the target host is on the same computer as the controller host, you must also run the updateHost command for the controller host.
Create and configure installables and packages that a scaling controller can deploy onto a registered host.

An installable is a binary file the application you want to install on a registered host needs to run, such as a Liberty runtime or JRE. A package is that application packaged into a compressed file.
1. Create a Liberty runtime archive that contains the wlp directory, but does not contain the usr directory.
  The naming convention for this installable is type.name.zip; for example, wlp.855.zip. To create a Liberty runtime archive, you have the following options:
  - Run the Liberty server package command with the --include=wlp option; for example:
```
wlp/bin/server package --include=wlp
```
    To specify a file name and target location, add the --archive=archive_path_name option; for example:
```
wlp/bin/server package --include=wlp --archive=c:\temp\wlp.855.zip
```
    If you do not specify a valid file name or target location with the --archive option, then the command creates the wlp.zip runtime archive in the $WLP_OUTPUT_DIR location, which is the ${wlp.install.dir}/usr/servers directory by default. The target location must exist before running the command. Thus, if the target location is c:\temp, the C:\temp directory must exist and have write permission for the command to write the archive to the C:\temp directory.
  - Run the package command with the --include=all option and then delete the usr directory. The package command resembles:
```
wlp/bin/server package myServer --include=all --archive=myArchive.zip
```
  - Create a compressed (.zip) file that contains the wlp directory, without the usr directory.
  After you create the Liberty runtime archive, ensure that the archive name follows the naming convention, wlp.name.zip.
2. Create or obtain archives for the Java development kit (JDK) and any other required installable.
  The naming convention for an installable is type.name.zip; for example, jre.17.zip. Valid type values for installables are:
  - wlp for a Liberty runtime.
  - jre for a Java runtime environment.
  - other for a different file type. This is the default.
  For example, to create an archive for a JRE, create a compressed (.zip) file that contains the contents of the java directory of your IBM JRE installation. Do not include the java directory, but include all folders and files in the java directory. Follow the jre.name.zip naming convention when naming the archive.
3. To deploy a Liberty server and applications, create a server package ZIP file that contains the Liberty server and applications.
  The naming convention for a server package is package_name.zip; for example, cluster1.zip. Options for creating a server package include:
  - Run the package command:
```
wlp/bin/server package cluster1 --include=usr
```
    The command creates a server package named, for example, C:\wlp\usr\servers\cluster1\cluster1.zip.
  - Run the package command with the --include=all option and then delete the wlp directory. The package command resembles:
```
wlp/bin/server package cluster1 --include=all --archive=cluster1.zip
```
  - Create a compressed (.zip) file that contains the usr directory, without the wlp directory.
  For example, to create a server package named cluster1.zip that consists of a stand-alone Liberty server with one application:
  1. Create a server:
```
wlp/bin/server create cluster1
```
  2. Copy an application to the dropins directory of the cluster1 server.
  3. Package the server:
```
wlp/bin/server package cluster1 --include=usr
```
  The wlp/usr/servers/cluster1/cluster1.zip file is created.
  Important: Ensure any server.env file in the package has environment settings that are valid on the target hosts. If JAVA_HOME is set, it must be set to a location that exists on the target hosts to prevent failed deployments.
  Note: For Windows target hosts, create a server.env file that sets JAVA_HOME to the JRE location on the target hosts. After running the package command, place the server.env in the same directory as the server.xml file in the server package ZIP. Example server.env contents are:
```
JAVA_HOME=C:\wlp.jre\jre.17.zip\jre
```

Set a user name and password for the collective controller or stack manager in the scaling controller server.xml file.

<collectiveController user="adminUser" password="adminPassword" />

<stackManager controllerUser="adminUser" controllerUserPassword="adminPassword" />

Place the installables and packages in the WLP_STACK_GROUPS_DIR location, which by default is $WLP_USER_DIR/shared/stackGroups.

Scaling controllers monitor default installable and package locations in the file system and dynamically react to updates. If you place the installables and packages in the default locations, you do not need to change any of the default attributes.

You can use the default stack group, defaultStackGroup. Or you can create your own subdirectory of stackGroups, such as myStackGroup, and add to it the installables and packages subdirectories.

wlp/usr
      /servers
      /shared
         ...
         /stackGroups
            /defaultStackGroup
               /installables
               /packages
            /myStackGroup
               /installables
               /packages

The scaling controllers deploy the installables and packages onto the registered host and create a new server.

Tip: A new server is created only if the scaling policy is enabled and requires a new server. To force a scaling controller to create a new server, adjust the min value and possibly the max value of the scaling policy for the scaling controller. For example, if your scaling controller does not have a scaling policy and your collective has three scaling members, add to the scaling controller server.xml file a policy that forces the scaling controller to have at least four running members:

<scalingDefinitions>
   <defaultScalingPolicy enabled="true" min="4" max="6"/>
</scalingDefinitions>

The cluster naming convention for Liberty elasticity is StackGroupName.PackageName. When a stack is deployed, <clusterMember name="StackGroupname.PackageName" is automatically set in the server.xml file of the deployed server. The corresponding <scalingPolicy> element includes a <bind clusters="StackGroupName.Packagename"/> statement.

Table 1. Default installable and package locations. Liberty environment variables set the default installation directories. To override the default locations, see Customizing the Liberty environment.
File	Default installation directory
Installable type wlp	/wlp
Installable type jre	/wlp/jre
Installable type other	/wlp/other
Package	/wlp/usr

Examine the configuration attributes for stack groups and installables and change the configurations of your stack groups and installables as needed to define when and where to run Liberty provisioning. You might need to override the default configurations.
Override default configurations by setting new values in the stackGroup and installable elements of the scaling controller server.xml file. See Scaling Controller for information about the stackGroup and installable elements.

Tips for overriding default values for some elements follow:
- The installable element defines an installable for a stack group. The installable element can be a child element of the stackGroup element or a sibling referenced by an installableRef child element of the stackGroup element.
  The following examples show how you can change the settings in the scaling controller server.xml file to override the default value for the installable attribute of a stack group:
```
<stackGroup name="myStackGroup">
   <installable name="wlp.v8555.zip" sourceDir="c:\myStackGroup\installables"/>
</stackGroup>
```
  or
```
<stackGroup name="myStackGroup" installDir="/myInstallDir" installableRef="myInstallable1, myInstallable2"/>
<installable name="wlp.v8555.zip" id="myInstallable1" sourceDir="c:\myStackGroup\installablesOne" />
<installable name="jre.v1.6.zip" id="myInstallable2" sourceDir="c:\myStackGroup\installablesTwo"/>
```
- The deployVariable child element specifies a substitution variable which gets injected into the deployed stack. You can specify that the substitution variable automatically increment each time the stack is deployed. For example, use a deployVariable attribute to specify an initial port number value and increment the value each deployment. The purpose of deployVariable in this situation is to avoid port conflicts on the target host. The deployVariable element uses arithmetic in the server.xml file of the deployed server to derive the runtime port number.
  For example, to define a starting port value and amount to increment:
  1. Set httpPort="${http.port}" in the httpEndpoint element of the packaged server server.xml file:
```
<httpEndpoint ... httpPort="${http.port}" />
```
  2. Add a deployVariable definition that sets the starting port and increment values to the scaling controller server.xml file:
```
<stackGroup name="DefaultStackGroup" installDir="">
  <deployVariable name="http.port" value="9080" increment="1"/>
</stackGroup>
```
  Then, each successive time the stack is deployed to the host, the httpPort value increments by 1. Thus, the first time the stack is deployed to host1, the HTTP endpoint element is:
```
<httpEndpoint ... httpPort="9080" />
```
  and the second time the stack is deployed to host1, the element is:
```
<httpEndpoint ... httpPort="9081" />
```
  As to the deployVariable attribute, the default value for value is null. The default value for increment is 0 (zero).
  
  If deployVariable is specified in the scaling controller server.xml file, the runtime port number of a deployed server is the initial port value String increased by the increment integer.
- If the scaling controller server.xml defines the stack group as follows, do not define httpPort again in the bootstrap.properties file for the server directory with which you create a server package. If you do, the httpPort value defined in bootstrap.properties is used, not the one generated by the deployVariable configuration element.
```
<stackGroup name="DefaultStackGroup" installDir="">
  <deployVariable name="http.port" value="9080" increment="1"/>
</stackGroup>
```
Optional: Change the interval at which the scaling controller checks the file system for stack group additions, updates, and deletions.
The scaling controller scans the contents of the stackGroups directory and its subdirectories for changes. Content changes can cause the controller to provision clusters that previously did not have packages available. Updating packages does not cause the controller to provision existing clusters again.

By default, the controller scans the WLP_STACK_GROUPS_DIR location every 5000 milliseconds (five seconds). To change the scanning interval or disable scanning, set new values for the stack manager attributes scanningInterval and scanningEnable in the scaling controller server.xml file. For example, to set the scanning interval to six seconds and enable scanning, add a statement resembling the following to the scaling controller server.xml file:
```
<stackManager groupsDir="${wlp.install.dir}/usr/shared/stackGroups/"
              controllerUser="adminUser" controllerUserPassword="adminPassword"
              scanningInterval="6000" scanningEnable="true">
</stackManager>
```
To disable scanning, set scanningEnable to false.
Optional: Instruct the scaling controller to scan the file system for new stack group additions, updates, and deletions.

Run a StackManager MBean operation to force the scaling controller to check the WLP_STACK_GROUPS_DIR location for stack group additions, updates, and deletions. Even if the scaling controller server.xml file has scanningEnable="false", you can run a StackManager MBean operation to force a scanning for additions, updates, and deletions.

See List of provided MBeans for information about the StackManager MBean.
Optional: Start IHS to enable routing to servers.

For IBM HTTP Server (IHS) to discover and route to web applications on dynamically provisioned clusters, enable dynamic routing on the host where the scaling controller will reside. IHS will retrieve the routing information for the provisioned servers from the dynamic routing service. If server status is enabled, you can view the routing information.

If you do not have IHS installed, see Setting up dynamic routing for Liberty collectives. Also, the following video demonstrates how to install support for dynamic routing using IBM Installation Manager:

Watch: The Enabling IHS for Liberty Dynamic Routing video shows how to install IHS, install Web Server Plug-in for WebSphere Application Server, and apply the interim fix for Dynamic Routing. [Transcript]