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.

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.

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 map. Each map key is the name of the option, and the content is a map defining the Option.

  options:
    optname1:
      [definition..]
    optname2:
      [definition..]

Option

An option definition has no required entries, so it could be empty:

myoption: {}

Optional map entries are:

description

description of the option

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"

sortIndex

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. Any options without a value will be arranged in alphabetical order below the other options.

Example:

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

["x value","y value"]

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

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 of month value. (mutually exclusive with weekday)

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.