RundeckRun¶

Getting Started¶

pip install rundeckrun

from rundeck.client import Rundeck
rd = Rundeck(api_token='SECRET_API_TOKEN')
rd.list_projects()

[{
    'description': None,
    'name': 'TestProject',
    'resources': {'providerURL': 'http://localhost:8000/resources.xml'},
}]

Interacting with Rundeck¶

An instance of the Rundeck class is where you’ll spend most with RundeckRun. If you want a more raw interface to the Rundeck API, check out the RundeckApi class. In this case, you’ll definitely want to check out the Rundeck API Reference.

Projects¶

>>> rd.list_projects()
[{
    'description': None,
    'name': 'TestProject',
    'resources': {'providerURL': 'http://localhost:8000/resources.xml'},
}]

Jobs¶

>>> rd.list_jobs('TestProject')
[{'description': 'Hello World!',
  'group': None,
  'id': 'a6e1e0f7-ad32-4b93-ba2c-9387be06a146',
  'name': 'HelloWorld',
  'project': 'TestProject'}]

>>> rd.run_job('a6e1e0f7-ad32-4b93-ba2c-9387be06a146', argString={'from': 'RundeckRun'})
{'argstring': '-from RundeckRun',
 'date-started': datetime.datetime(2013, 7, 11, 18, 4, 24),
 'description': 'Plugin[localexec, nodeStep: true]',
 'href': 'http://rundeck.server.com/execution/follow/123',
 'id': '123',
 'job': None,
 'status': 'running',
 'user': 'rundeckrun'}

argString={'recipients':'admin@example.com,support@example.com'}

>>> print(rd.jobs_export('TestProject', fmt='yaml'))
- id: cb973e3a-e682-4b45-9dbe-9e5301a4361e
project: TestProject
loglevel: INFO
sequence:
  keepgoing: false
  strategy: node-first
  commands:
  - type: localexec
    nodeStep: true
    configuration:
      command: echo "Hello World!"
description: ''
name: TestJob
uuid: cb973e3a-e682-4b45-9dbe-9e5301a4361e
group: RundeckRun/Tests

Resources¶

Importing and Exporting¶

rundeck¶

rundeck.api¶

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¶

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¶

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¶

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¶

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¶

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¶

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