In this post, we will discuss how to set up job templates and run them against your inventory. We will also discuss job output and how you can view previous job runs to compare and contrast successful/failed runs.
Before we get started, a gentle reminder that in order to run job templates successfully in Red Hat® Ansible® Tower, you will need to have an inventory present, an updated project to select a playbook from to run against and up-to-date credentials.
Job Templates: What Are They?
Job templates are a definition and set of parameters for running an Ansible Playbook. In Ansible Tower, job templates are a visual realization of the ansible-playbook command and all flags you can utilize when executing from the command line. A job template defines the combination of a playbook from a project, an inventory, a credential and any other Ansible parameters required to run.
When you run playbooks from the command line you use arguments to control and direct it. Whether you're invoking an inventory file or setting tags, you will be adding arguments as part of the job template.
What is Needed
Before you can run your job template, there are a few things that you will need in place. The template needs everything that you would need to make a change on a specific machine. Everything from knowledge of how to connect to the machine (credentials) to knowing what you want to change on the machine (project/playbook).
Creating a Job Template
In these steps, we’ll go over how to create a job template from scratch. I’ll be using the demo project that comes with Ansible Tower but you can use any created projected that is assigned to your organization.
To start off with, select templates from the top of the screen next to Inventories. This will bring you to the templates screen where all of your current templates that you can select from. From here, navigate to the ‘Add’ drop down box and select job template from the dropdown selection.
Once selected, this will display the new job template screen. Displayed here is an assortment of options that you can add to your job template to change how it might interact with the machines that it will be touching. For the sake of time, I am only going to cover what is needed to save and run the job template. The sections that are needed are denoted with (*) next to them.
Naming and Job Type
The first two options that needed to added to the template are name and job type. I will leave naming up to your opinion but as for the job type, this drop down selection provides the variety of jobs that can be run with Ansible Tower.
There are three available choices: check and run. The behavior of the template will change depending on which you select.
- Check performs a “dry run” of the playbook and reports changes that would be made without actually making them. Some tasks that have specific modules that do not support check will be skipped automatically in the process and will report nothing back.
- Run will execute the tasks in the playbook on the selected hosts. Depending on what the playbook does will determine the type of job that needs to be selected.
Once you have selected the job type and you have named your job template, you can move on to selecting your inventory, project, and playbook.
Inventory, Product, and Playbook Selection
Arguably the most import three selections that you will make during the job template creation process, the inventory, project, and playbook all play an extremely important role in how this template will be used.
To start, you will need to select the inventory that you want to use this template against. To select one, you can hit the eyeglass in the textbox and this will display all of the available inventories that you have access to. Select the inventory you want to use for this job template. You can use “prompt at launch”, or you can invoke a more complex selection prompt at the beginning of a job using a survey. Once you’ve made a selection, you can move onto choosing the project.
Remember that the project you select will dictate what playbook you can select. The playbook you want for this job template must be housed in the particular project repository so that you can select it. You can select the project you want by the same method you selected your inventory. Once you have your project selected, the playbooks that are housed in this project’s repository will become available to this template.
Choosing the playbook is similar to previous fields on the selection process. Just note that Tower will not display the full file name. For example, if the file name for your playbook is AWS.yml, Ansible Tower will display it as AWS.
Now to the part of the template that deals with authenticating to the machine. Credentials play a crucial role in job templates as they are how Ansible Tower will connect to the machine or cloud to complete the execution of the ansible playbook.
There is only one required but depending on what type of inventory you are acting against, others might be needed. The most important credential is the machine credential. This must be selected for the job template to save but it can also be changed on launch for on the fly template runs against different machines with an inventory.
The other three options on this row of credentials are vault, cloud and network credentials. Here is where my previous statement about needed credentials comes into play. Depending on what you are managing with this template, you might need either a cloud credential or a network credential. With the release of Ansible Tower 3.2, there are a few new changes to credentials. Previously, a vault password was stored in a machine credential, there was a field that you could fill out there. Now it has its own type of credential so that the same vault password can be applied across multiple templates. If you don’t have either of those types created and you need one for the job template, one of our previous blog posts goes into how you can create them.
Forks, Limits, and Verbosity
The next few options allow you the flexibility to control how the template executes and what kind of output is generated. Only one of these options is necessary for the template to be saved but all three can be useful.
The first option you have on this row is forks. Forks are the number of parallel or simultaneous processes in use while executing the playbook. A value of zero uses the default ansible setting of 5. You can override this in ansible.cfg (BAM).
The second option in this row is limit. A limit is a host pattern to further constrain the job template’s targeted hosts. You can provide one or more host patterns separated by a colon, semicolon or comma.
The final option is required for the job template to save properly. Verbosity allows you to control the amount of data returned in the playbook run. Higher verbosity returns a more granular set data as each task runs. There are five levels of verbosity to choose from but Ansible Tower defaults to level 0. To draw a line back to ansible on the command line, this acts in the same way that adding a dash and Vs to the execution command.
There are a few other options that remain below the previous ones I spoke about such as job tags and skip tags. If you currently use either type of these tags, they can go here. For the sake of time, we will not go into detail about tags but documentation of them can be here.
There also a few other options that you can select that address some other opportunities to further customize your job template. They appear under the options header and are Enable Privilege Escalation, Allow Provisioning Callbacks and Enable Concurrent Jobs. The first choice acts in the same manner as passing --become with the ansible-playbook command on the command line. The second choice addresses provisioning callbacks. Allowing provisioning callbacks creates a provisioning callback URL that allows the host to callback to Ansible Tower for configuration based on the specific job template. And if you select Enable Concurrent Jobs, this will allow simultaneous runs of this particular job template.
Example Job Template
Below you can find an example of a completed job template that I am currently running against a slew of AWS Hosts.
In this job template, I am running against my demo inventory that has a few AWS hosts added to it and I am going to install nextcloud on it. I am using a Github repository that I am pulling my playbook from. Since I am running against AWS hosts, I did have to create a cloud credential as well as a machine credential. I also changed the default setting of verbosity to 1 (verbose) to get a slightly more detailed output from this installation.
More and Where to Find It
This was a light take on what job templates can accomplish. There are many creative things that you can do with job templates and all the features that come with them.
Something I didn’t touch on but will in a future post are workflow job templates. As of version 3.1, Ansible Tower is equipped to create and run workflow templates that allow you to string together job templates. Job templates are linked together using a graph-like structure called nodes. Each node represents a single job template and the workflow can be set up in many different ways to allow the maximization of each template. If you want to learn more about workflows templates, you can check out a more in depth dive in documentation on them here.
There are a few things that everyone can look forward to with the Getting Started series. Currently in the works is an automation field guide on how to configure Ansible Tower with your LDAP instance.
Want to learn more about how Ansible works? Visit our overview page.