21. Job Templates¶

21.1. Create a Job Template¶

To create a new job template:

1. Click the Add button then select Job Template from the menu list.

2. Enter the appropriate details into the following fields:

Job Template default credentials must be replaced
with one of the same type. Please select a credential
for the following types in order to proceed: Machine.

3. Options: Specify options for launching this template, if necessary.

• Privilege Escalation: If checked, you enable this playbook to run as an administrator. This is the equivalent of passing the --become option to the ansible-playbook command.

• Provisioning Callbacks: If checked, you enable a host to call back to automation controller via the REST API and invoke the launch of a job from this job template. Refer to Provisioning Callbacks for additional information.

• Enable Webhook: Turns on the ability to interface with a predefined SCM system web service that is used to launch a job template. Currently supported SCM systems are GitHub and GitLab.

If you enable webhooks, other fields display, prompting for additional information:

• Webhook Service: Select which service to listen for webhooks from

• Webhook URL: Automatically populated with the URL for the webhook service to POST requests to.

• Webhook Key: Generated shared secret to be used by the webhook service to sign payloads sent to automation controller. This must be configured in the settings on the webhook service in order for automation controller to accept webhooks from this service.

• Webhook Credential: Optionally, provide a GitHub or GitLab personal access token (PAT) as a credential to use to send status updates back to the webhook service. Before you can select it, the credential must exist. See Credential Types to create one.

For additional information on setting up webhooks, see Working with Webhooks.

• Concurrent Jobs: If checked, you are allowing jobs in the queue to run simultaneously if not dependent on one another. Check this box if you want to run job slices simultaneously. Refer to Automation Controller Capacity Determination and Job Impact for additional information.

• Enable Fact Storage: When checked, automation controller will store gathered facts for all hosts in an inventory related to the job running.

• Prevent Instance Group Fallback: Check this option to allow only the instance groups listed in the Instance Groups field above to execute the job. If unchecked, all available instances in the execution pool will be used based on the hierarchy described in Control Where a Job Runs. Click the icon for more information.

4. When you have completed configuring the details of the job template, click Save.

Saving the template does not exit the job template page but advances to the Job Template Details tab for viewing. After saving the template, you can click Launch to launch the job, or click Edit to add or change the attributes of the template, such as permissions, notifications, view completed jobs, and add a survey (if the job type is not a scan). You must first save the template prior to launching, otherwise, the Launch button remains grayed-out.

You can verify the template is saved when the newly created template appears on the Templates list view.

21.2. Add Permissions¶

1. In the Access tab, click the Add button.

2. Select a user or team to add and click Next

3. Select one or more users or teams from the list by clicking the check box(es) next to the name(s) to add them as members and click Next.

In this example, two users have been selected to be added.

4. Select the role(s) you want the selected user(s) or team(s) to have. Be sure to scroll down for a complete list of roles. Different resources have different options available.

5. Click the Save button to apply the roles to the selected user(s) or team(s) and to add them as members.

The Add Users/Teams window closes to display the updated roles assigned for each user and team.

To remove roles for a particular user, click the disassociate (x) button next to its resource.

This launches a confirmation dialog, asking you to confirm the disassociation.

21.3. Work with Notifications¶

Clicking the Notifications tab allows you to review any notification integrations you have setup and their statuses, if they have ran.

Use the toggles to enable or disable the notifications to use with your particular template. For more detail, see Enable and Disable Notifications.

If no notifications have been set up, click the Add button to create a new notification. Refer to Notification Types for additional details on configuring various notification types and extended messaging.

21.4. View Completed Jobs¶

The Completed Jobs tab provides the list of job templates that have ran. Click Expanded to view details of each job, including its status, ID, and name; type of job, time started and completed, who started the job; and which template, inventory, project, and credential were used. You can filter the list of completed jobs using any of these criteria.

Sliced jobs that display on this list are labeled accordingly, with the number of sliced jobs that have run:

21.5. Scheduling¶

Access the schedules for a particular job template from the Schedules tab.

21.6. Surveys¶

Job types of Run or Check will provide a way to set up surveys in the Job Template creation or editing screens. 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 allow for validation of user input. Click the Survey tab to create a 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.

21.6.1. Create a Survey¶

To create a survey:

1. Click the Survey tab and click the Add button.

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

• Question: 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.

• Required: Whether or not an answer to this question is required from the user.

• Minimum length and Maximum length: Specify if a certain length in the answer is required.

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

3. Once you have entered the question information, click Save to add the question.

The survey question displays in the Survey list. For any question, you can click to edit the question, or check the box next to each question and click Delete to delete the question, or use the toggle button at the top of the screen to enable or disable the survey prompt(s).

If you have more than one survey question, use the Edit Order button to rearrange the order of the questions by clicking and dragging on the grid icon.

4. To add more questions, click the Add button to add additional questions.

21.7. Launch a Job Template¶

A major benefit of automation controller is the push-button deployment of Ansible playbooks. You can easily configure a template to store all parameters you would normally pass to the ansible-playbook on the command line–not just the playbooks, but the inventory, credentials, extra variables, and all options and settings you can specify on the command line.

Easier deployments drive consistency, by running your playbooks the same way each time, and allow you to delegate responsibilities–even users who aren’t Ansible experts can run playbooks written by others.

Launch a job template by any of the following ways:

• Access the job template list from the Templates menu on the left navigation bar or while in the Job Template Details view, scroll to the bottom to access the button from the list of templates.

• While in the Job Template Details view of the job template you want to launch, click Launch.

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

• Credentials that were setup

• The option Prompt on Launch is selected for any parameter

• 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

Below is an example job launch that prompts for Job Tags, and runs the example survey created in Surveys.

Along with any extra variables set in the job template and survey, automation controller automatically adds the following variables to the job environment. Also note, awx_``* variables are defined by the system and cannot be overridden. Variables about the job context, like ``awx_job_template_name are not affected if they are set in extra_vars.

• awx_job_id: The Job ID for this job run

• awx_job_launch_type: The description to indicate how the job was started:

  • manual: Job was started manually by a user.

  • relaunch: Job was started via relaunch.

  • callback: Job was started via host callback.

  • scheduled: Job was started from a schedule.

  • dependency: Job was started as a dependency of another job.

  • workflow: Job was started from a workflow job.

  • sync: Job was started from a project sync.

  • scm: Job was created as an Inventory SCM sync.

• awx_job_template_id: The Job Template ID that this job run uses

• awx_job_template_name: The Job Template name that this job uses

• awx_execution_node: The Execution Node name that launched this job

• awx_project_revision: The revision identifier for the source tree that this particular job uses (it is also the same as the job’s field scm_revision)

• awx_project_scm_branch: The configured default project SCM branch for the project the job template uses

• awx_job_scm_branch If the SCM Branch is overwritten by the job, the value is shown here

• awx_user_email: The user email of the controller user that started this job. This is not available for callback or scheduled jobs.

• awx_user_first_name: The user’s first name of the controller user that started this job. This is not available for callback or scheduled jobs.

• awx_user_id: The user ID of the controller user that started this job. This is not available for callback or scheduled jobs.

• awx_user_last_name: The user’s last name of the controller user that started this job. This is not available for callback or scheduled jobs.

• awx_user_name: The user name of the controller user that started this job. This is not available for callback or scheduled jobs.

• awx_schedule_id: If applicable, the ID of the schedule that launched this job

• awx_schedule_name: If applicable, the name of the schedule that launched this job

• awx_workflow_job_id: If applicable, the ID of the workflow job that launched this job

• awx_workflow_job_name: If applicable, the name of the workflow job that launched this job. Note this is also the same as the workflow job template.

• awx_inventory_id: If applicable, the ID of the inventory this job uses

• awx_inventory_name: If applicable, the name of the inventory this job uses

For compatibility, all variables are also given an “awx” prefix, for example, awx_job_id.

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

When slice jobs are running, job lists display the workflow and job slices, as well as a link to view their details individually.

21.8. Copy a Job Template¶

If you choose to copy Job Template, it does not copy any associated schedule, notifications, or permissions. Schedules and notifications must be recreated by the user or admin creating the copy of the Job Template. The user copying the Job Template will be granted the admin permission, but no permissions are assigned (copied) to the Job Template.

1. Access the job template list from the Templates menu on the left navigation bar or while in the Job Template Details view, scroll to the bottom to access it from the list of templates.

2. Click the button associated with the template you want to copy.

The new template with the name of the template from which you copied and a timestamp displays in the list of templates.

3. Click to open the new template and click Edit.

4. Replace the contents of the Name field with a new name, and provide or modify the entries in the other fields to complete this page.

5. Click Save when done.

21.8.1. Fact Scan Playbooks¶

The scan job playbook, scan_facts.yml, contains invocations of three fact scan modules - packages, services, and files, along with Ansible’s standard fact gathering. The scan_facts.yml playbook file looks like the following:

- hosts: all
  vars:
    scan_use_checksum: false
    scan_use_recursive: false
  tasks:
    - scan_packages:
    - scan_services:
    - scan_files:
        paths: '{{ scan_file_paths }}'
        get_checksum: '{{ scan_use_checksum }}'
        recursive: '{{ scan_use_recursive }}'
      when: scan_file_paths is defined

The scan_files fact module is the only module that accepts parameters, passed via extra_vars on the scan job template.

scan_file_paths: '/tmp/'
scan_use_checksum: true
scan_use_recursive: true

• The scan_file_paths parameter may have multiple settings (such as /tmp/ or /var/log).

• The scan_use_checksum and scan_use_recursive parameters may also be set to false or omitted. An omission is the same as a false setting.

Scan job templates should enable become and use credentials for which become is a possibility. You can enable become by checking the Enable Privilege Escalation from the Options menu:

---

- name: Get Ubuntu 16, and on ready
 hosts: all
 sudo: yes
 gather_facts: no

 tasks:

 - name: install python-simplejson
   raw: sudo apt-get -y update
   raw: sudo apt-get -y install python-simplejson
   raw: sudo apt-get install python-apt

---

- name: Get Fedora ready
 hosts: all
 sudo: yes
 gather_facts: no

 tasks:

 - name: install python-simplejson
   raw: sudo dnf -y update
   raw: sudo dnf -y install python-simplejson
   raw: sudo dnf -y install rpm-python

- hosts: all
  gather_facts: false
  tasks:
    - scan_foo:

def main():
    module = AnsibleModule(
        argument_spec = dict())

    foo = [
      {
        "hello": "world"
      },
      {
        "foo": "bar"
      }
    ]
    results = dict(ansible_facts=dict(foo=foo))
    module.exit_json(**results)

main()

[
   {
     "hello": "world"
   },
   {
     "foo": "bar"
   }
 ]

21.9. Fact Caching¶

Automation controller can store and retrieve facts on a per-host basis through an Ansible Fact Cache plugin. This behavior is configurable on a per-job template basis. Fact caching is turned off by default but can be enabled to serve fact requests for all hosts in an inventory related to the job running. This allows you to use job templates with --limit while still having access to the entire inventory of host facts. A global timeout setting that the plugin enforces per-host, can be specified (in seconds) through the Jobs settings menu:

Upon launching a job that uses fact cache (use_fact_cache=True), the controller will store all ansible_facts associated with each host in the inventory associated with the job. The Ansible Fact Cache plugin that ships with automation controller will only be enabled on jobs with fact cache enabled (use_fact_cache=True).

When a job that has fact cache enabled (use_fact_cache=True) finishes running, the controller will restore all records for the hosts in the inventory. Any records with update times newer than the currently stored facts per-host will be updated in the database.

New and changed facts will be logged via the controller’s logging facility. Specifically, to the system_tracking namespace or logger. The logging payload will include the fields:

• host_name

• inventory_id

• ansible_facts

where ansible_facts is a dictionary of all Ansible facts for host_name in the controller inventory, inventory_id.

21.9.1. Benefits of Fact Caching¶

Fact caching saves a significant amount of time over running fact gathering. If you have a playbook in a job that runs against a thousand hosts and forks, you could easily spend 10 minutes gathering facts across all of those hosts. But if you run a job on a regular basis, the first run of it caches these facts and the next run will just pull them from the database. This cuts the runtime of jobs against large inventories, including Smart Inventories, by an enormous magnitude.

Note

Do not modify the ansible.cfg file to apply fact caching. Custom fact caching could conflict with the controller’s fact caching feature. It is recommended to use the fact caching module that comes with automation controller.

You can choose to use cached facts in your job by enabling it in the Options field of the Job Templates window.

To clear facts, you need to run the Ansible clear_facts meta task. Below is an example playbook that uses the Ansible clear_facts meta task.

- hosts: all
  gather_facts: false
  tasks:
    - name: Clear gathered facts from all currently targeted hosts
      meta: clear_facts

You can find the API endpoint for fact caching at:

http://<controller server name>/api/v2/hosts/x/ansible_facts

21.10. Utilizing Cloud Credentials¶

Cloud Credentials can be used when syncing a respective cloud inventory. Cloud Credentials may also be associated with a Job Template and included in the runtime environment for use by a playbook. Cloud Credentials currently supported:

clouds:
  devstack:
    auth:
      auth_url: http://devstack.yoursite.com:5000/v2.0/
      username: admin
      password: your_password_here
      project_name: demo

- hosts: all
  gather_facts: false
  vars:
    config_file: "{{ lookup('env', 'OS_CLIENT_CONFIG_FILE') }}"
    nova_tenant_name: demo
    nova_image_name: "cirros-0.3.2-x86_64-uec"
    nova_instance_name: autobot
    nova_instance_state: 'present'
    nova_flavor_name: m1.nano

    nova_group:
      group_name: antarctica
      instance_name: deceptacon
      instance_count: 3
  tasks:
    - debug: msg="{{ config_file }}"
    - stat: path="{{ config_file }}"
      register: st
    - include_vars: "{{ config_file }}"
      when: st.stat.exists and st.stat.isreg

    - name: "Print out clouds variable"
      debug: msg="{{ clouds|default('No clouds found') }}"

    - name: "Setting nova instance state to: {{ nova_instance_state }}"
      local_action:
        module: nova_compute
        login_username: "{{ clouds.devstack.auth.username }}"
        login_password: "{{ clouds.devstack.auth.password }}"

- vsphere_guest:
    vcenter_hostname: "{{ lookup('env', 'VMWARE_HOST') }}"
    username: "{{ lookup('env', 'VMWARE_USER') }}"
    password: "{{ lookup('env', 'VMWARE_PASSWORD') }}"
    guest: newvm001
    from_template: yes
    template_src: linuxTemplate
    cluster: MainCluster
    resource_pool: "/Resources"
    vm_extra_config:
      folder: MyFolder

21.11. Provisioning Callbacks¶

Provisioning callbacks are a feature of Automation Controller 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 Automation Controller console. Please note that provisioning callbacks are only used to run playbooks on the calling host. Provisioning callbacks are meant for cloud bursting (i.e. new instances with a need for client to server communication for configuration (such as transmitting an authorization key)), not to run a job against another host. 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 Automation Controller 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 Provisioning Callbacks checkbox in the Job Template. 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. Please provide a custom value for Host Config 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:

https://<CONTROLLER_SERVER_NAME>/api/v2/job_templates/7/callback/

The ‘7’ in this sample URL is the job template ID in Automation Controller.

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

curl -k -f -i -H 'Content-Type:application/json' -XPOST -d '{"host_config_key": "redhat"}' \
                  https://<CONTROLLER_SERVER_NAME>/api/v2/job_templates/7/callback/

The requesting host must be defined in your inventory for the callback to succeed. If Automation Controller 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 one of the example scripts that ships with Automation Controller - /usr/share/awx/request_tower_configuration.sh (Linux/UNIX) or /usr/share/awx/request_tower_configuration.ps1 (Windows). Usage is described in the source code of the file by passing the -h flag, as shown below:

./request_tower_configuration.sh -h
Usage: ./request_tower_configuration.sh <options>

Request server configuration from Ansible Tower.

OPTIONS:
 -h      Show this message
 -s      Controller server (e.g. https://ac.example.com) (required)
 -k      Allow insecure SSL connections and transfers
 -c      Host config key (required)
 -t      Job template ID (required)
 -e      Extra variables

This script has some intelligence, 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.

Most likely you will use callbacks with dynamic inventory in Automation Controller, 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 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 Automation Controller, 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.sh script and make that into an autoscaling image.

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

root@localhost:~$ curl -f -H 'Content-Type: application/json' -XPOST \
                 -d '{"host_config_key": "redhat", "extra_vars": "{\"foo\": \"bar\"}"}' \
                 https://<CONTROLLER_SERVER_NAME>/api/v2/job_templates/7/callback

21.12. Extra Variables¶

When you pass survey variables, they are passed as extra variables (extra_vars) within the controller. 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.

By default, extra_vars are marked as !unsafe unless you specify them on the job template’s Extra Variables section. These are trusted, because they can only be added by users with enough privileges to add or edit a Job Template. For example, nested variables do not expand when entered as a prompt, as the Jinja brackets are treated as a string. For more information about unsafe variables, see unsafe or raw strings.

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.

If specifying the ALLOW_JINJA_IN_EXTRA_VARS parameter, refer to the Controller Tips and Tricks section of the Automation Controller Administration Guide to configure it in the Jobs Settings screen of the controller UI.

Here are some simplified examples of extra_vars in YAML and JSON formats:

The configuration in YAML format:

launch_to_orbit: true
satellites:
  - sputnik
  - explorer
  - satcom

The configuration in JSON format:

{
  "launch_to_orbit": true,
  "satellites": ["sputnik", "explorer", "satcom"]
}

The following table notes the behavior (hierarchy) of variable precedence in automation controller as it compares to variable precedence in Ansible.

Automation Controller Variable Precedence Hierarchy (last listed wins)