Documentation

11. Launching a Job Template

Ansible Tower makes it simple to launch a job based on a Job Template from Tower’s API or by using the tower-cli command line tool.

Launching a Job Template also:

  • Creates a Job Record
  • Gives that Job Record all of the attributes on the Job Template, combined with certain data you can give in this launch endpoint (“runtime” data)
  • Runs Ansible with the combined data from the JT and runtime data

Runtime data takes precedence over the Job Template data, contingent on the ask_ _on_launch field on the job template being set to True. For example, a runtime credential is only accepted if the Job Template has ask_credential_on_launch set to True.

Launching from Job Templates via the API follows the following workflow:

  • GET https://your.tower.server/api/v2/job_templates/<your job template id>/launch/. The response will contain data such as job_template_data and defaults which give information about the job template.

  • Inspect returned data for runtime data that is needed to launch. Inspecting the OPTIONS of the launch endpoint may also help deduce what POST fields are allowed.

    Warning

    Providing certain runtime credentials could introduce the need for a password not listed in passwords_needed_to_start.

    • passwords_needed_to_start: List of passwords needed
    • credential_needed_to_start: Boolean
    • inventory_needed_to_start: Boolean
    • variables_needed_to_start: List of fields that need to be passed inside of the extra_vars dictionary

  • Inspect returned data for optionally allowed runtime data that the user should be asked for.

    • ask_variables_on_launch: Boolean specifying whether to prompt the user for additional variables to pass to Ansible inside of extra_vars
    • ask_tags_on_launch: Boolean specifying whether to prompt the user for job_tags on launch (allow allows use of skip_tags for convienience)
    • ask_job_type_on_launch: Boolean specifying whether to prompt the user for job_type on launch
    • ask_limit_on_launch: Boolean specifying whether to prompt the user for limit on launch
    • ask_inventory_on_launch: Boolean specifying whether to prompt the user for the related field inventory on launch
    • ask_credential_on_launch: Boolean specifying whether to prompt the user for the related field credential on launch
    • survey_enabled: Boolean specifying whether to prompt the user for additional extra_vars, following the job template’s survey_spec Q&A format

  • POST https://your.tower.server/api/v2/job_templates/<your job template id>/launch/ with any required data gathered during the previous step(s). The variables that can be passed in the request data for this action include the following.

    • extra_vars: A string that represents a JSON or YAML formatted dictionary (with escaped parentheses) which includes variables given by the user, including answers to survey questions
    • job_tags: A string that represents a comma-separated list of tags in the playbook to run
    • limit: A string that represents a comma-separated list of hosts or groups to operate on
    • inventory: A integer value for the foreign key of an inventory to use in this job run
    • credential: A integer value for the foreign key of a credential to use in this job run

The POST will return data about the job and information about whether the runtime data was accepted. The job id is given in the job field to maintain compatibility with tools written before 3.0. The response will look similar to:

{
  "ignored_fields": {
    "credential": 2,
    "job_tags": "setup,teardown"
  }
  "id": 4,
  ...more data about the job...
  "job": 4,
}

In this example, values for credential and job_tags were given while the job template ask_credential_on_launch and ask_tags_on_launch were False. These were rejected because the job template author did not allow using runtime values for them.

You can see details about the job in this response. To get an updated status, you will need to do a GET request to the job page, /jobs/4, or follow the url link in the response. You can also find related links to cancel, relaunch, and so fourth.

Note

When querying a job on a non-execution node, an error message, stdout capture is missing displays for the result_stdout field and on the related stdout page. In order to generate the stdout, use the format=txt_download query parameter for the related stdout page. This generates the stdout file and any refreshes to either the job or the related std will display the job output.

Note

You cannot assign a new inventory at the time of launch to a scan job. Scan jobs must be tied to a fixed inventory.

Note

You cannot change the Job Type at the time of launch to or from the type of “scan”. The ask_job_type_on_launch option only enables you to toggle “run” versus “check” at launch time.

11.1. tower-cli Job Template Launching

From the Tower command line, you can use tower-cli as a method of launching your Job Templates.

For help with tower-cli launch, use:

tower-cli job launch --help.

For launching from a job template, invoke tower-cli in a way similar to:

For an example of how to use the API, you can also add the -v flag here:

tower-cli job launch --job-template=4 -v