Documentation

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, and is not always allowed. For example, a runtime credential is only accepted if the Job Template does not have a credential set.

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

  • GET https://your.tower.server/api/v1/job_templates/<your job template id>/launch/

  • 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
    • 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

  • POST https://your.tower.server/api/v1/job_templates/<your job template id>/launch/ with any required data gathered during the previous step(s)

Please note that variables are provided to the playbook (and used in surveys) are accepted as sub-fields inside of the extra_vars field. Other data, such as passwords and credentials, are expected in the top-level JSON POST data.

Additionally, the extra_vars field is where survey question answers should be placed.

The POST will return something similar to:

{ "job": 4 }

If you save that number and then do a GET request to the job page, /jobs/4, you can find details about the job, get an updated status, a link to cancel the job run, and so forth.

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