Deploy Liberty servers using deployment REST APIs

Overview

We can deploy Liberty servers as members of a collective using the DeployService REST APIs.

Create and package a Liberty server to deploy.

Before beginning

If we do not have an existing server to package, run the create command to create a new server.
If we have an existing server to package, ensure the server to package is stopped.
Create the server package.
The member1.zip file will include a Liberty runtime, which a "collective join" operation needs, and an expected path in the package for a deploying the Liberty server, like /wlp/usr/servers.

Set up the target host for Remote Execution Agent (RXA).

Also ensure the target host has:

cURL utility
unzip utility
jar utility

Log on to the controller host as the Remote Procedure Call user (--rpcUser) used when we registered the host.

Procedure

Add a collectiveController statement to the controller server.xml file.
For admin id and password we can use values in statement:

Review the available deployment rules.

Use a REST API Client to invoke a REST API that returns the available deployment rules in JSON structure.

GET https://controller_host:controller_port/ibm/api/collective/v1/deployment/rule

The invocation returns the deployment rules in JSON structure:

{ 
  -"id": "Liberty Server Rule",
  -"description": "Deploy rule for Liberty servers.",
  -"type": "Liberty",
  -"deployCommands": "curl 
  -X GET https://${wlp.admin.host}:${wlp.admin.port}/IBMJMXConnectorREST/file/${serverPackageDir}%2F${serverPackage} 
  --user ${wlp.admin.user}:${wlp.admin.password} 
  -k 
  --create
  -dirs 
  -o ${targetDir}/${serverPackage}.tmp 
  --verbose && unzip ${targetDir}/${serverPackage}.tmp 
  -d ${targetDir}/${serverPackage} && ${targetDir}/${serverPackage}/${binDir}/collective join ${serverName} 
  --host=${wlp.admin.host} 
  --port=${wlp.admin.port} 
  --user=${wlp.admin.user} 
  --password=${wlp.admin.password} 
  --keystorePassword=${keystorePassword} 
  --hostName=${wlp.deploy.host} 
  --useHostCredentials 
  --createConfigFile=${targetDir}/${serverPackage}/wlp/usr/servers/${serverName}/configDropins/defaults/additionalConfig.xml 
  --autoAcceptCertificates",
  -"undeployCommands": "${targetDir}/${serverPackage}/${binDir}/server stop ${serverName}; 
  ${targetDir}/${serverPackage}/${binDir}/collective remove ${serverName} 
  --host=${wlp.admin.host} 
  --port=${wlp.admin.port} 
  --user=${wlp.admin.user} 
  --password=${wlp.admin.password} 
  --autoAcceptCertificates 
  --hostName=${wlp.deploy.host}",
  -"startCommands": "${targetDir}/${serverPackage}/${binDir}/server start ${serverName}",
  -"stopCommands": "${targetDir}/${serverPackage}/${binDir}/server stop ${serverName}",
  -"restartCommands": "${targetDir}/${serverPackage}/${binDir}/server stop ${serverName} &
  & ${targetDir}/${serverPackage}/${binDir}/server start ${serverName}",
-"inputVariables": [
-{ -"name": "targetDir",
   -"type": "filePath",
   -"description": "The target directory for the Liberty server package to be installed.",
   -"displayName": "Target Directory"},
-{ -"name": "keystorePassword",
   -"type": "password",
   -"description": "Password for keystores of the deployed server",
   -"displayName": "Keystore Password"},
-{ -"name": "serverPackage",
   -"type": "file",
   -"description": "Name of the Liberty server package to install.",
   -"displayName": "Server Package File"},
-{ -"name": "serverPackageDir",
   -"type": "filePath",
   -"description": "Directory on controlller containing server package to deploy.",
   -"displayName": "Package directory"}],
-"name": "Liberty Server",
-"default": true,
-"runtimeTypes": [
-{ -"displayName": "Liberty"}],
   -"packageType": "Server Package"}

If necessary, create deployment rules.
Make the server package available to the controller.
Complete either of the following actions:
- Put the server package in one of the default readDir directories (or subdirectory of readDir):
  - ${wlp.install.dir}
  - ${wlp.user.dir}
  - ${server.output.dir}
- Add a remoteFileAccess statement to server.xml that points to the location of the server package.
  The first readDir statement provides the location of the server package. This directory is the serverPackageDir input variable specified for the deployService deployment in step 4. The serverPackageDir directory is /usr/test/source/member.zip on the controller host. The next three readDir statements re-enable the default readDir directories; for example:

Register the host on which we want to install a Liberty server with the collective controller.
Registering a host enables the collective controller to access files, commands, and other resources on the host. Use the registerHost command to register the target host. If a host is already registered, we can use the updateHost command to reset registration information.
Important: Ensure we run the collective registerHost or updateHost command as the user that we will later use to deploy the member server. For example, if we run the command as the root user and then later deploy a member as a different user, the deployment fails because DeployService does not have rights to push a file to the /root/wlp directory.
- --host, --port, --user, and --password are required. To find the values for these parameters, look at server.xml of the controller.
- If the remote target host does not support SSH or we do not want to use SSH keys, such as for target hosts on Linux or Windows operating systems, --rpcUser and --rpcUserPassword are required. Set --rpcUser to an operating system login user and set --rpcUserPassword to the password. The user specified by --rpcUser must have operating system rights to the target deployment location.
- --autoAcceptCertificates is required.
- --hostWritePath=directory is required. The directory value for --hostWritePath must be the targetDir specified in the deployment rules, or a parent directory of the targetDir on the host on which we want to install a Liberty server. We can specify more than one --hostWritePath parameter; for example: --hostWritePath=/dir1 --hostWritePath=/dir2
For more information see Register host computers with a Liberty collective.
Deploy the Liberty server.
Use a REST API Client to invoke REST APIs that deploy the Liberty server. The deployment rule contains variables that can specify input values for the invocation, such as the Liberty server to use. The return body contains a token used to request status and results.
The targetDir and serverPackageDir variables are UTF-8 encoded directory paths. The serverPackageDir variable is the location of the Liberty server package (serverPackage) ZIP file on the collective controller. In this case, /usr/test/source/member.zip
Use the return token, which might resemble {"id":3}, to get status and results. We can get the output in JSON format.

What to do next

Request and review the deployment status and results.

Use a REST API Client to get a list of deployment tokens for requested deployment operations.
Get a short status of the deployment operations. Use the token from step 4 for {token}. Thus, for a {"id":3} return token from step 4, use 3 for {token}.
During deployment, the API returns IN_PROGRESS:
After deployment, the API returns FINISHED:
We can also get a final status of ERROR if the deployment has problems. Use the following information to get the complete results. The stdout and stderr information that is returned can help you diagnose the problems.
Get the complete results of a deployment operation.
Use the token from step 4 for {token}. Thus, for a {"id":3} return token from step 4, use 3 for {token}.
After deployment completes, the results contain information about the operation. The following example shows results for FINISHED:

Undeploy the Liberty server. We do not need to specify a deploy rule. The rule used for deployment was stored at deploy time. We can use the rule for undeployment. The server tuple of host name, user directory, and server name is used to undeploy the server. This tuple is shown on server pages in the Explore tool of Admin Center.

Undeploy a Liberty server.

POST https://controller_host:controller_port/ibm/api/collective/v1/deployment/undeploy
{     
   "host": "myHostName",
   "userDir":"myUserDir",     
   "serverName":"myServerName"
}

Get a list of tokens for undeployment operations.
To get status and results, follow steps similar to deployments.