API

rundeck

summary:rundeckrun package
license:Apache License, Version 2.0
author:Mark LaPerriere
contact:rundeckrun@mindmind.com
copyright:Mark LaPerriere 2015

rundeck.api

summary:Direct interaction with Rundeck server API
license:Apache License, Version 2.0
author:Mark LaPerriere
contact:rundeckrun@mindmind.com
copyright:Mark LaPerriere 2015
class rundeck.api.RundeckApi(server='localhost', protocol='http', port=4440, api_token=None, **kwargs)

Same as RundeckApiTolerant and complains on every Rundeck Server error or 4xx/5xx HTTP status code.

class rundeck.api.RundeckApiTolerant(server='localhost', protocol='http', port=4440, api_token=None, **kwargs)

As close to the Rundeck API as possible. The “Tolerant” class does not throw exceptions when HTTP status codes are returned. Probably don’t want/need to use this.

IVariables:
connection : RundeckConnection

a RundeckConnection instance

__init__(server='localhost', protocol='http', port=4440, api_token=None, **kwargs)

Initialize a Rundeck API instance

Parameters:
server : str

hostname of the Rundeck server (default: localhost)

protocol : str (‘http’|’https’)

(default: ‘http’)

port : int

Rundeck server port (default: 4440)

api_token : str

valid Rundeck user API token

Keywords:
base_path : str

Custom base URL path for Rundeck server URLs [default: None]

usr : str

Rundeck user name (used in place of api_token)

pwd : str

Rundeck user password (used in combo with usr)

api_version : int

Rundeck API version

connection : RundeckConnection

an instance of a RundeckConnection or instance of a subclass of RundeckConnection

delete_job(job_id, **kwargs)

Wraps Rundeck API DELETE /job/[ID]

Parameters:
job_id : str

Rundeck Job ID

Returns:

A Requests response

Return type:

requests.models.Response

execution(execution_id, **kwargs)

Wraps Rundeck API GET /execution/[ID]

Parameters:
execution_id : str

Rundeck Job Execution ID

Returns:

A RundeckResponse

Return type:

RundeckResponse

execution_abort(execution_id, **kwargs)

Wraps Rundeck API GET /execution/[ID]/output

Parameters:
execution_id : str

Rundeck Job Execution ID

Keywords:
asUser : str

specifies a username identifying the user who aborted the execution

Returns:

A Requests response

Return type:

requests.models.Response

execution_output(execution_id, **kwargs)

Wraps Rundeck API GET /execution/[ID]/output

Parameters:
execution_id : str

Rundeck Job Execution ID

Keywords:
fmt : str

the format of the response one of ExecutionOutputFormat values (default: ‘text’)

offset : int

byte offset to read from in the file, 0 indicates the beginning

lastlines : int

number of lines to retrieve from the end of the available output, overrides offset

lastmod : int

a unix millisecond timestamp; return output data received after this timestamp

maxlines : int

maximum number of lines to retrieve forward from the specified offset

Returns:

A Requests response

Return type:

requests.models.Response

executions(project, **kwargs)

Wraps Rundeck API GET /executions

Parameters:
project : str

name of the project

Keywords:
statusFilter : str

one of Status values

abortedbyFilter : str

user name that aborted the execution

userFilter : str

user name that initiated the execution

recentFilter | str

Use a simple text format to filter executions that completed within a period of time; the format is “XY” where ‘X’ is an integer and ‘Y’ is one of:

  • h:hour
  • d:day
  • w:week
  • m:month
  • y:year

So a value of “2w” would return executions that completed within the last two weeks

begin : int | str

either a unix millisecond timestamp or a W3C dateTime “yyyy-MM-ddTHH:mm:ssZ”

end : int | str

either a unix millisecond timestamp or a W3C dateTime “yyyy-MM-ddTHH:mm:ssZ”

adhoc : bool

includes adhoc executions

jobIdListFilter : str | list

one or more job ids to include

excludeJobIdListFilter : str | list

one or more job ids to exclude

jobListFilter : str | list

one or more full job group/name to include

excludeJobListFilter : str | list

one or more full job group/name to include

groupPath : str

a group or partial group path to include, special “-” setting matches top level jobs only

groupPathExact : str

an exact group path to include, special “-” setting matches top level jobs only

excludeGroupPath : str

a group or partial group path to exclude, special “-” setting matches top level jobs only

excludeGroupPathExact : str

an exact group path to exclude, special “-” setting matches top level jobs only

jobExactFilter : str

an exact job name

exludeJobExactFilter : str

an exact job name to exclude

max : int

maximum number of results to include in response (default: 20)

offset : int

offset for result set (default: 0)

Returns:

A RundeckResponse

Return type:

RundeckResponse

executions_running(project, **kwargs)

Wraps Rundeck API GET /executions/running

Parameters:
project : str

the name of a project

Returns:

A RundeckResponse

Return type:

RundeckResponse

history(project, **kwargs)

Wraps Rundeck API GET /history

Parameters:
project : str

name of the project

Keywords:
jobIdFilter : str

include event for a job ID

reportIdFilter : str

include events for an event name

userFilter : str

include events created by user

statFilter : str

one of Status values

jobListFilter : str | list

one or more full job group/name to include

excludeJobListFilter : str | list

one or more full job group/name to include

recentFilter | str

Use a simple text format to filter executions that completed within a period of time; the format is “XY” where ‘X’ is an integer and ‘Y’ is one of:

  • h:hour
  • d:day
  • w:week
  • m:month
  • y:year

So a value of “2w” would return executions that completed within the last two weeks

begin : int | str

either a unix millisecond timestamp or a W3C dateTime “yyyy-MM-ddTHH:mm:ssZ”

end : int | str

either a unix millisecond timestamp or a W3C dateTime “yyyy-MM-ddTHH:mm:ssZ”

max : int

maximum number of results to include in response (default: 20)

offset : int

offset for result set (default: 0)

Returns:

A RundeckResponse

Return type:

RundeckResponse

job(job_id, **kwargs)

Wraps Rundeck API GET /job/[ID]

Parameters:
job_id : str

Rundeck Job ID

Keywords:
fmt : str

the format of the response one of JobDefFormat values (default: ‘xml’)

Returns:

A Requests response

Return type:

requests.models.Response

job_executions(job_id, **kwargs)

Wraps Rundeck API GET /job/[ID]/executions

Parameters:
job_id : str

a Job ID

Keywords:
status : str

one of Status values

max : int

maximum number of results to include in response (default: 20)

offset : int

offset for result set (default: 0)

Returns:

A RundeckResponse

Return type:

RundeckResponse

job_run(job_id, **kwargs)

Wraps Rundeck API GET /job/[ID]/run

Parameters:
job_id : str

Rundeck Job ID

Keywords:
argString : str | dict

argument string to pass to job - if str, will be passed as-is else if dict will be converted to compatible string

loglevel : str(‘DEBUG’, ‘VERBOSE’, ‘INFO’, ‘WARN’, ‘ERROR’)

logging level (default: ‘INFO’)

asUser : str

user to run the job as

exclude-precedence : bool

set the exclusion precedence (default True)

hostname : str

hostname inclusion filter

tags : str

tags inclusion filter

os-name : str

os-name inclusion filter

os-family : str

os-family inclusion filter

os-arch : str

os-arch inclusion filter

os-version : str

os-version inclusion filter

name : str

name inclusion filter

exlude-hostname : str

hostname exclusion filter

exlude-tags : str

tags exclusion filter

exlude-os-name : str

os-name exclusion filter

exlude-os-family : str

os-family exclusion filter

exlude-os-arch : str

os-arch exclusion filter

exlude-os-version : str

os-version exclusion filter

exlude-name : str

name exclusion filter

Returns:

A RundeckResponse

Return type:

RundeckResponse

jobs(project, **kwargs)

Wraps Rundeck API GET /jobs

Parameters:
project : str

the name of a project

Keywords:
idlist : str | list(str, ...)

specify a comma-separated string or a list of Job IDs to include

groupPath : str

specify a group or partial group path to include all jobs within that group path or “*” for all groups or “-” to match top level jobs only (default: “*”)

jobFilter : str

specify a job name filter; will match any job name that contains this string

jobExactFilter : str

specify an exact job name to match

groupPathExact : str

specify an exact group path to match or “-” to match the top level jobs only

Returns:

A RundeckResponse

Return type:

RundeckResponse

jobs_delete(idlist, **kwargs)

Wraps Rundeck API POST /jobs/delete

Parameters:
ids : str | list(str, ...)

a list of job ids or a string of comma seperated job ids to delete

Returns:

A RundeckResponse

Return type:

RundeckResponse

jobs_export(project, **kwargs)

Wraps Rundeck API GET /jobs/export

Parameters:
name : str

name of the project

Keywords:
fmt : str (‘xml’|’yaml’)

format of the definition string (default: ‘xml’)

idlist : list(str, ...)

a list of job ids to return

groupPath : str

a group path, partial group path or the special top level only char ‘-‘

jobFilter: str

find job names that include this string

Returns:

A Requests response

Return type:

requests.models.Response

jobs_import(definition, **kwargs)

Wraps Rundeck API POST /jobs/import

Parameters:
definition : str

a string representing a job definition

Keywords:
fmt : str (‘xml’|’yaml’)

format of the definition string (default: ‘xml’)

dupeOption : str (‘skip’|’create’|’update’)

a value to indicate the behavior when importing jobs which already exist (default: ‘create’)

project : str

specify the project that all job definitions should be imported to otherwise all job definitions must define a project

uuidOption : str (‘preserve’|’remove’)

preserve or remove UUIDs in imported jobs - preserve may fail if a UUID already exists

Returns:

A RundeckResponse

Return type:

RundeckResponse

project(project, **kwargs)

Wraps Rundeck API /project/[NAME]

Parameters:
project : str

name of Project

Keywords:
create : bool

Create the project if it is not found (requires API version >11) [default: True for API version >11 else False]

Returns:

A RundeckResponse`

Return type:

RundeckResponse

project_jobs(project, **kwargs)
Simulates Rundeck API GET /project/[NAME]/jobs
Note: Can’t find any difference between this and /jobs, so this method is just a
synonym for the jobs method
Parameters:
project : str

name of the project

Keywords:
idlist : list(str, ...)

a list of job ids to return

groupPath : str

a group path, partial group path or the special top level only char ‘-‘

jobFilter: str

find job names that include this string

jobExactFilter : str

a specific job name to return

groupPathExact : str

a exact group path to match or the special top level only char ‘-‘

Returns:

A RundeckResponse

Return type:

RundeckResponse

project_resources(project, **kwargs)

Wraps Rundeck API GET /project/[NAME]/resources

Parameters:
project : str

name of the project

Keywords:
fmt : str

the format of the response one of ExecutionOutputFormat values (default: ‘text’)

hostname : str

hostname inclusion filter

tags : str

tags inclusion filter

os-name : str

os-name inclusion filter

os-family : str

os-family inclusion filter

os-arch : str

os-arch inclusion filter

os-version : str

os-version inclusion filter

name : str

name inclusion filter

exlude-hostname : str

hostname exclusion filter

exlude-tags : str

tags exclusion filter

exlude-os-name : str

os-name exclusion filter

exlude-os-family : str

os-family exclusion filter

exlude-os-arch : str

os-arch exclusion filter

exlude-os-version : str

os-version exclusion filter

exlude-name : str

name exclusion filter

Returns:

A RundeckResponse

Return type:

RundeckResponse

project_resources_refresh(project, providerURL=None, **kwargs)

Wraps Rundeck API POST /project/[NAME]/resources/refresh

Parameters:
project : str

name of the project

providerURL : str

Specify the Resource Model Provider URL to refresh the resources from; otherwise the configured provider URL in the project.properties file will be used

Returns:

A RundeckResponse

Return type:

RundeckResponse

project_resources_update(project, nodes, **kwargs)

Wraps Rundeck API POST /project/[NAME]/resources

Parameters:
project : str

name of the project

nodes : list(RundeckNode, ...)

a list of RundeckNode objects

Returns:

A RundeckResponse

Return type:

RundeckResponse

projects(method='get', **kwargs)

An interface to the Rundeck projects API endpoint support

Parameters:
method : str

GET will retrieve a project, POST will create a project

Returns:

A RundeckResponse

Return type:

RundeckResponse

run_command(project, command, **kwargs)

Wraps Rundeck API GET /run/command

Parameters:
project : str

name of the project

command : str

the shell command string to run

Keywords:
nodeThreadcount : int

the number of threads to use

nodeKeepgoing : bool

if True, continue executing on other nodes even if some fail

asUser : str

specifies a username identifying the user who ran the command; requires runAs permission

hostname : str

hostname inclusion filter

tags : str

tags inclusion filter

os-name : str

os-name inclusion filter

os-family : str

os-family inclusion filter

os-arch : str

os-arch inclusion filter

os-version : str

os-version inclusion filter

name : str

name inclusion filter

exlude-hostname : str

hostname exclusion filter

exlude-tags : str

tags exclusion filter

exlude-os-name : str

os-name exclusion filter

exlude-os-family : str

os-family exclusion filter

exlude-os-arch : str

os-arch exclusion filter

exlude-os-version : str

os-version exclusion filter

exlude-name : str

name exclusion filter

Returns:

A RundeckResponse

Return type:

RundeckResponse

run_script(project, scriptFile, **kwargs)

Wraps Rundeck API POST /run/script

Parameters:
project : str

name of the project

scriptFile : str

a string containing the script file content

Keywords:
argString : str | dict

argument string to pass to job - if str, will be passed as-is else if dict will be converted to compatible string

nodeThreadcount : int

the number of threads to use

nodeKeepgoing : bool

if True, continue executing on other nodes even if some fail

asUser : str

specifies a username identifying the user who ran the command; requires runAs permission

scriptInterpreter : str

a command to use to run the script (requires API version 8 or higher)

interpreterArgsQuoted : bool

if True the script file and arguments will be quoted as the last argument to the scriptInterpreter (requires API version 8 or higher)

hostname : str

hostname inclusion filter

tags : str

tags inclusion filter

os-name : str

os-name inclusion filter

os-family : str

os-family inclusion filter

os-arch : str

os-arch inclusion filter

os-version : str

os-version inclusion filter

name : str

name inclusion filter

exlude-hostname : str

hostname exclusion filter

exlude-tags : str

tags exclusion filter

exlude-os-name : str

os-name exclusion filter

exlude-os-family : str

os-family exclusion filter

exlude-os-arch : str

os-arch exclusion filter

exlude-os-version : str

os-version exclusion filter

exlude-name : str

name exclusion filter

Returns:

A RundeckResponse

Return type:

RundeckResponse

run_url(project, scriptURL, **kwargs)

Wraps Rundeck API POST /run/url Requires API version >4

Parameters:
project : str

name of the project

scriptURL : str

a URL referencing a script to download and run

Keywords:
argString : str | dict

argument string to pass to job - if str, will be passed as-is else if dict will be converted to compatible string

nodeThreadcount : int

the number of threads to use

nodeKeepgoing : bool

if True, continue executing on other nodes even if some fail

asUser : str

specifies a username identifying the user who ran the command; requires runAs permission

scriptInterpreter : str

a command to use to run the script (requires API version 8 or higher)

interpreterArgsQuoted : bool

if True the script file and arguments will be quoted as the last argument to the scriptInterpreter (requires API version 8 or higher)

hostname : str

hostname inclusion filter

tags : str

tags inclusion filter

os-name : str

os-name inclusion filter

os-family : str

os-family inclusion filter

os-arch : str

os-arch inclusion filter

os-version : str

os-version inclusion filter

name : str

name inclusion filter

exlude-hostname : str

hostname exclusion filter

exlude-tags : str

tags exclusion filter

exlude-os-name : str

os-name exclusion filter

exlude-os-family : str

os-family exclusion filter

exlude-os-arch : str

os-arch exclusion filter

exlude-os-version : str

os-version exclusion filter

exlude-name : str

name exclusion filter

Returns:

A RundeckResponse

Return type:

RundeckResponse

system_info(**kwargs)

Wraps Rundeck API GET /system/info

Returns:A RundeckResponse
Return type:RundeckResponse
class rundeck.api.RundeckNode(name, hostname, username, **kwargs)

Represents a Rundeck node; mainly for serializing to XML

IVariables:
name : str

name of the node

hostname : str

hostname of the node

username : str

username used for the remote connection

description : str

node description

osArch : str

the node’s operating system architecture

osFamily : str

the node’s operating system system family

osName : str

the node’s operating system name

tags : list(str, ...)

a list of filtering tags

editUrl : str

URL to an external resource model editor service

remoteUrl : str

URL to an external resource model service

attributes : dict

a dictionary of name/value pairs to be used as node attributes

__init__(name, hostname, username, **kwargs)

Initialize a RundeckNode instance

Parameters:
name : str

name of the node

hostname : str

hostname of the node

username : str

username used for the remote connection

Keywords:
description : str

node description

osArch : str

the node’s operating system architecture

osFamily : str

the node’s operating system system family

osName : str

the node’s operating system name

tags : list(str, ...)

a list of filtering tags

editUrl : str

URL to an external resource model editor service

remoteUrl : str

URL to an external resource model service

attributes : dict

a dictionary of name/value pairs to be used as node attributes

serialize()

serializes the instance to XML

Return type:str
Returns:an XML string
xml
rundeck.api.api_version_check(api_version, required_version)

Raises a NotImplementedError if the api_version of the connection isn’t sufficient

rundeck.client

summary:Python client for interacting with Rundeck API
license:Apache License, Version 2.0
author:Mark LaPerriere
contact:rundeckrun@mindmind.com
copyright:Mark LaPerriere 2015
class rundeck.client.Rundeck(server='localhost', protocol='http', port=4440, api_token=None, **kwargs)
__init__(server='localhost', protocol='http', port=4440, api_token=None, **kwargs)

Initialize a Rundeck API Client

Parameters:
server : str

hostname of the Rundeck server (default: localhost)

protocol : str (‘http’|’https’)

(default: ‘http’)

port : int

Rundeck server port (default: 4440)

api_token : str

valid Rundeck user API token

Keywords:
base_path : str

Custom base URL path for Rundeck server URLs [default: None]

usr : str

Rundeck user name (used in place of api_token)

pwd : str

Rundeck user password (used in combo with usr)

api_version : int

Rundeck API version

api : RundeckApi

an instance of a RundeckApi or subclass of RundeckApi

connection : RundeckConnection

an instance of a RundeckConnection or instance of a subclass of RundeckConnection

abort_execution(*args, **kwargs)

Abort a running Job Execution

Parameters:
execution_id : str

Rundeck Job Execution ID

Keywords:
asUser : str

specifies a username identifying the user who aborted the execution

Returns:

abort status information

Return type:

dict

create_project(*args, **kwargs)

Create a project Requires API version >11

Parameters:
project : str

name of the project

Keywords:
config : dict

a dictionary of key/value pairs for the project config

Returns:

detailed information about a project

Return type:

dict

delete_job(job_id, **kwargs)

Delete a job

Parameters:
job_id : str

Rundeck Job ID

Returns:

success

Return type:

bool

delete_jobs(idlist, **kwargs)

Bulk Job delete

Parameters:
idlist : str | list(str, ...)

a list of job ids or a string of comma seperated job ids to delete

Returns:

results of the bulk delete with details

Return type:

dict

Example Response:

{
'requestCount': 3,
'allsuccessful': False,
'succeeded': {
    'id': '1234-123-123-12345',
    'message': 'success',
    },
'failed': {
    'id': '9876-986-987-98765',
    'message': 'Job ID 9876-986-987-98765 does not exist',
    },
}
execution_status(*args, **kwargs)

Get the status of an execution

Parameters:
execution_id : int

Rundeck Job Execution ID

Returns:

an Execution

Return type:

dict

export_job(job_id, **kwargs)

Export a job definition in XML or YAML format

Parameters:
job_id : str

Rundeck Job ID

Keywords:
fmt : str

the format of the response one of JobDefFormat.values (default: ‘xml’)

Returns:

a Job definition

Return type:

str

get_execution_output(execution_id, **kwargs)

Get the output for an execution in various formats

Parameters:
execution_id : str

Rundeck Job Execution ID

Keywords:
fmt : str

the format of the response one of ExecutionOutputFormat.values (default: ‘json’)

raw : bool

return the results of the Execution output request unmodified (default: False)

offset : int

byte offset to read from in the file, 0 indicates the beginning

lastlines : int

number of lines to retrieve from the end of the available output, overrides offset

lastmod : int

a unix millisecond timestamp; return output data received after this timestamp

maxlines : int

maximum number of lines to retrieve forward from the specified offset

Returns:

Execution output

Return type:

str | dict | RundeckResponse

get_job_id(project, name=None, **kwargs)
Fetch a Job ID that matches the filter criterea specified
WARNING: if there is more than one job that matches the specified criteria, this
will return the first job that Rundeck server includes in the list of matches
Parameters:
project : str

the name of a project

Keywords:
idlist : str | list(str, ...)

specify a comma-separated string or a list of Job IDs to include

groupPath : str

specify a group or partial group path to include all jobs within that group path or “*” for all groups or “-” to match top level jobs only (default: “*”)

jobFilter : str

specify a job name filter; will match any job name that contains this string

jobExactFilter : str

specify an exact job name to match

groupPathExact : str

specify an exact group path to match or “-” to match the top level jobs only

Returns:

a Rundeck Job ID

Return type:

str

get_job_ids(project, **kwargs)

Fetch a list of Job IDs that match the filter criterea specified

Parameters:
project : str

the name of a project

Keywords:
limit : int

limit the result set to 1 or more jobs

idlist : str | list(str, ...)

specify a comma-separated string or a list of Job IDs to include

groupPath : str

specify a group or partial group path to include all jobs within that group path or “*” for all groups or “-” to match top level jobs only (default: “*”)

jobFilter : str

specify a job name filter; will match any job name that contains this string

jobExactFilter : str

specify an exact job name to match

groupPathExact : str

specify an exact group path to match or “-” to match the top level jobs only

Returns:

a list of Job IDs

Return type:

list

get_project(*args, **kwargs)

Fetch a project details

Parameters:
project : str

the name of a project

Returns:

detailed information about a project

Return type:

dict

get_project_history(*args, **kwargs)

List history events for a project

Parameters:
project : str

name of the project

Keywords:
jobIdFilter : str

include event for a job ID

reportIdFilter : str

include events for an event name

userFilter : str

include events created by user

statFilter : str

one of Status.values

jobListFilter : str | list

one or more full job group/name to include

excludeJobListFilter : str | list

one or more full job group/name to include

recentFilter | str

Use a simple text format to filter executions that completed within a period of time; the format is “XY” where ‘X’ is an integer and ‘Y’ is one of:

  • h:hour
  • d:day
  • w:week
  • m:month
  • y:year

So a value of “2w” would return executions that completed within the last two weeks

begin : int | str

either a unix millisecond timestamp or a W3C dateTime “yyyy-MM-ddTHH:mm:ssZ”

end : int | str

either a unix millisecond timestamp or a W3C dateTime “yyyy-MM-ddTHH:mm:ssZ”

max : int

maximum number of results to include in response (default: 20)

offset : int

offset for result set (default: 0)

Returns:

A RundeckResponse

Return type:

RundeckResponse

import_job(*args, **kwargs)

Import a job definition string in XML or YAML format

Parameters:
definition : str

a string representing a job definition

Keywords:
fmt : str (‘xml’|’yaml’)

format of the definition string (default: ‘xml’)

dupeOption : str (‘skip’|’create’|’update’)

a value to indicate the behavior when importing jobs which already exist (default: ‘create’)

project : str

specify the project that all job definitions should be imported to otherwise all job definitions must define a project

uuidOption : str (‘preserve’|’remove’)

preserve or remove UUIDs in imported jobs - preserve may fail if a UUID already exists

Returns:

the results of the job import

Return type:

dict

import_job_file(file_path, **kwargs)

Read in the contents of a job definition file for import

Parameters:
file_path : str

the path to a readable job definition file

Keywords:
file_format : str (‘xml’|’yaml’)

if not specified it will be derived from the file extension (default: ‘xml’)

Raises:

IOError – raised if job definition file can not be found or is not readable

Returns:

a dict object representing a set of Rundeck status messages

Return type:

dict

jobs_export(project, **kwargs)

Export a the job definitions for a project in XML or YAML format

Parameters:
name : str

name of the project

Keywords:
fmt : str (‘xml’|’yaml’)

format of the definition string (default: ‘xml’)

idlist : list(str, ...)

a list of job ids to return

groupPath : str

a group path, partial group path or the special top level only char ‘-‘

jobFilter: str

find job names that include this string

Returns:

a job definition

Return type:

str

list_job_executions(*args, **kwargs)

Get a list of executions of a Job

Parameters:
job : str

A Job ID

Keywords:
status : str

one of Status.values

max : int

maximum number of results to include in response (default: 20)

offset : int

offset for result set (default: 0)

Returns:

a list of Job Executions

Return type:

list(dict, ...)

list_jobs(*args, **kwargs)

Fetch a listing of jobs for a project

Parameters:
project : str

the name of a project

Keywords:
limit : int

limit the result set to 1 or more jobs

idlist : str | list(str, ...)

specify a comma-separated string or a list of Job IDs to include

groupPath : str

specify a group or partial group path to include all jobs within that group path or “*” for all groups or “-” to match top level jobs only (default: “*”)

jobFilter : str

specify a job name filter; will match any job name that contains this string

jobExactFilter : str

specify an exact job name to match

groupPathExact : str

specify an exact group path to match or “-” to match the top level jobs only

Returns:

a list of Jobs

Return type:

list(dict, ...)

list_project_resources(project, **kwargs)

Retrieve the list of resources for a project. If fmt is unspecified, a python dictionary will be returned

Parameters:
project : str

name of the project

Keywords:
fmt : str
the format of the response, either ‘python’ (dict), ‘xml’ or ‘yaml’

(default: ‘python’)

hostname : str

hostname inclusion filter

tags : str

tags inclusion filter

os-name : str

os-name inclusion filter

os-family : str

os-family inclusion filter

os-arch : str

os-arch inclusion filter

os-version : str

os-version inclusion filter

name : str

name inclusion filter

exlude-hostname : str

hostname exclusion filter

exlude-tags : str

tags exclusion filter

exlude-os-name : str

os-name exclusion filter

exlude-os-family : str

os-family exclusion filter

exlude-os-arch : str

os-arch exclusion filter

exlude-os-version : str

os-version exclusion filter

exlude-name : str

name exclusion filter

Returns:

A list of resources or a string representing the requested resources in the requested format

Return type:

list({‘name’: str, ‘hostname’: str, ‘username’: str)) | str

list_projects(*args, **kwargs)

Get a list of projects

Returns:a list of Rundeck projects
Return type:list(dict, ...)
list_running_executions(*args, **kwargs)

Retrieve running executions

Parameters:
project : str

the name of a project (use “*” for all projects - API v9+ required)

Returns:

a list of Job Executions

Return type:

list(dict, ...)

query_executions(*args, **kwargs)

Execution query

Parameters:
project : str

name of the project

Keywords:
statusFilter : str

one of Status.values

abortedbyFilter : str

user name that aborted the execution

userFilter : str

user name that initiated the execution

recentFilter | str

Use a simple text format to filter executions that completed within a period of time; the format is “XY” where ‘X’ is an integer and ‘Y’ is one of:

  • h:hour
  • d:day
  • w:week
  • m:month
  • y:year

So a value of “2w” would return executions that completed within the last two weeks

begin : int | str

either a unix millisecond timestamp or a W3C dateTime “yyyy-MM-ddTHH:mm:ssZ”

end : int | str

either a unix millisecond timestamp or a W3C dateTime “yyyy-MM-ddTHH:mm:ssZ”

adhoc : bool

includes adhoc executions

jobIdListFilter : str | list

one or more job ids to include

excludeJobIdListFilter : str | list

one or more job ids to exclude

jobListFilter : str | list

one or more full job group/name to include

excludeJobListFilter : str | list

one or more full job group/name to include

groupPath : str

a group or partial group path to include, special “-” setting matches top level jobs only

groupPathExact : str

an exact group path to include, special “-” setting matches top level jobs only

excludeGroupPath : str

a group or partial group path to exclude, special “-” setting matches top level jobs only

excludeGroupPathExact : str

an exact group path to exclude, special “-” setting matches top level jobs only

jobExactFilter : str

an exact job name

exludeJobExactFilter : str

an exact job name to exclude

max : int

maximum number of results to include in response (default: 20)

offset : int

offset for result set (default: 0)

Returns:

a list of Job Executions

Return type:

list(dict, ...)

refresh_project_resources(*args, **kwargs)

Refresh the resources for a project via its Resource Model Provider URL

Parameters:
project : str

name of the project

providerURL : str

Specify the Resource Model Provider URL to refresh the resources from; otherwise the configured provider URL in the project.properties file will be used

Returns:

success message

Return type:

dict

run_adhoc_command(*args, **kwargs)

Run a command

Parameters:
project : str

name of the project

command : str

the shell command string to run

Keywords:
nodeThreadcount : int

the number of threads to use

nodeKeepgoing : bool

if True, continue executing on other nodes even if some fail

asUser : str

specifies a username identifying the user who ran the command; requires runAs permission

hostname : str

hostname inclusion filter

tags : str

tags inclusion filter

os-name : str

os-name inclusion filter

os-family : str

os-family inclusion filter

os-arch : str

os-arch inclusion filter

os-version : str

os-version inclusion filter

name : str

name inclusion filter

exlude-hostname : str

hostname exclusion filter

exlude-tags : str

tags exclusion filter

exlude-os-name : str

os-name exclusion filter

exlude-os-family : str

os-family exclusion filter

exlude-os-arch : str

os-arch exclusion filter

exlude-os-version : str

os-version exclusion filter

exlude-name : str

name exclusion filter

Returns:

Execution ID

Return type:

int

run_adhoc_script(*args, **kwargs)

Run a script downloaded from a URL

Parameters:
project : str

name of the project

scriptFile : str

a string containing the script file content

Keywords:
argString : str | dict

argument string to pass to job - if str, will be passed as-is else if dict will be converted to compatible string

nodeThreadcount : int

the number of threads to use

nodeKeepgoing : bool

if True, continue executing on other nodes even if some fail

asUser : str

specifies a username identifying the user who ran the command; requires runAs permission

scriptInterpreter : str

a command to use to run the script (requires API version 8 or higher)

interpreterArgsQuoted : bool

if True the script file and arguments will be quoted as the last argument to the scriptInterpreter (requires API version 8 or higher)

hostname : str

hostname inclusion filter

tags : str

tags inclusion filter

os-name : str

os-name inclusion filter

os-family : str

os-family inclusion filter

os-arch : str

os-arch inclusion filter

os-version : str

os-version inclusion filter

name : str

name inclusion filter

exlude-hostname : str

hostname exclusion filter

exlude-tags : str

tags exclusion filter

exlude-os-name : str

os-name exclusion filter

exlude-os-family : str

os-family exclusion filter

exlude-os-arch : str

os-arch exclusion filter

exlude-os-version : str

os-version exclusion filter

exlude-name : str

name exclusion filter

Returns:

Execution ID

Return type:

int

run_adhoc_url(*args, **kwargs)

Run a script downloaded from a URL

Parameters:
project : str

name of the project

scriptUrl : str

a URL referencing a script to download and run

Keywords:
argString : str | dict

argument string to pass to job - if str, will be passed as-is else if dict will be converted to compatible string

nodeThreadcount : int

the number of threads to use

nodeKeepgoing : bool

if True, continue executing on other nodes even if some fail

asUser : str

specifies a username identifying the user who ran the command; requires runAs permission

scriptInterpreter : str

a command to use to run the script (requires API version 8 or higher)

interpreterArgsQuoted : bool

if True the script file and arguments will be quoted as the last argument to the scriptInterpreter (requires API version 8 or higher)

hostname : str

hostname inclusion filter

tags : str

tags inclusion filter

os-name : str

os-name inclusion filter

os-family : str

os-family inclusion filter

os-arch : str

os-arch inclusion filter

os-version : str

os-version inclusion filter

name : str

name inclusion filter

exlude-hostname : str

hostname exclusion filter

exlude-tags : str

tags exclusion filter

exlude-os-name : str

os-name exclusion filter

exlude-os-family : str

os-family exclusion filter

exlude-os-arch : str

os-arch exclusion filter

exlude-os-version : str

os-version exclusion filter

exlude-name : str

name exclusion filter

Returns:

Execution ID

Return type:

int

run_job(job_id, **kwargs)
Wraps job_run method and implements a blocking mechanism to wait for the job to

complete (within reason, i.e. timeout and interval)

See Rundeck.job_run docstring for additional keyword args

Parameters:
job_id : str

Rundeck Job ID

Keywords:
timeout : int | float

how many seconds to wait for a completed status (default: 60)

interval : int | float

how many seconds to sleep between polling cycles (default: 3)

Returns:

Details about the Job Execution

Return type:

dict

system_info(*args, **kwargs)

Get Rundeck Server System Info

Returns:a dict object representing the Rundeck system information
Return type:dict
update_project_resources(*args, **kwargs)

Update the resources for a project

Parameters:
project : str

name of the project

nodes : list

a list of nodes in the form of a three tuple ((name, hostname, username)) or a dictionary at least the following keys ‘name’, ‘hostname’ and ‘username’

Returns:

success message

Return type:

dict

rundeck.client.is_job_id(job_id)
Checks if a Job ID “looks” like a UUID. It does not check if it exists as a job in Rundeck.
And of course, a Rundeck Job ID does not have to be a “UUID”. Any unique string will do so be prepared for false negatives if you customize your job ids.
Parameters:
job_id : str

a Rundeck Job ID

Return type:

bool

rundeck.connection

summary:Connection object for Rundeck client
license:Apache License, Version 2.0
author:Mark LaPerriere
contact:rundeckrun@mindmind.com
copyright:Mark LaPerriere 2015
requires:requests
class rundeck.connection.RundeckConnection(server='localhost', protocol='http', port=4440, api_token=None, **kwargs)
request(method, url, params=None, headers=None, data=None, files=None, quiet=False)

Override to call raise_for_status forcing non-successful HTTP responses to bubble up as as exceptions

Parameters:
method : str

the HTTP request method

url : str

API URL

params : dict({str: str, ...})

a dict of query string params (default: None)

data : str

the url encoded payload necessary for some commands (default: None)

files : dict({str: str, ...})

a dict of files to upload (default: None)

quiet : bool

suppress calling raise_for_status (default: False)

Return type:

requests.Response

class rundeck.connection.RundeckConnectionTolerant(server='localhost', protocol='http', port=4440, api_token=None, **kwargs)
__init__(server='localhost', protocol='http', port=4440, api_token=None, **kwargs)

Initialize a Rundeck API client connection

Parameters:
server : str

hostname of the Rundeck server (default: localhost)

protocol : str

either http or https (default: ‘http’)

port : int

Rundeck server port (default: 4440)

api_token : str

**Preferred method of authentication - valid Rundeck user API token (default: None)

Keywords:
base_path : str

Custom base URL path for Rundeck server URLs [default: None]

usr : str

Rundeck user name (used in place of api_token)

pwd : str

Rundeck user password (used in combo with usr)

api_version : int

Rundeck API version

verify_cert : bool

Server certificate verification (HTTPS only)

call(method, url, params=None, headers=None, data=None, files=None, parse_response=True, **kwargs)

Format the URL in preparation for making the HTTP request and return a RundeckResponse if requested/necessary

Parameters:
method : str

the HTTP request method

url : str

API URL

params : dict({str: str, ...})

a dict of query string params (default: None)

headers : dict({str: str, ...})

a dict of HTTP headers

data : str

the XML or YAML payload necessary for some commands (default: None)

files : dict({str: str, ...})

a dict of files to upload

parse_response : bool

parse the response as an xml message

Keywords:

passed along to RundeckConnection.request

Return type:

requests.Response

make_api_url(api_url)

Creates a valid Rundeck URL based on the API and the base url of the RundeckConnection

Parameters:
api_url : str

the Rundeck API URL

Return type:

str

Returns:

full Rundeck API URL

make_url(path)

Creates a valid Rundeck URL based base url of the RundeckConnection

Parameters:
path : str

the Rundeck http URL path

Return type:

str

Returns:

full Rundeck URL

request(method, url, params=None, headers=None, data=None, files=None)

Sends the HTTP request to Rundeck

Parameters:
method : str

the HTTP request method

url : str

API URL

params : dict({str: str, ...})

a dict of query string params (default: None)

data : str

the url encoded payload necessary for some commands (default: None)

files : dict({str: str, ...})

a dict of files to upload

Return type:

requests.Response

class rundeck.connection.RundeckResponse(response, client_api_version, as_dict_method=None)
__init__(response, client_api_version, as_dict_method=None)

Parses an XML string into a convenient Python object

Parameters:
response : requests.Response

an instance of the requests.Response returned by the associated command request

api_version
as_dict
message
pprint(*args, **kwargs)
raise_for_error(msg=None)
success
rundeck.connection.memoize(obj)

rundeck.defaults

summary:Default values
license:Apache License, Version 2.0
author:Mark LaPerriere
contact:rundeckrun@mindmind.com
copyright:Mark LaPerriere 2015
class rundeck.defaults.DupeOption
CREATE = 'create'
SKIP = 'skip'
UPDATE = 'update'
keys = ['SKIP', 'CREATE', 'values', 'UPDATE']
values = ['skip', 'create', 'update']
class rundeck.defaults.ExecutionOutputFormat
TEXT = 'text'
XML = 'xml'
YAML = 'yaml'
keys = ['XML', 'YAML', 'values', 'TEXT']
values = ['xml', 'yaml', 'text']
class rundeck.defaults.JobDefFormat
XML = 'xml'
YAML = 'yaml'
keys = ['XML', 'YAML', 'values']
values = ['xml', 'yaml']
class rundeck.defaults.Status
ABORTED = 'aborted'
FAILED = 'failed'
PENDING = 'pending'
RUNNING = 'running'
SKIPPED = 'skipped'
SUCCEEDED = 'succeeded'
keys = ['FAILED', 'RUNNING', 'SKIPPED', 'values', 'ABORTED', 'SUCCEEDED', 'PENDING']
values = ['failed', 'running', 'skipped', 'aborted', 'succeeded', 'pending']
class rundeck.defaults.UuidOption
PRESERVE = 'preserve'
REMOVE = 'remove'
keys = ['PRESERVE', 'values', 'REMOVE']
values = ['preserve', 'remove']
rundeck.defaults.enum(name, *sequential, **named)

rundeck.exceptions

summary:Exceptions
license:Apache License, Version 2.0
author:Mark LaPerriere
contact:rundeckrun@mindmind.com
copyright:Mark LaPerriere 2015
exception rundeck.exceptions.ApiVersionNotSupported

This library does not support the version of the API requested

exception rundeck.exceptions.InvalidAuthentication

The method of authentication is not valid

exception rundeck.exceptions.InvalidDupeOption

The dupeOption specified is invalid

exception rundeck.exceptions.InvalidJobArgument

The Job name or ID is not valid

exception rundeck.exceptions.InvalidJobDefinitionFormat

The specified job definition format is not supported

exception rundeck.exceptions.InvalidResourceSpecification

The resource specified does not meet requirements.

exception rundeck.exceptions.InvalidResponseFormat

The requested response format is not supported

exception rundeck.exceptions.InvalidUuidOption

The uuidOption specified is invalid

exception rundeck.exceptions.JobNotFound

The Job could not be found in the Project

exception rundeck.exceptions.MissingProjectArgument

The requested action requires a Project name to be supplied

exception rundeck.exceptions.RundeckServerError(*args, **kwargs)

Base exceptions generated by the Rundeck server

__init__(*args, **kwargs)

rundeck.transforms

summary:Transformations for RundeckResponses to simple dicts for consumption
license:Apache License, Version 2.0
author:Mark LaPerriere
contact:rundeckrun@mindmind.com
copyright:Mark LaPerriere 2015
requires:requests
rundeck.transforms.events(resp)
rundeck.transforms.execution(resp)
rundeck.transforms.execution_abort(resp)
rundeck.transforms.execution_output(resp)
rundeck.transforms.executions(resp)
rundeck.transforms.is_transform(func)

A simple decorator that marks a function as a “trasform” which allows the transform decorator to only reference functions that are specifically intended to transform client method call responses.

rundeck.transforms.job_import_status(resp)
rundeck.transforms.jobs(resp)
rundeck.transforms.jobs_delete(resp)
rundeck.transforms.project(resp)
rundeck.transforms.project_resources(resp)
rundeck.transforms.projects(resp)
rundeck.transforms.run_execution(resp)
rundeck.transforms.success_message(resp)
rundeck.transforms.system_info(resp)
rundeck.transforms.transform(resp_type)

A decorator to take a RundeckResponse and pass it through one of the is_transform marked functions above

rundeck.util

summary:Utility functions for the package
license:Apache License, Version 2.0
author:Mark LaPerriere
contact:rundeckrun@mindmind.com
copyright:Mark LaPerriere 2015
rundeck.util.attr2dict(el)

Turns an elements attrib dict into... wait for it... a dict. Yea, it’s silly to me too. But, according to the ElementTree docs, using the Element.attrib attribute directly is not recommended - don’t look at me - I just work here.

Parameters:el : ElementTree.Element
Returns:a dictionary of element attrib key/value pairs
Return type:dict
rundeck.util.child2dict(el)

Turns an ElementTree.Element’s children into a dict using the node names as dict keys and and the node text as dict values

Parameters:el : ElementTree.Element
Returns:a dictionary of element key(tag name)/value(node text) pairs
Return type:dict
rundeck.util.cull_kwargs(api_keys, kwargs)

Strips out the api_params from kwargs based on the list of api_keys !! modifies kwargs inline

Parameters:
api_keys : list | set | tuple

an iterable representing the keys of the key value pairs to pull out of kwargs

kwargs : dict

a dictionary of kwargs

Returns:

a dictionary the API params

Return type:

dict

rundeck.util.dict2argstring(argString)

Converts an argString dict into a string otherwise returns the string unchanged

Parameters:
argString : str | dict

argument string to pass to job - if str, will be passed as-is else if dict will be converted to compatible string

Returns:

an argString

Return type:

str

rundeck.util.node2dict(el)

Combines both the attr2dict and child2dict functions