You can deploy Liberty servers as
members of a collective using the DeployService REST APIs.
Before you begin
Create and
package a
Liberty server to deploy.
- If you do not have an existing server to package, run the create command to
create a new server.
./server create member1
- If you have an existing server to package, ensure the server that you want to package is
stopped.
- Run the package command to create the server
package.
./server package member1
The command creates a server
package named, for example, member1.zip.
Ensure the target host is set up for Remote Execution Agent (RXA). See Setting up RXA for Liberty collective operations.
Also ensure the target host has the cURL utility, an
unzip utility, and Java support for the jar utility in the
environment (path) of a user that has operating system rights to the target deployment location.
This user must be the same user specified for --rpcUser, a Remote Procedure Call
(RPC) user, during registration of the host. You register a host in step 3.
Procedure
- Add a collectiveController statement to the controller
server.xml file. Set the user and
password values to the controller administrative user ID and password. For
example, use the values that are in the <quickStartSecurity userName="admin"
userPassword="adminpwd" /> statement in the controller server.xml
file.
<collectiveController user="admin" password="adminpwd" />
- Review the available deployment rules.
- Invoke a REST API that returns the available deployment rules in JSON structure. Use a tool that can invoke REST APIs to get the available deployment rules.
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": "Location of directory on the controller containing the server package to deploy.",
-"displayName": "Package directory"}],
-"name": "Liberty Server",
-"default": true,
-"runtimeTypes": [
-{
-"displayName": "Liberty"}],
-"packageType": "Server Package"}
- If necessary, create your own deployment rules by adding DeployRules to your
controller configuration. See Deploy Rule (deployRule).
- Make the server package available to the controller.
Complete either of the following actions:
- Register the host on which you 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, you can use the updateHost command to reset
registration information.
Important: Ensure you run the collective registerHost or
updateHost command as the user that you will later use to deploy the member
server. For example, if you 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.
collective registerHost targetHost --host=controllerHost --port=controllerHTTPSPort
--user=controllerAdmin --password=controllerAdminPassword --rpcUser=osUser --rpcUserPassword=osUserPassword --autoAcceptCertificates --hostWritePath=targetDir
- --host, --port, --user, and
--password are required. To find the values for these parameters, look at the
server.xml file of the controller.
- If the remote target host does not support SSH or you 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 you want to install a Liberty server. You can specify more than one
--hostWritePath parameter; for example: --hostWritePath=/dir1
--hostWritePath=/dir2
For more information about the registerHost and updateHost
commands, see Registering host computers with a Liberty collective.
- Deploy the Liberty server.
Use a tool that can invoke REST APIs to 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 that you can use to request status and results.
POST https://controller_host:controller_port/ibm/api/collective/v1/deployment/deploy
{
"rule":"Liberty Server Rule",
"hosts":["target_host_name"],
"variables": [
{ "name":"serverPackage","value":"member.zip" },
{ "name":"targetDir","value":"%2Fhome%2Fszhou%2Fdeploy" },
{ "name":"keystorePassword","value":"password" },
{ "name":"serverPackageDir","value":"%2Fusr%2Ftest%2Fsource" }
]
}
Attention: The targetDir and serverPackageDir
variables are UTF-8 encoded directory paths. The serverPackageDir variable is the
location of the Liberty server package ZIP
file on the collective controller.
Use the return token, which might resemble {"id":3}, to get status and results.
You can get the output in JSON format.
What to do next
Request and review the deployment status and results.
- Get a list of deployment tokens for requested deployment
operations.
GET https://controller_host:controller_port/ibm/api/collective/v1/deployment/deploy
- Get a short status of the deployment operations. Use the token from step 6 for
{token}. Thus, for a {"id":3} return token from
step 6, use 3 for
{token}.
GET https://controller_host:controller_port/ibm/api/collective/v1/deployment/{token}/status
During
deployment, the API returns
IN_PROGRESS:{"status":{"target_host":"IN_PROGRESS"}}
After
deployment, the API returns
FINISHED:{"status":{"target_host":"FINISHED"}}
You
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 6 for
{token}. Thus, for a {"id":3} return token from
step 6, use 3 for
{token}.
GET https://controller_host:controller_port/ibm/api/collective/v1/deployment/{token}/results
After
deployment completes, the results contain information about the operation. The following example
shows results for
FINISHED:{"results":[{"host_name":"target_host","status":"FINISHED","result":0,"stdout":"deployment_stdout", "stderr":"deployment_stderr", "deployedArtifactName":"serverName_from_inputVars", "deployedUserDir":"target_host_directory_for_deployed_server"}]}
Undeploy the
Liberty server. You do not
need to specify a deploy rule. The rule that is used for deployment was stored at deploy time. You
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.
GET https://controller_host:controller_port/ibm/api/collective/v1/deployment/undeploy
To
get status and results, follow steps similar to deployments.