12. Job Templates¶

12.1. Utilitzing 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. The use of Cloud Credentials was introduced in Ansible Tower version 2.4.0.

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: centosTemplate
    cluster: MainCluster
    resource_pool: "/Resources"
    vm_extra_config:
      folder: MyFolder

12.2. 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. Click the button 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.

12.2.1. Creating a Survey¶

Clicking on the button brings up the Add Survey window.

Use the ON/OFF toggle button to quickly activate or deactivate this survey prompt.

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.

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

Note

Beginning with Ansible Tower version 2.4, the behavior for Job Template extra variables and Survey variables has changed. Previously, variables set using a Survey overrode any extra variables specified in the Job Template. In 2.4 and later, the Job Template extra variables dictionary is merged with the Survey variables. This may result in a change of behavior upon upgrading to 2.4.

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

Ansible Tower Variable Precedence Hierarchy (last listed wins)

12.3. Scan Job Templates¶

Scan jobs are special Job Templates that only collect information about the host on which the job is running.

Click on Job Templates to create this special type of job template.

To create a new job template click the button, which opens the Create Job Templates window.

Enter values for the following fields and select Save.

• Name: Enter a name appropriate for this inventory. (Required.)
• Description: Enter an arbitrary description as appropriate.
• Job Type: Jobs can be of type Run, Check, or Scan. (Required.)
• Inventory: Select the inventory containing the hosts you want this job to manage. (Required.)
• Project: Select the project containing the playbook you want this job to execute. Use the default project included with Tower unless you have a specific project to scan. (Required.)
• Playbook: Select the playbook to be executed by this job. Use the default playbook included with Tower unless you have a specific playbook to scan. (Required.)
• Machine Credential: Select the credential you want the job to use when accessing the remote hosts. Choose the credential containing the username and SSH key or password that Ansible will need to log into the remote hosts.
• Cloud Credential: Selecting an optional cloud credential in the job template will pass along the access credentials to the running playbook, allowing provisioning into the cloud without manually passing parameters to the included modules.
• Forks: The number of parallel or simultaneous processes to use while executing the playbook.
• Limit: Provide a host pattern to further constrain the list of hosts that will be managed or affected by the playbook.
• Verbosity: Control the level of output Ansible produces as the playbook executes (this is required).
• Job Tags: Provide a comma separated list of tags to run a specific part of a play or task.
• Enable Privilege Escalation: If enabled, run this playbook as an administrator. This is the equivalent of passing the --become option to the ansible-playbook command.
• Allow Provisioning 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.
• Labels: Supply optional labels that describe this job template, such as “dev” or “test”. Labels can be used to group and filter job templates and completed jobs in the Tower display.
  • Labels are created when they are added to the Job Template. Labels are associated to a single Organization using the Project that is provided in the Job Template. Members of the Organization can create labels on a Job Template if they have edit permissions (such as an admin role).
  • Once the Job Template is saved, the labels appear in the Job Templates overview.
  • Click on the “x” beside a label to remove it. When a label is removed, and is no longer associated with a Job or Job Template, the label is permanently deleted from the list of Organization labels.
  • Jobs inherit labels from the Job Template at the time of launch. If a label is deleted from a Job Template, it is also deleted from the Job.

• Extra Variables: Variable definitions and values to be applied to all hosts in this job template. Enter variables using either JSON or YAML syntax. Use the radio button to toggle between the two.

Extra variables can be passed as 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. Example commands might include:

scan_file_paths:
 - /root/
 - /root/
scan_use_checksum: true
scan_use_recursive: true

Extra variables can also be provided by key/value pairs using either YAML or JSON. These variables have a maximum value of precedence and overrides other variables specified elsewhere.

---

- name: Get Ubuntu 15, 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
  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

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

- 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"
   }
 ]

12.4. 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. Please note that provisioning callbacks are only used to run playbooks on the calling host. Provisioning callbacks are meant for cloud bursting, ie: 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 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 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. 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://<Tower server name>/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 one of the example scripts that ships with Tower - /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. 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.

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 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",...}}'

root@localhost:~$ curl -f -H 'Content-Type: application/json' -XPOST \
                 -d '{"host_config_key": "5a8ec154832b780b9bdef1061764ae5a", "extra_vars": "{\"foo\": \"bar\"}"}' \
                 http://<Tower server name>/api/v1/job_templates/1/callback

12.5. Launching Jobs¶

A major benefit of Ansible Tower is the push-button deployment of Ansible playbooks. You can easily configure a template within Tower 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 Tower playbooks written by others.

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 Job Tags, 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.

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