10. Job Templates¶

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.

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.

Click Save to save the survey.

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. The Job Template launched only runs against the host requesting the provisioning.

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.

Callbacks also require a Host Config Key, to ensure that foreign hosts with the URL cannot request configuration. Click the 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 is 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. When running a Job Template in this way, the host initiating the playbook run against itself must be in the inventory. If the host is missing from the inventory, the Job Template will fail with a “No Hosts Matched” type error message.

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.

'{"extra_vars": {"variable1":"value1","variable2":"value2",...}}'

10.3. Launching Jobs¶

To launch a job template, click the 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.

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 button. Clicking this button opens the Schedules page.

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