job-v20 - The 'job' XML file declares job entries for Rundeck.
This is a demonstration document using all possible elements in the current Rundeck "jobs" XML.
This file can be batch loaded via [rd-jobs] load command:
rd-jobs load -p project --file /path/to/jobs.xml
Rundeck job definitions can be dumped and saved to a file via rd-jobs list command:
rd-jobs list -p project --file /tmp/jobs.xml
The root (aka "top-level") element of the jobs XML file.
Nested elements
Example
<joblist>
<job>
...
</job>
<job>
...
</job>
</joblist>
The job element is a sub-element of joblist and defines a job executable in Rundeck.
The following elements are used to describe the job. Only one of each element is allowed.
Nested elements
unique UUID to identify the job
the job name
the job description
group name
If the job can be executed multiple times simultaneously
command context
dispatch options
workflow sequence
notifications of execution success/failure, via email or webhook
node filtering expressions
the logging level
Job command modes
Jobs execute a sequence of commands. Commands come in several styles:
Examples
Execute the Unix 'who' command
1 | |
Execute a Bash script
1 | |
Execute a sequence of other commands, scripts and jobs:
1 | |
The UUID is a sub-element of job. This string can be set manually (if you are writing the job definition from scratch), or will be assigned at job creation time by the Rundeck server using a random UUID. This string should be as unique as possible if you set it manually.
This identifier is used to uniquely identify jobs when ported between Rundeck instances.
The job name is a sub-element of job. The combination of 'name' and group and project must be unique if the uuid identifier is not included.
The job description is a sub-element of job and allows a short description of the job.
The group is a sub-element of job and defines the job's group identifier. This is a "/" (slash) separated string that mimics a directory structure.
Example
<job>
<name>who</name>
<description>who is logged in?</description>
<group>/sysadm/users</group>
</job>
Boolean value: 'true/false'. If 'true', then the job can be run multiple times at once. Otherwise, the Job can only have a single execution at a time.
<job>
<name>who</name>
<description>who is logged in?</description>
<group>/sysadm/users</group>
<multipleExecutions>true</multipleExecutions>
</job>
schedule is a sub-element of job and specifies periodic job execution using the stated schedule. The schedule can be specified using embedded elements as shown below, or using a single crontab attribute to set a full crontab expression.
Nested elements
Attributes
Example
Run the job every morning at 6AM, 7AM and 8AM.
<schedule>
<time hour="06,07,08" minute="00"/>
<weekday day="*"/>
<month month="*"/>
</schedule>
Run the job every morning at 6:00:02AM, 7:00:02AM and 8:00:02AM only in the year 2010:
<schedule>
<time hour="06,07,08" minute="00" seconds="02"/>
<weekday day="*"/>
<month month="*"/>
<year year="2010"/>
</schedule>
Run the job every morning at 6:00:02AM, 7:00:02AM and 8:00:02AM only in the year 2010, using a single crontab attribute to express it:
<schedule crontab="02 00 06,07,08 ? * * 2010"/>
For more information, see http://www.quartz-scheduler.org/docs/tutorials/crontrigger.html or http://www.stonebranch.com
Attribute of the schedule, sets the schedule with a full crontab string. For more information, see http://www.quartz-scheduler.org/docs/tutorials/crontrigger.html.
If specified, then the embedded schedule elements are not used.
The schedule weekday to run the job
Attributes
* - all ; 1-5 days "sun-sat" ; 1,2,3-5 - days "sun,mon,tue-thu", etcThe job context.
Nested elements
The context project name. Optional. If a project is not specified at import time, this value will be used.
The context options for user input.
Nested elements
Example
<options>
<option name="detail" value="true"/>
</options>
Defines one option within the options.
Attributes
the option name
the default value
comma separated list of values
URL to a list of JSON values
Boolean specifying that must pick from one of values
Regex pattern of acceptable value
Description of the option
Boolean specifying that the option is required
"true/false" - whether the option supports multiple input values
A string used to conjoin multiple input values. (Required if multivalued is "true")
"true/false" - whether the option is a secure input option. Not compatible with "multivalued"
Example
Define defaults for the "port" option, requiring regex match.
<option name="port" value="80" values="80,8080,8888" regex="\d+"/>
Define defaults for the "port" option, enforcing the values list.
<option name="port" value="80" values="80,8080,8888" enforcedvalues="true" />
Define defaults for the "ports" option, allowing multiple values separated by ",".
<option name="port" value="80" values="80,8080,8888" enforcedvalues="true"
multivalued="true" delimiter="," />
The data returned from the valuesUrl can be formatted as a list of values:
["x value","y value"]
or as Name-value list:
1 | |
The job dispatch options. See the [Dispatcher options] for general information.
Nested elements
dispatch up to threadcount
keep going flag
Name of the Node attribute to use for ordering the sequence of nodes (default is "nodename")
Order direction for node ranking. Either "ascending" or "descending" (default "ascending")
Example
<dispatch>
<threadcount>1</threadcount>
<keepgoing>false</keepgoing>
<rankAttribute>nodename</rankAttribute>
<rankOrder>descending</rankOrder>
</dispatch>
Defines the number of threads to execute within dispatch. Must be a positive integer.
Boolean describing if the dispatch should continue of an error occurs (true/false). If true, continue if an error occurs.
This is the name of a Node attribute that determines the order in which the Nodes are traversed. The default value of "nodename" will rank the nodes based on their names.
This can be any attribute of a Node, even attributes that do not exist on some nodes. For example you can set it to "rank", then any Nodes with a "rank" attribute will be ordered before any other nodes, and they will be used in the order of the rank attribute value.
The values in the rank attribute are compared first numerically if they are valid integers, but otherwise they are compared alphanumerically. Nodes which do not have the specified rank attribute will be ordered by node name and treated as if they come after all nodes which do have the rank attribute (if in ascending order).
This determines whether the rank attribute should be used to order the nodes in ascending or descending order.
Possible values: "ascending", or "descending". The default if not specified is "ascending".
The job nodefilters options. See Include/exclude patterns for a general description.
Attributes
Nested elements
Example
<nodefilters excludeprecedence="true">
<filter>.*</filter>
</nodefilters>
Example (deprecated filter include element)
<nodefilters excludeprecedence="true">
<include>
<hostname/>
<type/>
<tags>tomcats</tags>
<os-name/>
<os-family/>
<os-arch/>
<os-version/>
<name/>
</include>
</nodefilters>
The filter string to select matching nodes.
The content of this element is the full node filter string. See User Guide - Node Filters.
The nodefilters include and exclude patterns.
Note: These elements are deprecated and will be removed in a later version of Rundeck. Use the filter string.
Nested elements
node hostname
node resource name
node type
node tags. comma separated
operating system name (eg, Linux, Mac OS X)
operating system family (eg, unix, windows)
operating system architecture (eg i386,sparc)
operating system version
The job workflow sequence.
Attributes
true/false. (default false). If true, the workflow sequence will continue even if there is a failure
node-first/step-first. (default "node-first"). The strategy to use for executing the workflow across nodes.
The strategy attribute determines the way that the workflow is executed. "node-first" means execute the full workflow on each node prior to the next. "step-first" means execute each step across all nodes prior to the next step.
Nested elements
Defines a step for a workflow sequence.
The different types of sequence steps are defined in different ways.
See:
A command can embed a errorhandler to define an action to run if the step fails.
A command can have a description element to set the step description.
Defines an action to handle an error in a command.
The contents of an <errorhandler> are exactly the same as for a command except it cannot contain any errorhandler itself.
The different types of errorhandler steps are defined in different ways.
Attributes
keepgoingOnSuccesskeepgoing is false.See:
Example:
<errorhandler>
<exec>echo this is a shell command</exec>
</errorhandler>
Inline script. Note that using CDATA section will preserve linebreaks in the script. Simply put the script within a script element:
<errorhandler>
<script><![CDATA[#!/bin/bash
echo this is a test
echo whatever
exit 2 ]></script>
</errorhandler>
Script File:
<errorhandler>
<scriptfile>/path/to/a/script</scriptfile>
<scriptargs>-whatever something</scriptargs>
</errorhandler>
Example job reference:
<errorhandler >
<jobref group="My group" name="My Job">
<arg line="-option value -option2 value2"/>
</jobref>
</errorhandler>
Defines a description for a step.
Example:
<command>
<exec>echo this is a shell command</exec>
<description>Demonstrate echo command</description>
</command>
Script steps can be defined in three ways within a command element:
exec element.script element.scriptfile and scriptargs elements.Example exec step:
<command>
<exec>echo this is a shell command</exec>
</command>
Inline script. Note that using CDATA section will preserve linebreaks in the script. Simply put the script within a script element:
<command>
<script><![CDATA[#!/bin/bash
echo this is a test
echo whatever
exit 2 ]></script>
</command>
Script File:
<command >
<scriptfile>/path/to/a/script</scriptfile>
<scriptargs>-whatever something</scriptargs>
</command>
Script URL:
<command >
<scripturl>http://example.com/path/to/a/script</scripturl>
<scriptargs>-whatever something</scriptargs>
</command>
When using <script>, or <scriptfile>, you can declare an interpreter to use to execute the script and its args.
Add <scriptinterpreter> to the <command>:
<command >
<scriptinterpreter>sudo -u usera</scriptinterpreter>
<scripturl>http://example.com/path/to/a/script</scripturl>
<scriptargs>-whatever something</scriptargs>
</command>
This will be executed effectively with this commandline:
sudo -u usera script.sh -whatever something
If the filename and arguments need to be quoted when passed to the interpreter, you can declare argsQuoted='true':
<command >
<scriptinterpreter argsquoted='true'>sudo -u usera sh -c </scriptinterpreter>
<scripturl>http://example.com/path/to/a/script</scripturl>
<scriptargs>-whatever something</scriptargs>
</command>
This will execute as:
sudo -u usera sh -c 'script.sh -whatever something'
Define a jobref element within the command element
Attributes
the job name
the group name
true/false whether the Job reference step should run for each node
Nested elements
Optional "arg" element can be embedded:
: option arguments to the script or job
Example passing arguments to the job:
<command >
<jobref group="My group" name="My Job">
<arg line="-option value -option2 value2"/>
</jobref>
</command>
If nodeStep is set to "true", then the Job Reference step will operate as a Node Step instead of the default. As a Node Step it will execute once for each matched node in the containing Job workflow, and can use node attribute variable expansion in the arguments to the job reference.
There are two types of plugin steps that can be defined: Node steps, and workflow steps.
Define either one within the command element:
Both have the following contents:
Attributes
Nested elements
Optional 'configuration' can be embedded containing a list of 'entry' key/value pairs:
Defines plugin configuration entries
Defines a key/value pair for the configuration.
Example node step plugin definition:
<command>
<node-step-plugin type="my-node-step-plugin">
<configuration>
<entry key="someconfig" value="a value"/>
<entry key="timout" value="2000"/>
</configuration>
</node-step-plugin>
</command>
Example workflow step plugin definition:
<command>
<step-plugin type="my-step-plugin">
<configuration>
<entry key="repeat" value="12"/>
<entry key="debug" value="true"/>
</configuration>
</step-plugin>
</command>
Defines a plugin step that executes for each node.
Defines a plugin step that executes once in a workflow.
Contains the key/value pair entries for plugin configuration, within a node-step-plugin or step-plugin.
Defines a key/value pair within a configuration.
Attributes:
Key for the pair
Textual value
Defines email, webhook or plugin notifications for Job success and failure, with in a job definition.
Nested elements
define notifications for success result
define notifications for failure/kill result
define notifications for job start
Example
<notification>
<onfailure>
<email recipients="test@example.com,foo@example.com" />
</onfailure>
<onsuccess>
<email recipients="test@example.com" />
<webhook urls="http://example.com?id=${execution.id}" />
</onsuccess>
<onstart>
<plugin type="MyPlugin">
<configuration>
<entry key="customkey" value="customvalue"/>
</configuration>
</plugin>
</onstart>
</notification>
Embed an email element to send email on success, within notification.
Embed an webhook element to perform a HTTP POST to some URLs, within notification.
Embed an plugin element to perform a custom action, within notification.
Embed an email element to send email on failure or kill, within notification.
Embed an webhook element to perform a HTTP POST to some URLs, within notification.
Embed an plugin element to perform a custom action, within notification.
Embed an email element to send email on failure or kill, within notification.
Embed an webhook element to perform a HTTP POST to some URLs, within notification.
Embed an plugin element to perform a custom action, within notification.
Define email recipients for Job execution result, within onsuccess, onfailure or onstart.
Attributes
Example
<email recipients="test@example.com,dev@example.com" />
Define URLs to submit a HTTP POST to containing the job execution result, within onsuccess, onfailure or onstart.
Attributes
Example
<webhook urls="http://server/callback?id=${execution.id}&status=${execution.status}&trigger=${notification.trigger}"/>
Defines a configuration for a plugin to perform a Notification, within onsuccess, onfailure or onstart.
Attributes
Nested elements
Optional 'configuration' can be embedded containing a list of 'entry' key/value pairs:
Defines plugin configuration entries
Defines a key/value pair for the configuration.
Example notification plugin definition:
<onstart>
<plugin type="my-notification-plugin">
<configuration>
<entry key="someconfig" value="a value"/>
<entry key="timout" value="2000"/>
</configuration>
</plugin>
</onstart>
Contains the key/value pair entries for plugin configuration, within a plugin notification definition.
Defines a key/value pair within a configuration.
Attributes:
Key for the pair
Textual value
[rd-jobs](../man1/rd-jobs.html)
The Rundeck source code and all documentation may be downloaded from https://github.com/rundeck/rundeck/.