theforeman.foreman.job_invocation – Invoke Remote Execution Jobs

Note

This plugin is part of the theforeman.foreman collection.

To install it use: ansible-galaxy collection install theforeman.foreman.

To use it in a playbook, specify: theforeman.foreman.job_invocation.

New in version 1.4.0: of theforeman.foreman

Synopsis

  • Invoke and schedule Remote Execution Jobs

Requirements

The below requirements are needed on the host that executes this module.

  • requests

Parameters

Parameter Choices/Defaults Comments
bookmark
string
Bookmark to infer the search query from
command
string
Command to be executed on host. Required for command templates
concurrency_control
dictionary
Control concurrency level and distribution over time
concurrency_level
integer
Maximum jobs to be executed at once
time_span
integer
Distribute tasks over given number of seconds
execution_timeout_interval
integer
Override the timeout interval from the template for this invocation only
inputs
dictionary
Inputs to use
job_template
string / required
Job template to execute
password
string / required
Password of the user accessing the Foreman server.
If the value is not specified in the task, the value of environment variable FOREMAN_PASSWORD will be used instead.
randomized_ordering
boolean
    Choices:
  • no
  • yes
Whether to order the selected hosts randomly
recurrence
dictionary
Schedule a recurring job
cron_line
string
How often the job should occur, in the cron format
end_time
string
Perform no more executions after this time
max_iteration
integer
Repeat a maximum of N times
scheduling
dictionary
Schedule the job to start at a later time
start_at
string
Schedule the job for a future time
start_before
string
Indicates that the action should be cancelled if it cannot be started before this time.
search_query
string
Search query to identify hosts
server_url
string / required
URL of the Foreman server.
If the value is not specified in the task, the value of environment variable FOREMAN_SERVER_URL will be used instead.
ssh
dictionary
ssh related options
effective_user
string
What user should be used to run the script (using sudo-like mechanisms)
Defaults to a template parameter or global setting
targeting_type
string
    Choices:
  • static_query ←
  • dynamic_query
Dynamic query updates the search results before execution (useful for scheduled jobs)
username
string / required
Username accessing the Foreman server.
If the value is not specified in the task, the value of environment variable FOREMAN_USERNAME will be used instead.
validate_certs
boolean
    Choices:
  • no
  • yes ←
Whether or not to verify the TLS certificates of the Foreman server.
If the value is not specified in the task, the value of environment variable FOREMAN_VALIDATE_CERTS will be used instead.

Examples

- name: "Run remote command on a single host once"
  job_invocation:
    search_query: "name ^ (foreman.example.com)"
    command: 'ls'
    job_template: "Run Command - SSH Default"
    ssh:
      effective_user: "tester"

- name: "Run ansible command on active hosts once a day"
  job_invocation:
    bookmark: 'active'
    command: 'pwd'
    job_template: "Run Command - Ansible Default"
    recurrence:
      cron_line: "30 2 * * *"
    concurrency_control:
      concurrency_level: 2

Return Values

Common return values are documented here, the following are the fields unique to this module:

Key Returned Description
entity
dictionary
success
Final state of the affected entities grouped by their type.
 
job_invocations
list / elements=dictionary
success
List of job invocations


Authors

  • Peter Ondrejka (@pondrejk)