NAME

job-yaml-v13 - The 'job' YAML file declares job entries for Rundeck.

Loading and unloading

This file can be batch loaded via rd-jobs load command:

rd-jobs load -p project --file /path/to/jobs.yaml -F yaml

Rundeck job definitions can be dumped and saved to a file via rd-jobs list command:

rd-jobs list -p project --file /tmp/jobs.yaml -F yaml

Structure

The YAML document can contain multiple Job definitions, in a sequence:

- # job 1
  name: ...
- # job 2
  name: ...

Each Job definition is a Map consisting of some required and some optional entries, as listed below.

Job Map Contents

Each Job definition requires these values:

name

the job name (required)

description

the job description (can be blank). The firstline is the "simple description". Remaining lines are the "extended description".

loglevel

the loglevel to use for the job, the value must be one of:

DEBUG
VERBOSE
INFO
WARN
ERROR

If the description contains more than one line of text, then the first line is used as the "short description" of the job, and rendered exactly as text. The remaining lines are the "extended description", rendered using Markdown format as HTML in the Rundeck GUI. Markdown can also embed HTML directly if you like. See Wikipedia - Markdown.

The HTML is sanitized to remove disallowed tags before rendering to the browser (such as <script>, etc.). You can disable all extended description HTML rendering via a configuration flag. See GUI Customization.

sequence: The workflow sequence definition

A minimal job definition example:

- name: job name
  description: ''
  loglevel: INFO
  sequence: 
    commands:
      - exec: a command

Extended description using yaml 'literal' scalar string format (beginning with a |). Make sure each line is indented to the correct level.

- name: job name
  description: |
    Performs a service
    
    This is <b>html</b>
    <ul><li>bulleted list</li></ul>
    
    <a href="/">Top</a>
    
    1. this is a markdown numbered list
    2. second item
    
    [a link](http://example.com)
  loglevel: INFO
  sequence: 
    commands:
      - exec: a command

In addition, these optional entries can be present:

uuid

Unique UUID

group

Job group name

multipleExecutions

'true/false': if true, the job can have more than one execution at once.

timeout

a maximum runtime before the job will be stopped.

120 - indicates 120 seconds
6h 30m indicates 6 hours and 30 minutes
${option.timeout} reference to a job option value

retry

Number of times to retry the job if it fails or times out. Allowed values:

An integer number indicating the maximum retries
${option.retry} reference to a job option value

loglimit

An optional logging limit.

(See Jobs - Log Limit). Allowed values:

* `###` If you specify a number, that is treated as the "Maximum total number of log lines"
* `###/node` If you specify a number followed by `/node`, the number is treated as the "Maximum number of log lines for a single node"
* `###[GMK]B` If you specify a number followed by a filesize suffix, that is treated as the "total log file size".  The file size suffixes allowed are "GB" (gigabyte), "MB" (megabyte), "KB" (kilobyte) and "B" (byte).

loglimitAction

The action to perform if the loglimit value is exceeded. If loglimit is sepcified, but no loglimitAction is set, it will default to a value of halt. Allowed values:

halt - halt and fail the job (default)
truncate - do not halt the job, and truncate all further output

loglimitStatus

The status for the Job when halted. If no loglimitStatus is set, it will default to a value of failed. Allowed values:

failed
aborted
(any string)

options

Set of Options for the Job

schedule

Job schedule

nodefilters

Node filter definition

notification

Job result notifications

Note: The UUID 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.

Sequence

This defines the Workflow options and execution sequence.

Example:

  sequence:
    keepgoing: true
    strategy: node-first
    commands: 
    - exec: ...
    - script: ...
      args: ...
    - scriptfile: ...
      args:
    - scripturl: ...
      args:
    - jobref:
        name: jobname
        group: group
        args: args
    - nodeStep: true/false
      type: plugin-type
      configuration: 
        key: value
        another: value

The sequence has these required entries:

keepgoing: "true/false" - whether the sequence should keep going if an error occurs
strategy: "node-first" or "step-first". Determines the strategy for executing the sequence across a set of nodes. See the Rundeck User Manual for more info.
commands: This is a Sequence of: * One or more Command Definitions

Command

Each command in the Sequence can be of these different types:

Simple command execution entry
Script execution entry
Script file execution entry
Job Reference entry
Plugin step entry

Each command can also embed an Error Handler.

Each command can have a description.

Error Handler

An Error Handler defines a secondary action in case the first one fails. An Error Handler is a map keyed with the name:

errorhandler

The Error Handler contents can be exactly the same as a Command, except it cannot contain another Error Handler. The contents are defined by one of these types:

Simple command execution entry
Script execution entry
Script file execution entry
Job Reference entry

The errorhandler has this additional optional entry:

keepgoingOnSuccess: "true/false" - If true, and the error handler succeeds, the workflow sequence will continue even if the workflow keepgoing is false.

description

Defines a description for a step.

description: Text to describe this step (optional).

Simple Command Entry

This Command consists of a single entry:

exec: the command to execute

Script Execution Entry

This Command executes the script content specified.

script: The script content. It is useful to use the YAML "literal" scalar syntax shown below
args: Optional string defining arguments to pass to the script.

Example:

   - script: |-
      #!/bin/bash

      echo this is a script
      echo this is option value: @option.test@
    args: arguments passed to the script

Script File Execution Entry

This Command executes a script file stored on the server.

scriptfile: path to the script file
args: optional arguments to the script

Example:

  - scriptfile: /path/to/script
    args: arguments to script

Script URL Execution Entry

This Command downloads a script file from a URL and executes it.

scripturl: URL to the script file
args: optional arguments to the script

Example:

  - scripturl: http://example.com/path/to/script
    args: arguments to script

Script Interpreter

For script, scriptfile and scripturl, you can optionally declare an "interpreter" string to use to execute the script, and whether the arguments are quoted or not.

scriptInterpreter: Optional string to declare an interpreter line for the script. The script and args will be passed to this command, rather than executed directly.

Example:

   - script: |-
      #!/bin/bash

      echo this is a script
      echo this is option value: @option.test@
    args: arguments passed to the script
    scriptInterpreter: interpreter -flag

This script will then be executed as:

interpreter -flag script.sh arguments ...

interpreterArgsQuoted: Optional boolean, indicating whether the script and arguments should be quoted when passed to the interpreter.

If interpreterArgsQuoted is true, then the script will then be executed as:

interpreter -flag 'script.sh arguments ...'

Job Reference Entry

This Command executes another Rundeck Job.

jobref

map consisting of these entries:

name: Name of the Job
group: Group of the Job (optional)
args: Arguments to pass to the job when executed
nodeStep: Execute as a Node Step (optional). true/false.
nodefilters: Overriding node filters and dispatch options.

Example:

  - jobref:
      group: test
      name: simple job test
      args: args for the job

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.

Job Reference Nodefilters

A nodefilters map entry specifies the Nodes to use for the referenced job, and the node-dispatch options. Contains the following entries:

dispatch

a Map containing:

keepgoing: "true/false" - whether to keepgoing on remaining nodes if a node fails
threadcount: Number of threads to use for parallel dispatch (default "1")
rankAttribute: Name of the Node attribute to use for ordering the sequence of nodes (default is the node name)
rankOrder: Order direction for node ranking. Either "ascending" or "descending" (default "ascending")

The nodefilters should contain a filter entry. The value is a string defining a node filter. See User Guide - Node Filters.

filter: A node filter string

Example:

- jobref:
   name: jobname
   group: group
   args: args
   nodefilters:
      dispatch:
        threadcount: 1
        keepgoing: false
        rankAttribute: rank
        rankOrder: descending
      filter: 'tags: web name: web-.* !os-family: windows'

Plugin Step Entry

This Command executes a plugin. There are two types of step plugins: Node step, and Workflow step.

nodeStep: boolean: true indicates it is a Node step plugin, false indicates a Workflow step plugin.
type: The plugin provider type identifier.
configuration: map consisting of a single level of configuration entries for the plugin. Refer to the plugin documentation for appropriate configuration keys and values.

Example:

  - nodeStep: false
    type: jenkins-build
    configuration:
      job: "${option.job}"

Options

Options for a job can be specified with a list of Maps. Each map contains a name key with the name of the option, and the content is a map defining the Option.

  options:
  - {definition..}
  - {definition..}

Note: for backwards compatibility, a Map format is also accepted on import:

  options:
    optname1:
      {definition..}
    optname2:
      {definition..}

Option

An option definition requires at least a name key to identify it:

  options:
  - name: myoption

Optional map entries are:

description: description of the option, will be rendered as Markdown
value: a default value for the option
values: A set of possible values for the option. This must be a YAML Sequence of strings.
required: "true/false" - whether the option is required or not
enforced: "true/false" - whether the option value must be one of the specified possible values
regex: A regular expression defining what option values are acceptable
valuesUrl: A URL to an endpoint that will return a JSON-formatted set of values for the option.
multivalued: "true/false" - whether the option supports multiple input values
delimiter: A string used to conjoin multiple input values. (Required if multivalued is "true")
secure: "true/false" - whether the option is a secure input option. Not compatible with "multivalued"
valueExposed: "true/false" - whether a secure input option value is exposed to scripts or not. false means the option will be used only as a Secure Remote Authentication option. default: false.
storagePath: for a secure option, a storage path to password value to use as default
sortIndex (deprecated): integer - A number indicating the order this option should appear in the GUI. If specified this option will be arranged in order with other options with a sortIndex value. If the Options are defined in a list, the order specified will be preserved.

The description for an Option will be rendered with Markdown in the GUI.

Example:

  test:
    required: true
    description: a test option
    value: dvalue
    regex: ^[abcd]value$
    values:
    - avalue
    - bvalue
    - cvalue
    multivalued: true
    delimiter: ','

Example using multiple lines for the description:

  test:
    required: true
    description: |
      example option description

      * this content will be rendered
      * as markdown
    value: dvalue
    regex: ^[abcd]value$
    values:
    - avalue
    - bvalue
    - cvalue
    multivalued: true
    delimiter: ','

valuesUrl JSON

The data returned from the valuesUrl can be formatted as a list of values:

["x value","y value"]

or as Name-value list:

[
  {name:"X Label", value:"x value"},
  {name:"Y Label", value:"y value"},
  {name:"A Label", value:"a value"}
]

See the Jobs Guide for more info.

Schedule

Define a schedule for repeated execution of the Job. The schedule can be defined as a Crontab formatted string, or as individual components. The individual components support Crontab syntax.

crontab: The crontab string, e.g. "0 30 */6 ? Jan Mon *"

Or use a structure of explicit components. All of these are optional, but likely you want to change them:

time

a map containing:

seconds: seconds value (default: "0")
minute: minutes value (default: "0")
hour: hour value (default: "0")

month

Month value (default: "*")

year

Year value (default "*")

dayofmonth

`day`

:    day of month value. (mutually exclusive with `weekday`) Numerical values start with 1.

weekday

Map containing:

day: Weekday value. (mutually exclusive with dayofmonth) (default: "*") Numerical values are 1-7 for Sunday-Saturday.

Example using crontab string:

    schedule:
      crontab: '0 30 */6 ? Jan Mon *'

Example using structure:

    schedule:
      time:
        hour: '05'
        minute: '01'
        seconds: '0'
      month: APR,MAR,MAY
      year: '*'
      weekday:
        day: FRI,MON,TUE

Nodefilters

Specifies the Nodes to use for the job, and the node-dispatch options. Contains the following entries:

dispatch

a Map containing:

keepgoing: "true/false" - whether to keepgoing on remaining nodes if a node fails
excludePrecedence: "true/false" (default "true") - determines precedence for filters
threadcount: Number of threads to use for parallel dispatch (default "1")
rankAttribute: Name of the Node attribute to use for ordering the sequence of nodes (default is the node name)
rankOrder: Order direction for node ranking. Either "ascending" or "descending" (default "ascending")

The nodefilters should contain a filter entry. The value is a string defining a node filter. See User Guide - Node Filters.

filter: A node filter string

Example:

  nodefilters:
    dispatch:
      threadcount: 1
      keepgoing: false
      excludePrecedence: true
      rankAttribute: rank
      rankOrder: descending
    filter: 'tags: web name: web-.* !os-family: windows'

Note: The include and exclude map entries are deprecated and will be removed in a later version of Rundeck.

The nodefilters must also contain ONE of include or exclude filter specifiers.

include/exclude

A Map containing filter entries:

hostname: Hostname filter
name: Node name filter
tags: Tags filter. Supports boolean operators AND ("+") and OR (",").
os-name: OS name filter
os-family: OS Family filter
os-arch: OS Arch filter
os-version: OS Version filter

Deprecated Example:

  nodefilters:
    dispatch:
      threadcount: 1
      keepgoing: false
      excludePrecedence: true
      rankAttribute: rank
      rankOrder: descending
    include:
      tags: web
      name: web-.*
    exclude:
      os-family: windows

Notification

Defines a notification for the job. You can include any of onsuccess, onfailure or onstart notifications. Each type of notification can define any of the built in notifications, or define plugin notifications.

onsuccess/onfailure/onstart

A Map containing either or both of:

recipients: A comma-separated list of Email addresses
urls: A comma-separated list of URLs to use as webhooks
plugin: Defines a plugin notification.

Example:

  notification:
    onfailure:
      recipients: tom@example.com,shirley@example.com
    onsuccess:
      urls: 'http://server/callback?id=${execution.id}&status=${execution.status}&trigger=${notification.trigger}'
      plugin:
        type: myplugin
        configuration:
          somekey: somevalue
    onstart:
      -  plugin:
          type: myplugin
          configuration:
            somekey: somevalue
      -  plugin:
          type: otherplugin
          configuration:
            a: b

For more information about the Webhook mechanism used, see the chapter Integration - Webhooks.

plugin

Defines a plugin notification section, can contain a single Map, or a Sequence of Maps. Each such map must have these contents:

type: The type identifier of the plugin
configuration: A Map containing any custom configuration key/values for the plugin.

JOB-YAML

NAME

Loading and unloading

Structure

Job Map Contents

Sequence

Command

Error Handler

description

Simple Command Entry

Script Execution Entry

Script File Execution Entry

Script URL Execution Entry

Script Interpreter

Job Reference Entry

Job Reference Nodefilters

Plugin Step Entry

Options

Option

valuesUrl JSON

Schedule

Nodefilters

Notification

plugin

SEE ALSO