Documentation

10. Job Templates

A job template is a definition and set of parameters for running an Ansible job. Job templates are useful to execute the same job many times. While the REST API allows executing jobs directly, Tower requires first creating a job template.

This menu opens a list of the job templates that are currently available. The job template list may be sorted and searched by Name or Description. The Job Templates tab also enables the user to launch, schedule, modify, and remove a job template.

Job templates - home with example job template

To create a new job template click the plus button.

Job templates - create new job template

Enter the appropriate details into the following fields:

  • Name: Required

  • Description: Enter an arbitrary description as appropriate.

  • Job Type:

    • Run: Execute the playbook when launched, running Ansible tasks on the selected hosts
    • Check: Execute the playbook in dry-run mode, reporting “changed” when an item would be changed, but not actually making changes.
    • Scan: Gather system tracking information. Only Superusers and Admins have permission to create scan jobs. A default playbook has been created for your use. Custom written scan playbooks can use scan modules.
    • More information on job types can be found in the Playbooks: Special Topics section of the Ansible documentation.

  • Inventory: Choose the inventory to be used with this job template from the inventories available to the currently logged in Tower user.

  • Project: Choose the project to be used with this job template from the projects available to the currently logged in Tower user.

  • Playbook: Choose the playbook to be launched with this job template from the available playbooks. This menu is automatically populated with the names of the playbooks found in the project base path for the selected project. For example, a playbook named “jboss.yml” in the project path appears in the menu as “jboss”.

  • Credential: Choose the credential to be used with this job template from the credentials available to the currently logged in Tower user.

  • Cloud Credential: Choose the credential to be used with this job template from the credentials available to the currently logged in Tower user.

  • Forks: The number of parallel or simultaneous processes to use while executing the playbook. A value of zero uses the Ansible default setting, which is 5 parallel processes unless overridden in /etc/ansible/ansible.cfg.

  • Limit:

    • A host pattern to further constrain the list of hosts managed or affected by the playbook. Multiple patterns can be separated by colons (”:”). As with core Ansible, “a:b” means “in group a or b”, “a:b:&c” means “in a or b but must be in c”, and “a:!b” means “in a, and definitely not in b”.
    • For more information and examples refer to Patterns in the Ansible documentation.

  • Job Tags:

    • A comma-separated list of playbook tags to constrain what parts of the playbooks are executed.
    • For more information and examples refer to Tags in the Ansible documentation.

  • Verbosity: Control the level of output Ansible produces as the playbook executes. Set the verbosity to any of Default, Verbose, or Debug. This only appears in the “details” report view. Verbose logging includes the output of all commands. Debug logging is exceedingly verbose and includes information on SSH operations that can be useful in certain support instances. Most users do not need to see debug mode output.

  • Extra Variables:

    • Pass extra command line variables to the playbook. This is the “-e” or “–extra-vars” command line parameter for ansible-playbook that is documented in the Ansible documentation at Passing Variables on the Command Line.

    • Provide key/value pairs using either YAML or JSON. These variables have a maximum value of precedence and overrides other variables specified elsewhere. An example value might be:

      git_branch: production
release_version: 1.5

  • Prompt for Extra Variables: If this is checked, the user is prompted for Extra Variables at job execution. The set of extra variables defaults to any Extra Variables already configured for the job template.

  • Enable Survey: Survey the user on job launch. Refer to Surveys for additional information.

  • Create Survey: Creates a survey, if the survey is enabled.

  • Edit Survey: Edits the existing survey for this job template.

  • Delete Survey: Deletes the existing survey for this job template.

  • Allow Callbacks: Enable a host to call back to Tower via the Tower API and invoke the launch of a job from this job template. Refer to Provisioning Callbacks for additional information.

When you have completed configuring the job template, select Save.

When editing an existing job template, by clicking the job template name or the Edit button, the bottom of the screen displays a list of all of the jobs that have been launched from this template. Refer to the section Jobs for more information about this interface.

10.1. Surveys

Surveys set extra variables for the playbook similar to ‘Prompt for Extra Variables’ does, but in a user-friendly question and answer way. Surveys also allows for validation of user input. If Enable Survey is checked, you can see a button to Create Survey.

Use cases for surveys are numerous. An example might be if operations wanted to give developers a “push to stage” button they could run without advanced Ansible knowledge. When launched, this task could prompt for answers to questions such as, “What tag should we release?”

Many types of questions can be asked, including multiple-choice questions.

10.1.1. Creating a Survey

Clicking on Create Survey brings up the Add Survey window.

Job template - create survey

A survey can consist of any number of questions. For each question, enter the following information:

  • Name: The question to ask the user
  • Description: (optional) A description of what’s being asked of the user.
  • Answer Variable Name: The Ansible variable name to store the user’s response in. This is the variable to be used by the playbook. Variable names cannot contain spaces.
  • Answer Type: Choose from the following question types.
    • Text: A single line of text. You can set the minimum and maximum length (in characters) for this answer.
    • Textarea: A multi-line text field. You can set the minimum and maximum length (in characters) for this answer.
    • Password: Responses are treated as sensitive information, much like an actual password is treated. You can set the minimum and maximum length (in characters) for this answer.
    • Multiple Choice (single select): A list of options, of which only one can be selected at a time. Enter the options, one per line, in the Multiple Choice Options box.
    • Multiple Choice (multiple select): A list of options, any number of which can be selected at a time. Enter the options, one per line, in the Multiple Choice Options box.
    • Integer: An integer number. You can set the minimum and maximum length (in characters) for this answer.
    • Float: A decimal number. You can set the minimum and maximum length (in characters) for this answer.
  • Default Answer: The default answer to the question. This value is pre-filled in the interface and is used if the answer is not provided by the user.
  • Required: Whether or not an answer to this question is required from the user.

Once you have entered the question information, click Add Question to add the question.

A stylized version of the survey is presented, along with a New Question button. Click this button to add additional questions.

For any question, you can click on the Edit button to edit the question, the Delete button to delete the question, and click on the Up and Down arrow buttons to rearrange the order of the questions. Click Save to save the survey.

job-template-completed-survey

Click Save to save the survey.

10.1.2. Optional Survey Questions

The Required setting on a survey question determines whether the answer is optional or not for the user interacting with it.

Behind the scenes, optional survey variables can be passed to the playbook in extra_vars, even when they aren’t filled in.

  • If a non-text variable (input type) is marked as optional, and is not filled in, no survey extra_var is passed to the playbook.
  • If a text input or text area input is marked as optional, is not filled in, and has a minimum length > 0, no survey extra_var is passed to the playbook.
  • If a text input or text area input is marked as optional, is not filled in, and has a minimum length === 0, that survey extra_var is passed to the playbook, with the value set to an empty string (‘’).

10.1.3. Extra Variables

When you pass survey variables, they are passed as extra variables (extra_vars) within Tower. This can be tricky, as passing extra variables to a job template (as you would do with a survey) can override other variables being passed from the inventory and project.

For example, say that you have a defined variable for an inventory for debug = true. It is entirely possible that this variable, debug = true, can be overridden in a job template survey.

To ensure that the variables you need to pass are not overridden, ensure they are included by redefining them in the survey. Keep in mind that extra variables can be defined at the inventory, group, and host levels.

10.2. Provisioning Callbacks

Provisioning callbacks are a feature of Tower that allow a host to initiate a playbook run against itself, rather than waiting for a user to launch a job to manage the host from the tower console. This provides for automatically configuring a system after it has been provisioned by another system (such as AWS auto-scaling, or a OS provisioning system like kickstart or preseed) or for launching a job programmatically without invoking the Tower API directly.

Frequently this would be accessed via a firstboot type script, or from cron.

To enable callbacks, check the Allow Callbacks checkbox. This displays the Provisioning Callback URL for this job template.

Note

If you intend to use Tower’s provisioning callback feature with a dynamic inventory, Update on Launch should be set for the inventory group used in the Job Template.

Callbacks also require a Host Config Key, to ensure that foreign hosts with the URL cannot request configuration. Click the create button to create a unique host key for this callback, or enter your own key. The host key may be reused across multiple hosts to apply this job template against multiple hosts. Should you wish to control what hosts are able to request configuration, the key may be changed at any time.

To callback manually via REST, look at the callback URL in the UI, which is of the form:

http://<Tower server name>/api/v1/job_templates/1/callback/

The ‘1’ in this sample URL would be the job template ID in Tower.

The request from the host must be a POST. Here is an example using curl (all on a single line):

root@localhost:~$ curl --data "host_config_key=5a8ec154832b780b9bdef1061764ae5a" \
                    http:///api/v1/job_templates/1/callback/

The requesting host must be defined in your inventory for the callback to succeed. If Tower fails to locate the host either by name or IP address in one of your defined inventories, the request is denied.

Note

If your host is not in inventory and Update on Launch is set for the inventory group, Tower attempts to update cloud based inventory source before running the callback.

Successful requests result in an entry on the Jobs tab, where the results and history can be viewed.

While the callback can be accessed via REST, the suggested method of using the callback is to use an example script that ships with Tower at /usr/share/awx/request_tower_configuration.sh. Usage is described in the source code of the file. This script is intelligent in that it knows how to retry commands and is therefore a more robust way to use callbacks than a simple curl request. As written, the script retries once per minute for up to ten minutes, which is amply conservative.

Most likely you will use callbacks with dynamic inventory in Tower, such as pulling cloud inventory from one of the supported cloud providers. In these cases, along with setting Update On Launch, be sure to configure an inventory cache timeout for the inventory source, to avoid abusive hammering of your Cloud’s API endpoints. Since the request_tower_configuration.sh script polls once per minute for up to ten minutes, a suggested cache invalidation time for inventory (configured on the inventory source itself) would be one or two minutes.

While we recommend against running the request_tower_configuration.sh script from a cron job, a suggested cron interval would be perhaps every 30 minutes. Repeated configuration can be easily handled by scheduling in Tower, so the primary use of callbacks by most users is to enable a base image that is bootstrapped into the latest configuration upon coming online. To do so, running at first boot is a better practice. First boot scripts are just simple init scripts that typically self-delete, so you would set up an init script that called a copy of the request\_tower\_configuration script and make that into an autoscaling image.

10.3. Launching Jobs

To launch a job template, click the launch button.

A job may require additional information to run. The following data may be requested at launch:

  • Credentials that were setup
  • Passwords or passphrases that have been set to Ask
  • A survey, if one has been configured for the job templates
  • Extra variables, if requested by the job template

Here is an example job launch that prompts for a password, and runs the example survey created in Surveys.

Job launch with credentials and survey

Along with any extra variables set in the job template and survey, Tower automatically adds the following variables to the job environment:

  • tower_job_id: The Job ID for this job run
  • tower_job_launch_type: One of manual, callback, or scheduled to indicate how the job was started
  • tower_job_template_id: The Job Template ID that this job run uses
  • tower_job_template_name: The Job Template name that this job uses
  • tower_user_id: The user ID of the Tower user that started this job. This is not available for callback or scheduled jobs.
  • tower_user_name: The user name of the Tower user that started this job. This is not available for callback or scheduled jobs.

Upon launch, Tower automatically redirects the web browser to the Job Status page for this job under the Jobs tab.

10.4. Scheduling

Launching job templates may also be scheduled via the schedule button. Clicking this button opens the Schedules page.

Job Templates - schedule launch

This page displays a list of the schedules that are currently available for the selected Job Template. The schedule list may be sorted and searched by Name.

The list of schedules includes: - Name: Clicking the schedule name opens the Edit Schedule dialog - First Run: The first scheduled run of this task - Next Run: The next scheduled run of this task - Final Run: If the task has an end date, this is the last run of the task

Buttons located in the upper right corner of the Schedules screen provide the following actions:

  • Create a new schedule
  • Refresh this view
  • View Activity Stream

10.4.1. Add a new schedule

To create a new schedule click the plus button.

Job Templates - create new schedule

Enter the appropriate details into the following fields and select Save:

  • Name (required)
  • Start Date (required)
  • Start Time (required)
  • Local Time Zone (the entered Start Time should be in this timezone)
  • UTC Start Time (calculated from Start Time + Local Time Zone)
  • Repeat Frequency (the appropriate options displays as the update frequency is modified.)

The Details tab displays a description of the schedule and a list of the scheduled occurrences in the selected Local Time Zone.

Note

Jobs are scheduled in UTC. Repeating jobs that runs at a specific time of day may move relative to a local timezone when Daylight Saving Time shifts occur.

There are several actions available for schedules, under the Actions column:

  • Stop an active schedule or activate a stopped schedule
  • Edit Schedule
  • Delete schedule

Job Templates - newly created schedule