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, contingent on the ask__on_launch field on the job template being set to True. For example, a runtime credential is only accepted if the Job Template has ask_credential_on_launch set to True.

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

GET https://your.tower.server/api/v2/job_templates/<yourjobtemplateid>/launch/. The response will contain data such as job_template_data and defaults which give information about the job template.

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

inventory_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

ask_tags_on_launch: Boolean specifying whether to prompt the user for job_tags on launch (allow allows use of skip_tags for convienience)

ask_job_type_on_launch: Boolean specifying whether to prompt the user for job_type on launch

ask_limit_on_launch: Boolean specifying whether to prompt the user for limit on launch

ask_inventory_on_launch: Boolean specifying whether to prompt the user for the related field inventory on launch

ask_credential_on_launch: Boolean specifying whether to prompt the user for the related field credential on launch

POST https://your.tower.server/api/v2/job_templates/<yourjobtemplateid>/launch/ with any required data gathered during the previous step(s). The variables that can be passed in the request data for this action include the following.

extra_vars: A string that represents a JSON or YAML formatted dictionary (with escaped parentheses) which includes variables given by the user, including answers to survey questions

job_tags: A string that represents a comma-separated list of tags in the playbook to run

limit: A string that represents a comma-separated list of hosts or groups to operate on

inventory: A integer value for the foreign key of an inventory to use in this job run

credential: A integer value for the foreign key of a credential to use in this job run

The POST will return data about the job and information about whether the runtime data was accepted. The job id is given in the job field to maintain compatibility with tools written before 3.0. The response will look similar to:

In this example, values for credential and job_tags were given while the job template ask_credential_on_launch and ask_tags_on_launch were False. These were rejected because the job template author did not allow using runtime values for them.

You can see details about the job in this response. To get an updated status, you will need to do a GET request to the job page, /jobs/4, or follow the url link in the response. You can also find related links to cancel, relaunch, and so fourth.

Note

When querying a job on a non-execution node, an error message, stdoutcaptureismissing displays for the result_stdout field and on the related stdout page. In order to generate the stdout, use the format=txt_download query parameter for the related stdout page. This generates the stdout file and any refreshes to either the job or the related std will display the job output.

Note

You cannot assign a new inventory at the time of launch to a scan job. Scan jobs must be tied to a fixed inventory.

Note

You cannot change the Job Type at the time of launch to or from the type of “scan”. The ask_job_type_on_launch option only enables you to toggle “run” versus “check” at launch time.

During the installation process, you are prompted to enter an administrator password which is used for the admin superuser/first user created in Tower. If you log into the instance via SSH, it will tell you the default admin password in the prompt. If you need to change this password at any point, run the following command as root on the Tower server:

awx-managechangepasswordadmin

Next, enter a new password. After that, the password you have entered will work as the admin password in the web UI.

Once in a while you may find it helpful to create an admin (superuser) account from the commandline. To create an admin, run the following command as root on the Tower server and enter in the admin information as prompted:

You must disable PRoot by default if you need to use a jump host. You can disable PRoot through the Configure Tower user interface by setting the Enable Job Isolation toggle to OFF from the Jobs tab:

You can also add a jump host to your Tower instance through Inventory variables. These variables can be set at either the inventory, group, or host level. To add this, navigate to your inventory and in the variables field of whichever level you choose, add the following variables:

While Ansible does not require a configuration file, OS packages often include a default one in /etc/ansible/ansible.cfg for possible customization. In order to use a custom ansible.cfg file, place it at the root of your project. Ansible Tower runs ansible-playbook from the root of the project directory, where it will then find the custom ansible.cfg file. An ansible.cfg anywhere else in the project will be ignored.

Using the defaults are acceptable for starting out, but know that you can configure the default module path or connection type here, as well as other things.

Tower overrides some ansible.cfg options. For example, Tower stores the SSH ControlMaster sockets, the SSH agent socket, and any other per-job run items in a per-job temporary directory, secured by multi-tenancy access control restrictions via PRoot.

Ansible by default gathers “facts” about the machines under its management, accessible in Playbooks and in templates. To view all facts available about a machine, run the setup module as an ad hoc action:

Ansible Tower 3.0 and later uses virtualenv. Virtualenv creates isolated Python environments to avoid problems caused by conflicting dependencies and differing versions. Virtualenv works by simply creating a folder which contains all of the necessary executables and dependencies for a specific version of Python. Ansible Tower creates two virtualenvs during installation–one is used to run Tower, while the other is used to run Ansible. This allows Tower to run in a stable environment, while allowing you to add or update modules to your Ansible Python environment as necessary to run your playbooks. For more information on virtualenv, see the Python Guide to Virtual Environments and the Python virtualenv project itself.

By default, the virtualenv is located at /var/lib/awx/venv/ansible on the file system.

Tower also pre-installs a variety of third-party library/SDK support into this virtualenv for its integration points with a variety of cloud providers (such as EC2, OpenStack, Azure, etc.) Periodically, you may want to add additional SDK support into this virtualenv, which is described in further detail below.

Note

It is highly recommended that you run umask 0022 before installing any packages to the virtual environment. Failure to properly configure permissions can result in Tower service failures. An example follows:

If you want to copy them, the libraries included in Tower’s default virtualenv can be found using pipfreeze:

$ sudo /var/lib/awx/venv/ansible/bin/pip freeze

In a clustered Tower installation, you need to ensure that the same custom virtualenv exists on every local file system at /var/lib/awx/venv/. Custom virtualenvs are supported on isolated instances. If you are using a custom virtual environment, it needs to also be copied or replicated on any isolated node you would be using, not just on the Tower node.

You can also specify the virtual environment to assign to an Organization, Project, and Job Template from their respective edit screens in the Ansible Tower User Interface. Select the virtualenv from the Ansible Environment drop-down menu, as shown in the example below:

In /etc/tower/settings.py, you can modify TOWER_URL_BASE='https://tower.example.com' to change the notification hostname, replacing https://tower.example.com with your preferred hostname. You must restart Tower services after saving your changes with ansible-tower-servicerestart.

Refreshing your Tower license also changes the notification hostname. New installations of Ansible Tower 3.0 should not have to set the hostname for notifications.

Save and trigger an update of the group. You should now be able to see all of your VPC instances.

Note

Tower must be running inside the VPC with access to those instances in order to usefully configure them.

25.14. Filtering instances returned by the dynamic inventory sources in Tower¶

By default, the dynamic inventory sources in Tower (AWS, Rackspace, etc) return all instances available to the cloud credentials being used. They are automatically joined into groups based on various attributes. For example, AWS instances are grouped by region, by tag name and value, by security groups, etc. To target specific instances in your environment, write your playbooks so that they target the generated group names. For example:

----hosts:tag_Name_webservertasks:...

You can also use the Limit field in the Job Template settings to limit a playbook run to a certain group, groups, hosts, or a combination thereof. The syntax is the same as the --limitparameter on the ansible-playbook command line.

You may also create your own groups by copying the auto-generated groups into your custom groups. Make sure that the Overwrite option is disabled on your dynamic inventory source, otherwise subsequent synchronization operations will delete and replace your custom groups.

If there is a feature that is available in the latest Ansible core branch that you would like to leverage with your Tower system, making use of it in Tower is fairly simple.

First, determine which is the updated module you want to use from the available Ansible Core Modules or Ansible Extra Modules GitHub repositories.

Next, create a new directory, at the same directory level of your Ansible source playbooks, named /library.

Once this is created, copy the module you want to use and drop it into the /library directory–it will be consumed first over your system modules and can be removed once you have updated the the stable version via your normal package manager.

Ansible has a flexible method of handling actions during playbook runs, called callback plugins. You can use these plugins with Tower to do things like notify services upon playbook runs or failures, send emails after every playbook run, etc. For official documentation on the callback plugin architecture, refer to: http://docs.ansible.com/developing_plugins.html#callbacks

Note

Ansible Tower does not support the stdout callback plugin because Ansible only allows one, and it is already being used by Ansible Tower for streaming event data.

To use these plugins, put the callback plugin .py file into a directory called /callback_plugins alongside your playbook in your Tower Project.

To make callbacks apply to every playbook, independent of any projects, put the plugins .py file in one of the following directories (depending on your particular Linux distribution and method of Ansible installation):

By default Tower attempts to ssh to hosts. You must add the winrm connection info to the group variables to which the Windows hosts belong. To get started, edit the Windows group in which the hosts reside and place the variables in the source/edit screen for the group.

To add winrm connection info:

Edit the properties for the selected group by clicking on the button to the right of the group name that contains the Windows servers. In the “variables” section, add your connection information as such: ansible_connection:winrm

Once done, save your edits. If Ansible was previously attempting an SSH connection and failed, you should re-run the job template.