AWX is the open source version of Ansible Tower. It is composed of a web application that provides a user interface, and a task engine that runs the playbooks. To understand the benefits of AWX the best way is to have a try at it!

This tutorial focuses on how to setup AWX to run some jobs, using Gitlab as a source of files (playbooks, inventory and so on). You should be able to apply these guidelines to Github or another SCM source. This post assumes you already have an AWX instance set up. If not, follow the docs.

Initial setup

To be able to run playbooks, use roles, get hosts and variables from your inventory (without giving you the trouble of recreating everything from scratch from the AWX user interface), you will have to create an AWX project.

AWX can use several sources to retrieve the files:

• Manual source. Use this if your Ansible files can be found on the filesystem where AWX is installed. When using docker-compose, this would be within the docker container - directly from the image or with a volume.
• Source Control Management sources such as Git, Mercurial, etc.

To allow AWX to fetch files from Gitlab, we will first have to create a Credential.

Add a SSH key in Gitlab

In a terminal, execute one of theses commands to create an ssh key:

# without a passphrase
ssh-keygen -N '' -f awx_ssh_key
# with a passphrase
ssh-keygen -f awx_ssh_key

Display and copy the public key:

cat awx_ssh_key.pub

In Gitlab, Go to User Settings > SSH Keys (https://gitlab.com/profile/keys) and create a new key from it.

Add a Source Control credential for Gitlab in AWX

Display and copy the private key:

cat awx_ssh_key

In AWX, Go to Credentials and click on the ”+” button to add a new credential entry. Fill in the following fields:

• NAME: Gitlab awx private key
• CREDENTIAL TYPE: Source Control
• SCM PRIVATE KEY: The content of the awx_ssh_key file
• PRIVATE KEY PASSPHRASE: Your passphrase if required

Create a project in AWX

A project needs to belong to an Organization so you will first have to create one from the Organization tab. Then, in the same way as Credentials, Go on Projects to add a new project. Fill in the following fields:

• NAME. I strongly suggest to include the name of the branch in the project name. In case you create different projects from the same repository, this will be useful to differenciate your projects. For example Gitlab repository - master
• ORGANIZATION. This should be defaulted to the one and only organization you have.
• SCM TYPE: Git
• SCM CREDENTIAL: Look for the Credential Gitlab ‘ansible awx’ private key created in the step above.
• SCM URL: git@gitlab.com:path/to/repo.git. Copy this url using the Clone button in Gitlab on your repository page (the label is clone from SSH for private repositories)
• SCM BRANCH/TAG/COMMIT: master for example.

If you want AWX to fetch the latest version of the branch every time a job uses this project, select UPDATE REVISION ON LAUNCH. Without this option, you will have to manually refresh the project everytime you want to apply new changes from the repo.

💡 In the future, it might be very useful to create multiple projects from the same repository but using different branches. This would allow users to test their playbooks without impacting other users and existing templates.

Import the inventory

Now that AWX can fetch our Ansible files from Gitlab, let’s import the hosts and variables.

In my case, the inventory file is located in the root directory of my repository, as well as the group_vars and host_vars folders. AWX detect all files from these folders. This might not work if they are located elsewhere in the repository.

In the Inventories tab, create an empty inventory - you just have to specify the NAME and the ORGANIZATION. Once created, the SOURCES button will be available. Create a new SOURCE, with SOURCE being Sourced from a Project. Select the previously created project, then choose your inventory file in the INVENTORY FILE select box (hosts in my case)

Create the required credentials

If some files or variables were encrypted using Ansible Vault, you have to create a credential for it. Simply create a second credential with TYPE Vault and set the password. If you have any other kind of credentials that are not available directly from variables (these should be values that you pass as command line arguments when running your playbooks) you will also need to create additional credentials for them.

Run some jobs

Use an existing playbook

We now have everything we need to run our playbooks. As an example, I created a playbook that gives the ansible version running the playbook. This way we can see with which version of ansible AWX runs playbooks.

- name: Check the ansible version
  hosts: '{{ servers }}'
  tasks:
    - name: Display the ansible version
      debug:
        msg: 'ansible version: {{ ansible_version.full }}'

I put this content in a file at playbooks/check_ansible_version/main.yml in the gitlab repository.

The next thing to do is to create a Template.

Templates in AWX are used to defined the execution context of one or more playbooks:

• a template that refers to a single playbook is a Job Template
• a template that composes with multiple playbooks is a Workflow Template

Creating a template

Eventually we are getting to the fun part. Create a new Job template and fill in the fields. The picture below contains everything you need.

Do not forget to add the servers variable used on the playbook to specify on which hosts the playbook will be run. With this playbook, localhost is enough.

💡 If you want to guide your users to set the variables correctly, have a look at the “ADD SURVEY” button.

This template is very simple. For more complex playbooks requiring root privileges, you will need to check the ENABLE PRIVILEGE ESCALATION box.

Now, hit the Launch button to create a job from this template. That’s it!