Red Hat Ansible Tower supports Ansible Collections starting with version 3.5 - earlier version will not automatically install and configure them for you. To make sure Ansible Collections are recognized by Red Hat Ansible Tower a requirements file is needed and has to be stored in the proper directory.
Ansible Galaxy is already configured by default, however if you want your Red Hat Ansible Tower to prefer and fetch content from the Red Hat Automation Hub, additional configuration changes are required. They are addressed in a the chapter Use Automation Hub in this lab.
In this exercise you will learn how to define an Ansible Collection as a requirement in a format recognized by Red Hat Ansible Tower. We’ll be using the ansible.posix
collection again from Ansible Galaxy. As you probably know for Ansible Tower to access the needed bits and pieces a version control system is needed. For the sake of keeping this lab setup easy, we’ll set up a local Git server for this.
Set up a Local Git Server
So, let’s get started. We have to create a simplistic Git server on our control host. Typically you would work with GitHub, GitLab, Gitea, or any other Git server.
Make sure to run these steps from your users home directory!
|
|
Next we will clone the repository on the control host. To enable you to work with git on the command line the SSH key for user ec2-user was already added to the Git user git. Next, clone the repository on the control machine:
|
|
The repository is currently empty. The three config commands are just there to avoid warnings from Git.
You now have a local Git server that can be accessed via SSH from Tower.
Create Content for the Ansible Tower Project
Red Hat Ansible Tower can download and install Ansible Collections automatically before executing a Job Template. If a collections/requirements.yml
exists in your project, it will be parsed and the Ansible Collections specified in this file will be automatically installed.
Starting with Red Hat Ansible Tower 3.6 the working directory for the Job Template is in /tmp
. Since the Ansible Collection is downloaded into this directory before the Job Template is executed, you will not find temporary files of your Ansible Collection in /var/lib/awx/projects/
.
The format of the requirements.yml
for Ansible Collections is very similar to the one for roles, however it is very important to store in the folder collections
.
Let’s create the files needed to see how you can use collections in Ansible Tower. This is of course just a simple example. First create the collections
directory in your Git repo (you should have changed into tower_collections
already above):
|
|
Then create the requirements.yml
file listing the collection(s) you need:
|
|
As this is a simple example we’ll just add a Playbook to the Git repo now. Normally you would have a lot more content in your project repository. So what could we do as an example instead of using the ansible.posix
collection again? Let’s create a Playbook to configure an at
job:
|
|
Save the file as configure_at_job.yml
.
Note the usage of the Fully Qualified Collection Name in the Playbook
Make sure everything looks fine:
|
|
So far you created the code only locally on the control host, now you are ready to add it to the repository and push it:
|
|
Create the Project and Job Template
Now it’s time to access your Ansible Tower web UI if you haven’t done so out of curiosity already. Point your browser to the URL you were given on the lab landing page, similar to https://student<N>.<LABID>.open.redhat.com
(replace <N>
with your student number and <LABID>
with the ID of this lab) and log in as admin
. You can find the password again on the lab landing page.
To run your new Playbook in Ansible Tower you have to configure a number of objects:
- An Inventory with the managed hosts
- Machine Credentials to access the managed hosts
- Git Credentials to access your Git repository via SSH
- The Git repo as Project
- A Job Template to run the Playbook
We’ll be a bit verbose for students new to Ansible Tower. If you are an Ansible Tower old-hand, just skip through and finish the configuration steps shown.
Inventory and Machine Credentials
The inventory Workshop Inventory and the machine credentials Workshop Credentials have already been created in your lab environment.
Configure SCM Credentials
Now we will configure the credentials to access our the Git repo on your control host via SSH. In the RESOURCES menu choose Credentials. Now:
Click the button to add new credentials
- NAME: Git Credentials
- ORGANIZATION: Click on the magnifying glass, pick Default and click SELECT
- CREDENTIAL TYPE: Click on the magnifying glass, pick Source Control as type and click SELECT (you will have to use the search or cycle through the types to find it).
- USERNAME: ec2-user
As we are using SSH key authentication, you have to provide an SSH private key that can be used to access the host with the Git repo as the user git
.
The Playbook we used to configure Git added the SSH private key to the authorized_keys
of user git
Bring up your code-server terminal on Tower and use cat
to get the SSH private key:
|
|
-
Copy the complete private key (including “BEGIN” and “END” lines) from the output and paste it into the SSH PRIVATE KEY field in the web UI.
-
Click SAVE
You have now setup credentials to access the Git repo on your control host.
Set up the Project
It’s time to set up the Tower Project pointing to your Git repository holding your Playbook and collections requirements file.
- Go to RESOURCES → Projects in the side menu view click the
button. Fill in the form:
- NAME: Collections Repo
- ORGANIZATION: Default
- SCM TYPE: Git
Now you need the URL to access the repo. You could get the URL in Github as Clone URL. Enter the URL into the Project configuration:
- SCM URL: git@ansible-1:projects/tower_collections
- SCM CREDENTIAL: Click the magnifying glass and choose
Git Credentials
, click SELECT - SCM UPDATE OPTIONS: Tick the first three boxes to always get a fresh copy of the repository and to update the repository when launching a job.
- Click SAVE
The new Project will be synced automatically after creation. If everything went fine, you should see a green icon to the left of the new Project.
Create the Job Template and run it
The last step is to create a Job Template to run the Playbook. Go to the Templates view, click the button and choose Job Template.
-
NAME: Install AT Job
-
JOB TYPE: Run
-
INVENTORY: Workshop Inventory
-
PROJECT: Collections Repo
-
PLAYBOOK:
configure_at_job.yml
-
CREDENTIAL: Workshop Credentials
-
We need to run the tasks as root so check Enable privilege escalation
-
Click SAVE
You can start the job by directly clicking the blue LAUNCH button, or by clicking on the rocket in the Job Templates overview. After launching the Job Template, you are automatically brought to the job overview where you can follow the playbook execution in real time.
After the Job has finished bring up your VSCode terminal, as the job was run on all three managed nodes and the control/ Ansible Tower node, you can simply check the result here. Run sudo at -l
and you should see your job was scheduled successfully.
Troubleshooting
Since Red Hat Ansible Tower does only check for updates in the repository in which you stored your Playbook, it might not do a refresh if there was a change in the Ansible Collection used by your Playbook. This happens particularly if you also combine Roles and Collections.
In this case you should check the option Delete on Update which will delete the entire local directory during a refresh.
If there is a problem while parsing your requirements.yml
it’s worth testing it with the ansible-galaxy
command. As a reminder, Red Hat Ansible Tower basically also just runs the command for you with the appropriate parameters, so testing this works manually makes a lot of sense.
|
|
The -f
switch will forces a fresh installation of the specified Ansible Collections, otherwise ansible-galaxy
will only install it, if it wasn’t already installed. You can also use the --force-with-deps
switch to make sure Ansible Collections which have dependencies to others are refreshed as well.