Steps Reference 7.6.x
Introduction
This document describes the predefined, general-purpose steps that are available for use with XL Deploy rules.
Plugins such as the IBM WebSphere Application Server plugin can also provide predefined steps. For information about these steps, refer to the plugin documentation.
Step Reference
create-ci
Description
The create-ci
step creates a configuration item (CI) in the XL Deploy Repository.
Note: This step cannot run on a satellite.
Examples
This is an example of a create-ci
step in an XML rule. It creates a CI under Infrastructure/EC2
. The CI name is determined by the name of the deployed application.
<create-ci>
<order>63</order>
<description>Create an SSH host</description>
<ci>
<overthere.SshHost>
<id expression="true">"Infrastructure/EC2/" + deployedApplication.name</id>
<os>UNIX</os>
<connectionType>SUDO</connectionType>
<address>deployed.deployable.ip</address>
<username>ubuntu</username>
<privateKeyFile>/tmp/key.pem</privateKeyFile>
<sudoUsername>root</sudoUsername>
</overthere.SshHost>
</ci>
</create-ci>
Step Parameters
Parameter | Type | Description | Required | Calculated |
---|---|---|---|---|
ci | ConfigurationItem | Configuration item to create | Yes | No |
description | String | Description of this step, as it should appear in generated deployment plans | Yes | Yes |
order | Integer | Execution order of the step | Yes | Yes |
delete
Description
The delete
step deletes a file or directory on a remote host. When you specify a directory name, the full directory and all of its content is removed.
Examples
This is an example of the delete
step created with an XML rule. It deletes a file named C:\tmp\somefile.txt
from the host where the current deployed is located.
<delete>
<target-path>C:\tmp\somefile.txt</target-path>
</delete>
This example deletes the C:\tmp\testdir
and all of its content:
<delete>
<target-path>C:\tmp\testdir</target-path>
</delete>
This is an example of a fully-specified step created with an XML rule. It combines the target file name and containing folder using a file separator that depends on the operating system of the target machine; that is, when deploying to a Windows environment, \
will be used, while on Unix and z/OS, /
will be used.
<delete>
<description expression="true">"Remove the artifact " + deployed.file.name</description>
<order>40</order>
<target-host expression="true">deployed.container.host</target-host>
<target-path expression="true">deployed.container.home + deployed.container.host.os.fileSeparator + deployed.file.name</target-path>
</delete>
Step Parameters
Parameter | Type | Description | Required | Calculated |
---|---|---|---|---|
description | String | Description of this step, as it should appear in generated deployment plans | Yes | Yes |
order | Integer | Execution order of the step | Yes | Yes |
target-host | Host | A target host where the step is applied | Yes | Yes |
target-path | String | Path of the file or folder to be deleted | Yes | No |
delete-ci
Description
The delete-ci
step deletes a configuration item (CI). You specify the ID of the CI, and it is deleted from the XL Deploy Repository when the step is executed.
Note: This step cannot run on a satellite.
Examples
This is an example of a delete-ci
step in an XML rule. It deletes a CI under Infrastructure/Unix
. The CI name is determined by the public IP address of the deployed.
<delete-ci>
<id expression="true">"Infrastructure/Unix/" + deployed.publicIP</id>
</delete-ci>
Step Parameters
Parameter | Type | Description | Required | Calculated |
---|---|---|---|---|
description | String | Description of this step, as it should appear in generated deployment plans | Yes | Yes |
id | String | Configuration item to create | Yes | No |
order | Integer | Execution order of the step | Yes | Yes |
jython
Description
The jython
step executes a Python script locally on the XL Deploy server. The execution script receives a reference to the ExecutionContext
in the context
parameter. This object can be used to share data with other steps and log events.
Note that the script's context
is different from the planning execution context. Be sure to understand the difference between the planning script and the jython
step's <script-path>
script, and the difference between the planning context and the execution context.
Note: This step does not have access to the command-line interface script API.
Note: This step cannot run on a satellite.
Examples
There is a script called script/greet_user.py
in the ext/
directory with the following content:
context.logOutput("Hello " + name)
This script will print some text in the step log.
This is an example of a jython
step created with an XML rule:
<jython>
<order>60</order>
<description>Run the 'greet_user.py' script</description>
<script-path>script/greet_user.py</script-path>
<jython-context>
<user>XebiaLabs</user>
</jython-context>
</jython>
The following is an example of a jython
step created with a script rule. Note how in this example, context
refers to the planning context - the one which allows you to add steps to the plan. This is also where you have access to e.g. the deployedApplication
, the logger
, the services, etc. These are not by default available during execution; but if you need them, you can add them here by letting the planning script include them in the jython_context
(e.g. by saying jython_context = {"app": deployedApplication}
or <jython-context><app expression="true">deployedApplication</app></jython-context>
).
context.addStep(steps.jython(
description = "Run the 'greet_user.py' script",
order = 60,
script_path = "script/greet_user.py",
jython_context = {"user": "XebiaLabs"}
))
This is an example of how to return the code of a step from a jython
step:
private def executeScript(executionContext: ExecutionContext): StepExitCode = {
import scala.collection.convert.ImplicitConversions._
implicit val scriptContext = createJythonContext(executionContext, Bindings.xlDeployApiServices ++ (jythonContext + ("context" -> executionContext)).toMap)
val scriptResult: AnyRef = jython.executeScript(byResource(scriptPath), resultProcessor = extractJythonResult)
scriptResult match {
case "PAUSE" => StepExitCode.PAUSE
case "RETRY" => StepExitCode.RETRY
case x: Integer if x > 0 =>
executionContext.logError(s"Python script exited with exit code '$x'")
StepExitCode.FAIL
case x: StepExitCode => x
case _ => StepExitCode.SUCCESS
}
}
Step Parameters
Parameter | Type | Description | Required | Calculated |
---|---|---|---|---|
description | String | Description of this step, as it should appear in generated deployment plans | Yes | Yes |
jython-context | Map | Dictionary with keys as variable name and values as variable that are passed to the Python script | No | Yes |
order | Integer | Execution order of the step | Yes | Yes |
script | String | Path to the Python script to execute (relative to XL Deploy's classpath) | No | No |
script-path | String | DEPRECATED: Use 'script' instead. Path to the Python script to execute (relative to XL Deploy's classpath) | No | No |
manual
Description
The manual
step allows you to incorporate a manual process as part of a deployment. The step can reference a text file that contains instructions for the manual execution. The content of the text file will appear in the logging output when the step is executed. You can use FreeMarker for the template.
When the step is executed, the deployment is put into a PAUSE
state. To resume the deployment, the user must carry out the instructions and click Continue in the XL Deploy interface. Alternatively, the "continue" action can be triggered by the command-line interface or the REST API.
XL Deploy can automatically send the instructions in the step to one or more email addresses, which you specify in the mail-to
parameter. This feature requires that there is either:
- An SMTP server associated with the mail-server that you are deploying to, or
- A default SMTP server defined in the XL Deploy repository (which XL Deploy will then use)
Note: This step cannot run on a satellite.
Examples
This is an example of a manual
step created with an XML rule:
<manual>
<description>Send mails</description>
<order>50</order>
<message-template>templates/email.txt.ftl</message-template>
<mail-server expression="true">deployedApplication.environment.smtpServer</mail-server>
<mail-to>
<value>jdoe@operations.example.com</value>
<value>manager@operations.example.com</value>
</mail-to>
<mail-from>noreply@deployment.example.com</mail-from>
<subject>Deploying...</subject>
<freemarker-context>
<buttonColour>green</buttonColour>
</freemarker-context>
</manual>
Same example of manual
of step but with calculated parameters omitted.
<manual>
<description>Send mails</description>
<order>50</order>
<message-template>templates/email.txt.ftl</message-template>
<mail-to>
<value>jdoe@operations.example.com</value>
<value>manager@operations.example.com</value>
</mail-to>
<mail-from>noreply@deployment.example.com</mail-from>
<freemarker-context>
<buttonColour>green</buttonColour>
</freemarker-context>
</manual>
This is an example of a manual
step created with a script rule:
context.addStep(steps.manual(
description = "Send mails",
order = 50,
message_template = "templates/email.txt.ftl",
mail_server = deployedApplication.environment.smtpServer,
mail_to = ["jdoe@operations.example.com","manager@operations.example.com"],
mail_from = "noreply@deployment.example.com",
subject = "Deploying...",
freemarker_context = {"buttonColour": "green"}
))
Both examples refer to a template, <XL_DEPLOY_HOME>/ext/templates/email.txt.ftl
, which contains:
Hi!
We're deploying ${deployed.name}.
Please press the $buttonColour button so we can proceed!
Don't forget to push the Continue button in XL Deploy afterward to resume the deployment :-)
Calculated Step Parameters
Mail Server
mail-server
is set to the one of the following:
environment
property of typemail.SmtpServer
and namesmtpServer
.mail.SmtpServer
that has a namedefaultSmtpServer
in the repository.- If nothing of above is available, the parameter must be specified manually.
Mail From
mail-from
is set to the default sender address specified in the mail server configuration.
Step Parameters
Parameter | Type | Description | Required | Calculated |
---|---|---|---|---|
description | String | Description of this step, as it should appear in generated deployment plans | Yes | No |
freemarker-context | Map | Dictionary that contains all values available in the template | No | Yes |
mail-from | String | The email's sender ('From:') email address | No | Yes |
mail-server | SmtpServer | Mail server that is used to send emails | No | Yes |
mail-to | List | The list of email receivers to send instructions to | No | No |
message-template | String | The path to the message template to display to the user and/or send out | No | No |
order | Integer | The execution order of the step | Yes | No |
subject | String | The email subject line | No | Yes |
noop
Description
The <noop>
step is a step that does not perform any actions; a kind of 'dummy' step. One can use it as a marker to indicate that a plan defined by means of rules is correct.
Note: This step cannot run on a satellite.
Example
<noop>
<description>This is a dummy step that performs no actions</description>
<order>60</order>
</noop>
Step Parameters
Parameter | Type | Description | Required | Calculated |
---|---|---|---|---|
description | String | Description of this step, as it should appear in generated deployment plans | Yes | No |
order | Integer | Execution order of the step | Yes | No |
os-script
Description
The os-script
step executes a script on a remote host. The required script
parameter refers to the script in classpath or the ext/
directory.
The step has the following features:
- Operating system independence: The step will select the script based on the host of the operating system (OS) of the host where the script will be executed, so you do not need to include the script extension in the
script
parameter.- In the case of Unix, XL Deploy searches for a script with an
.sh
extension. - In the case of Microsoft Windows, it searches for a
.bat
or.cmd
extension.
- In the case of Unix, XL Deploy searches for a script with an
- FreeMarker template support: If the script has an
.ftl
extension, XL Deploy processes it with FreeMarker before uploading it and removes the.ftl
extension from the uploaded file. The input that you define in thefreemarker-context
parameter is used to resolve the FreeMarker template. - Classpath resources: In
classpath-resources
, you can specify additional resources that are located in the classpath or theext/
directory. XL Deploy uploads these resources with the script. If a resource has an.ftl
extension, XL Deploy processes it with FreeMarker before uploading it and removes.ftl
from the uploaded file. - Attach artifacts to your step: You can attach an artifact (which is a deployed that implements udm.Artifact) to the script. XL Deploy will upload the artifact to the working directory on the target host.
Attachment is done through the FreeMarker context. Any artifact in the FreeMarker context will be uploaded (the
deployed
itself is added to the FreeMarker context by default). The artifact can only be resolved after it is uploaded. For each artifact in the FreeMarker context,artifact.file
resolves to anOverthereFile
that points to the final destination of the uploaded artifact.
Examples
The following example shows how to use os-script
to deploy a deployed of type udm.Artifact
to a remote host. This example focuses on defining the step and omits other required preconditions such as packaging, deployment plan, and so on.
This example deploys a WAR file to a container and copies company-logo.jpg
and index.html
to the www
folder of an HTTP server.
Assume that the following files are created in the ext/
directory.
os-script-example
├── images
│ └── company-logo.jpg
├── html
│ └── index.html.ftl
└── scripts
├── deploy.bat.ftl
└── deploy.sh.ftl
The WAR file (sample-artifact.war
) is provided in a configuration item (CI) that was created in the XL Deploy repository.
index.html
is a FreeMarker template with the following content:
<!DOCTYPE html>
<html>
<head lang="en">
<meta charset="UTF-8">
<title>Welcome to ${deployedApplicationName}</title>
</head>
<body>
<img src="images/company-logo.jpg">
</body>
</html>
The FreeMarker expression ${deployedApplicationName}
is a way of accessing the name of the deployed application; it must be provided in the step definition.
deploy.sh.ftl
is a FreeMarker template with the following content:
cp ${deployed.file.path} /opt/container/wars/
cp os-script-example/images/company-logo.jpg /var/www/company-site/image/
cp os-script-example/html/index.html /var/www/company-site/
${deployed.file.path}
will resolve to the final destination of the uploaded artifact.
deploy.bat.ftl
is a script that executes same commands as deploy.sh.ftl
, but on a Windows host.
The step definition is:
<os-script>
<description>Deploying War file to servlet container and static content to an HTTP server</description>
<order>70</order>
<target-host expression="true">deployed.container.host</target-host>
<script>os-script-example/scripts/deploy</script>
<shell>/bin/sh</shell>
<freemarker-context>
<deployedApplicationName expression="true">deployedApplication.name</deployedApplicationName>
</freemarker-context>
<classpath-resources>
<value>os-script-example/images/company-logo.jpg</value>
<value>os-script-example/html/index.html</value>
</classpath-resources>
</os-script>
The os-script
parameters are defined as follows:
target-host
is a Jython expression that points to a host (deployed.container.host
) where the script is executed.script
points to a script that is executed on the target host. Note that it does not specify the extensionbat.ftl
orsh.ftl
, because theos-script
step chooses the correct file, based on the operating system of the target host.shell
specifies the Unix shell needed to execute the shell script (.sh
file). This is an optional property with the default value/bin/bash
. Note that it is only valid for Unix/Linux operating systems.freemarker-context
specifies inputs for theindex.html.ftl
,deploy.bat.ftl
, anddeploy.sh.ftl
FreeMarker templates. Note that there is no definition of thedeployed
FreeMarker input that is used indeploy.sh.ftl
; XL Deploy will automatically calculate it.classpath-resources
specifies dependencies of the script. These dependencies are uploaded to the target host.
An os-script
step defined in this way does following:
- Processes all FreeMarker templates with the help of
freemarker-context
. - Creates a temporary working directory on a target host.
- Uploads all
classpath-resources
to the working directory, preserving the original folder structure. - Uploads all
udm.Artifact
s available in thefreemarker-context
to the working directory. The resulting file names are available in the FreeMarker template as${artifactName.file.path}
(in our example, the artifact has namedeployed
, thus the expression${deployed.file.path}
must be used) - Executes the script in the working directory.
Files are created in the working directory on the target host as follows:
os-script-example
├── images
│ └── company-logo.jpg
├── html
│ └── index.html
├── scripts
│ └── deploy.sh
└── sample-artifact.war
Note that all files generated with FreeMarker templates lose the ftl
extension.
The content of deploy.sh
is:
cp sample-artifact.war /opt/container/wars/
cp os-script-example/images/company-logo.jpg /var/www/company-site/image/
cp os-script-example/html/index.html /var/www/company-site/
Step Parameters
Parameter | Type | Description | Required | Calculated |
---|---|---|---|---|
classpath-resources | List | Resources that are attached to the script and uploaded to the target host | No | No |
description | String | Description of this step, as it should appear in generated deployment plans | Yes | Yes |
freemarker-context | Map | Dictionary that contains all values available in the template | No | Yes |
order | Integer | Execution order of the step | Yes | Yes |
script | String | Script base name that will be executed on the target host | Yes | No |
shell | String | shell to be used to execute script on the target host | No | No |
target-host | Host | A target host where the step is applied | Yes | Yes |
upload-artifacts | boolean | If true, every artifact presented in the freemarker context will be uploaded to the working directory of the script | No | No |
powershell
Description
The powershell
step executes a PowerShell script on the remote (Windows) host.
Examples
The script Hello.ps1
in the ext/
directory contains this script:
Write-Host "Hello" $who
This is an example of a powershell
step created with an XML rule:
<powershell>
<order>60</order>
<description>Run the 'Hello.ps1' test script</description>
<script>Hello.ps1</script>
<target-host expression="true">deployed.container</target-host>
<powershell-context>
<who>World</who>
</powershell-context>
</powershell>
The order
, description
and target-host
, if not specified, are calculated by XL Deploy.
<powershell>
<script>Hello.ps1</script>
<powershell-context>
<who>World</who>
</powershell-context>
</powershell>
This is an example of a powershell
step created with a script rule:
context.addStep(steps.powershell(
description = "Greeting the world",
order = 80,
script = "Hello.ps1",
powershell_context = {"who": "World"},
target_host = deployed.container
))
The syntax used for powershell_vars
is also available directly in the XML variant above. That is, you can write:
<powershell-context expression="true">{"who":"XebiaLabs"}</powershell-context>
Calculated Step Parameters
The target-host
parameter of a step is calculated as follows:
- If the scope is
deployed
:deployed.container
is of typeoverthere.HostContainer
, thetarget-host
is set todeployed.container
- In other cases,
target-host
cannot be calculated automatically and must be specified manually.
Step Parameters
Parameter | Type | Description | Required | Calculated |
---|---|---|---|---|
description | String | Description of this step, as it should appear in generated deployment plans | Yes | Yes |
order | Integer | Execution order of the step | Yes | Yes |
powershell-context | Map | The variables to pass to the Powershell step | No | Yes |
script | String | Path to the Powershell script to execute (relative to XL Deploy's classpath) | Yes | No |
target-host | HostContainer | The target host to run the script on | Yes | Yes |
upload-artifacts | Boolean | If true, the artifacts from the powershell context will be uploaded to the target host and available to the script as $bindingName.file. Defaults to true. | Yes | No |
template
Description
The template
step generates a file based on a FreeMarker template and uploads the file to a remote host.
Examples
This is an example of the template
step.
These examples resolve a template from the file datasource.ftl
and copies the resulting file to a directory on the target host. The file contains:
<datasource>
<name>${deployed.datasourceName}</name>
<property>${prop}</property>
</datasource>
${prop}
is provided to the template with freemarker-context
. Also, deployed
is added to the freemarker-context
. Refer to Define rule behavior for more information.
This is an example of a template
step created with an XML rule:
<template>
<target-path>/somewhere/there/datasource.xml</target-path>
<template-path>templates/datasource.ftl</template-path>
<freemarker-context>
<prop>myProp</prop>
</freemarker-context>
</template>
This is an example of a template
step created with a script rule:
context.addStep(steps.template(
target_path = "/somewhere/there/datasource.xml",
template_path = "templates/datasource.ftl",
freemarker_context = {"prop": "myProp"})
)
Step Parameters
Parameter | Type | Description | Required | Calculated |
---|---|---|---|---|
create-target-path | boolean | Whether to create the target folder structure if not present. Defaults to true | No | No |
description | String | Description of this step, as it should appear in generated deployment plans | Yes | Yes |
freemarker-context | Map | Dictionary that contains all values available in the template | No | Yes |
order | Integer | Execution order of the step | Yes | Yes |
target-host | Host | A target host where the step is applied | Yes | Yes |
target-path | String | Full path on the target host where the artifact is copied | Yes | No |
template-path | String | Path of the template relative to the ext/ directory | Yes | No |
upload
Description
The upload
step copies a udm.Artifact to an overthere.Host.
Examples
This is an example of a upload
step created with an XML rule:
<upload>
<artifact expression="true">deployed</artifact>
<target-host expression="true">deployed.container.host</target-host>
<target-path>/tmp/somewhere/there/file</target-path>
<create-target-path>true</create-target-path>
<order>50</order>
<description>Rule based copy artifact step</description>
</upload>
This is an example of a upload
step created with a script rule:
context.addStep(steps.upload(
artifact = deployed,
target_host = deployed.container.host,
target_path = "/tmp/somewhere/there/file",
create_target_path = True,
order = 50,
description = "Rule based copy artifact step"))
This is an example of a upload
step with parameters calculated by XL Deploy:
<upload>
<target-path>/tmp/somewhere/there/file</target-path>
</upload>
Step Parameters
Parameter | Type | Description | Required | Calculated |
---|---|---|---|---|
artifact | Artifact | Artifact that is uploaded to the target host | Yes | Yes |
create-target-path | boolean | Whether to create the target folder structure if not present. Defaults to true | No | No |
description | String | Description of this step, as it should appear in generated deployment plans | Yes | Yes |
order | Integer | Execution order of the step | Yes | Yes |
target-host | Host | A target host where the step is applied | Yes | Yes |
target-path | String | Full path on the target host where the artifact is copied | Yes | No |
wait
Description
The wait
step freezes the deployment plan execution for a specified number of seconds.
The description
parameter is optional and defaults to "Waiting for xx seconds".
Note: This step cannot run on a satellite.
Examples
This is an example of a wait
step created with an XML rule:
<wait>
<order>60</order>
<description>Let us have a 10 seconds pause</description>
<seconds>10</seconds>
</wait>
This is an example of a wait
step created with a script rule:
context.addStep(steps.wait(
description = "Delay the rest of the execution plan for 10 seconds",
order = 80,
seconds = 10
))
Step Parameters
Parameter | Type | Description | Required | Calculated |
---|---|---|---|---|
description | String | Description of this step, as it should appear in generated deployment plans | Yes | Yes |
order | Integer | Execution order of the step | Yes | No |
seconds | Integer | Seconds that this step pause plan execution | Yes | No |