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 ofRundeckConnection
-
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: Return type:
-
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: Return type:
-
executions_running
(project, **kwargs)¶ Wraps Rundeck API GET /executions/running
Parameters: - project : str
the name of a project
Returns: Return type:
-
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: Return type:
-
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: Return type:
-
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: Return type:
-
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: Return type:
-
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: Return type:
-
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: Return type:
-
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:
-
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: Return type:
-
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: Return type:
-
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: Return type:
-
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: Return type:
-
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: Return type:
-
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: Return type:
-
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: Return type:
-
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: Return type:
-
system_info
(**kwargs)¶ Wraps Rundeck API GET /system/info
Returns: A RundeckResponse
Return type: RundeckResponse
- connection :
-
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:
-
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
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