def job(self, job_id, **kwargs):
"""Wraps `Rundeck API GET /job/[ID] <http://rundeck.org/docs/api/index.html#getting-a-job-definition>`_
:Parameters:
job_id : str
Rundeck Job ID
:Keywords:
fmt : str
the format of the response one of :class:`~rundeck.defaults.JobDefFormat` ``values``
(default: 'xml')
:return: A Requests response
:rtype: requests.models.Response
"""
params = cull_kwargs(('fmt', ), kwargs)
if 'fmt' in params:
params['format'] = params.pop('fmt')
return self._exec(GET,
'job/{0}'.format(job_id),
params=params,
parse_response=False,
**kwargs)
def execution_output(self, execution_id, **kwargs):
"""Wraps `Rundeck API GET /execution/[ID]/output <http://rundeck.org/docs/api/index.html#execution-output>`_
:Parameters:
execution_id : str
Rundeck Job Execution ID
:Keywords:
fmt : str
the format of the response one of :class:`~rundeck.defaults.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
:return: A Requests response
:rtype: requests.models.Response
"""
params = cull_kwargs(
('fmt', 'offset', 'lastlines', 'lastmod', 'maxlines'), kwargs)
if 'fmt' in params:
params['format'] = params.pop('fmt')
parse_response = kwargs.pop('parse_response', False)
return self._exec(GET,
'execution/{0}/output'.format(execution_id),
params=params,
parse_response=parse_response,
**kwargs)
def jobs_export(self, project, **kwargs):
"""Wraps `Rundeck API GET /jobs/export <http://rundeck.org/docs/api/index.html#exporting-jobs>`_
: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
:return: A Requests response
:rtype: requests.models.Response
"""
params = cull_kwargs(('fmt', 'idlist', 'groupPath', 'jobFilter'),
kwargs)
if 'fmt' in params:
params['format'] = params.pop('fmt')
params['project'] = project
return self._exec(GET,
'jobs/export',
params=params,
parse_response=False,
**kwargs)
def jobs_import(self, definition, **kwargs):
"""Wraps `Rundeck API POST /jobs/import <http://rundeck.org/docs/api/index.html#importing-jobs>`_
: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
:return: A :class:`~.rundeck.connection.RundeckResponse`
:rtype: :class:`~.rundeck.connection.RundeckResponse`
"""
data = cull_kwargs(('fmt', 'dupeOption', 'project', 'uuidOption'),
kwargs)
data['xmlBatch'] = definition
if 'fmt' in data:
data['format'] = data.pop('fmt')
return self._exec(POST, 'jobs/import', data=data, **kwargs)
def jobs(self, project, **kwargs):
"""Wraps `Rundeck API GET /jobs <http://rundeck.org/docs/api/index.html#listing-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
:return: A :class:`~.rundeck.connection.RundeckResponse`
:rtype: :class:`~.rundeck.connection.RundeckResponse`
"""
params = cull_kwargs(('idlist', 'groupPath', 'jobFilter',
'jobExactFilter', 'groupPathExact'), kwargs)
if 'jobExactFilter' in params or 'groupPathExact' in params:
self.requires_version(2)
return self._exec(GET,
'project/{project}/jobs'.format(project=project),
params=params,
**kwargs)
def run_command(self, project, command, **kwargs):
"""Wraps `Rundeck API GET /run/command <http://rundeck.org/docs/api/index.html#running-adhoc-commands>`_
: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
:return: A :class:`~.rundeck.connection.RundeckResponse`
:rtype: :class:`~.rundeck.connection.RundeckResponse`
"""
params = cull_kwargs(('nodeThreadcount', 'nodeKeepgoing', 'asUser', 'hostname', 'tags', \
'os-name', 'os-family', 'os-arch', 'os-version', 'name', 'exlude-hostname', \
'exlude-tags', 'exlude-os-name', 'exlude-os-family', 'exlude-os-arch', \
'exlude-os-version', 'exlude-name'), kwargs)
params['project'] = project
params['exec'] = command
return self._exec(GET, 'run/command', params=params, **kwargs)
def project_resources(self, project, **kwargs):
"""Wraps `Rundeck API GET /project/[NAME]/resources <http://rundeck.org/docs/api/index.html#updating-and-listing-resources-for-a-project>`_
:Parameters:
project : str
name of the project
:Keywords:
fmt : str
the format of the response one of :class:`~rundeck.defaults.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
:return: A :class:`~.rundeck.connection.RundeckResponse`
:rtype: :class:`~.rundeck.connection.RundeckResponse`
"""
self.requires_version(2)
params = cull_kwargs(('fmt', 'scriptInterpreter', 'interpreterArgsQuoted', 'hostname', \
'tags', 'os-name', 'os-family', 'os-arch', 'os-version', 'name', 'exlude-hostname', \
'exlude-tags', 'exlude-os-name', 'exlude-os-family', 'exlude-os-arch', \
'exlude-os-version', 'exlude-name'), kwargs)
if 'fmt' in params:
params['format'] = params.pop('fmt')
return self._exec(GET,
'project/{0}/resources'.format(urlquote(project)),
params=params,
**kwargs)
def history(self, project, **kwargs):
"""Wraps `Rundeck API GET /history <http://rundeck.org/docs/api/index.html#listing-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 :class:`~rundeck.defaults.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)
:return: A :class:`~.rundeck.connection.RundeckResponse`
:rtype: :class:`~.rundeck.connection.RundeckResponse`
"""
self.requires_version(4)
params = cull_kwargs(('jobIdFilter', 'reportIdFilter', 'userFilter', 'statFilter', \
'jobListFilter', 'excludeJobListFilter', 'recentFilter', 'begin', 'end', 'max', \
'offset'), kwargs)
params['project'] = project
return self._exec(GET, 'history', params=params, **kwargs)
def execution_abort(self, execution_id, **kwargs):
"""Wraps `Rundeck API GET /execution/[ID]/output <http://rundeck.org/docs/api/index.html#execution-output>`_
:Parameters:
execution_id : str
Rundeck Job Execution ID
:Keywords:
asUser : str
specifies a username identifying the user who aborted the execution
:return: A Requests response
:rtype: requests.models.Response
"""
params = cull_kwargs(('asUser', ), kwargs)
return self._exec(GET,
'execution/{0}/abort'.format(execution_id),
params=params,
**kwargs)
def job_executions(self, job_id, **kwargs):
"""Wraps `Rundeck API GET /job/[ID]/executions <http://rundeck.org/docs/api/index.html#getting-executions-for-a-job>`_
:Parameters:
job_id : str
a Job ID
:Keywords:
status : str
one of :class:`~rundeck.defaults.Status` ``values``
max : int
maximum number of results to include in response (default: 20)
offset : int
offset for result set (default: 0)
:return: A :class:`~.rundeck.connection.RundeckResponse`
:rtype: :class:`~.rundeck.connection.RundeckResponse`
"""
params = cull_kwargs(('status', 'max', 'offset'), kwargs)
return self._exec(GET,
'job/{0}/executions'.format(job_id),
params=params,
**kwargs)
def project_archive_import(self, project, archive_zip_data, **kwargs):
"""Wraps `Rundeck API PUT /api/14/project/[PROJECT]/import <http://rundeck.org/docs/api/index.html#project-archive-import>`_
:Parameters:
project : str
name of the project
archive_zip_data : ?
Zip file containing a project archive.
:Keywords:
jobUuidOption : str ('preserve'|'remove')
Option declaring how duplicate Job UUIDs should be handled. If preserve (default) then
imported job UUIDs will not be modified, and may conflict with jobs in other projects.
If remove then all job UUIDs will be removed before importing.
importExecutions : bool
import all executions and logs from the archive (default: true)
importConfig : bool
import project configurationfrom the archive (default: true)
importACL : bool
import all of the ACL policies from the archive (default: true)
:return: A :class:`~.rundeck.connection.RundeckResponse`
:rtype: :class:`~.rundeck.connection.RundeckResponse`
"""
data = cull_kwargs(
('jobUuidOption', 'importExecutions', 'importConfig', 'importACL'),
kwargs)
headers = {'Content-Type': 'application/zip'}
return self._exec(PUT,
'project/{0}/import'.format(urlquote(project)),
params=data,
data=archive_zip_data,
headers=headers,
**kwargs)
def run_url(self, project, scriptURL, **kwargs):
"""Wraps `Rundeck API POST /run/url <http://rundeck.org/docs/api/index.html#running-adhoc-script-urls>`_
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
:return: A :class:`~.rundeck.connection.RundeckResponse`
:rtype: :class:`~.rundeck.connection.RundeckResponse`
"""
self.requires_version(4)
data = cull_kwargs(('argString', 'nodeThreadcount', 'nodeKeepgoing', 'asUser', \
'scriptInterpreter', 'interpreterArgsQuoted', 'hostname', 'tags', 'os-name', \
'os-family', 'os-arch', 'os-version', 'name', 'exlude-hostname', 'exlude-tags', \
'exlude-os-name', 'exlude-os-family', 'exlude-os-arch', 'exlude-os-version', \
'exlude-name'), kwargs)
data['project'] = project
data['scriptURL'] = scriptURL
if 'scriptInterpreter' in data or 'interpreterArgsQuoted' in data:
self.requires_version(8)
argString = data.get('argString', None)
if argString is not None:
data['argString'] = dict2argstring(argString)
return self._exec(POST, 'run/url', data=data, **kwargs)
def executions(self, project, **kwargs):
"""Wraps `Rundeck API GET /executions <http://rundeck.org/docs/api/index.html#getting-execution-info>`_
:Parameters:
project : str
name of the project
:Keywords:
statusFilter : str
one of :class:`~rundeck.defaults.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)
:return: A :class:`~.rundeck.connection.RundeckResponse`
:rtype: :class:`~.rundeck.connection.RundeckResponse`
"""
self.requires_version(5)
params = cull_kwargs(('statusFilter', 'abortedbyFilter', 'userFilter', 'recentFilter', \
'begin', 'end', 'adhoc', 'jobIdListFilter', 'excludeJobIdListFilter', \
'jobListFilter', 'excludeJobListFilter', 'groupPath', 'groupPathExact', \
'excludeGroupPath', 'excludeGroupPathExact', 'jobExactFilter', \
'exludeJobExactFilter', 'max', 'offset'), kwargs)
params['project'] = project
return self._exec(GET, 'executions', params=params, **kwargs)
def job_run(self, job_id, **kwargs):
"""Wraps `Rundeck API GET /job/[ID]/run <http://rundeck.org/docs/api/index.html#running-a-job>`_
: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
:return: A :class:`~.rundeck.connection.RundeckResponse`
:rtype: :class:`~.rundeck.connection.RundeckResponse`
"""
params = cull_kwargs(('argString', 'loglevel', 'asUser', 'exclude-precedence', \
'hostname', 'tags', 'os-name', 'os-family', 'os-arch', 'os-version', 'name', \
'exlude-hostname', 'exlude-tags', 'exlude-os-name', 'exlude-os-family', \
'exlude-os-arch', 'exlude-os-version', 'exlude-name'), kwargs)
argString = params.get('argString', None)
if argString is not None:
params['argString'] = dict2argstring(argString)
return self._exec(POST,
'job/{0}/run'.format(job_id),
data=params,
**kwargs)
