Decoupling Ansible Roles

Decouple the roles from the core Ansible repository using Ansible Galaxy roles.

We'll cover the following

Using roles that live in the Ansible code repository increases reusability. However, reusability is limited to that single repository. When you need to share a role across multiple repositories, use Ansible Galaxy roles.

Ansible Galaxy roles allow you to decouple the role from the core Ansible repository. Galaxy roles are stored in their own git repository, making it possible to develop and version the role independently.

Using the Chocolatey role as an example, you’ll now convert the role to a Galaxy role within its own git repository.

Create a Git repository

Ansible Galaxy roles are very similar to local roles. The major difference is that they are stored outside of the core Ansible repository, in their own repository.

Using GitHub create a new repository for the chocolatey Ansible Galaxy role.

  1. Log into GitHub.
  2. In the upper-right corner of any page, click +, and then click New repository.
  3. Name the repository chocolatey and add a description.
  1. Click Create repository.
  2. After the repository is created, click the Code button.
  3. Take note of the HTTPS URL for the repository. It will be used to install the Galaxy role.

Generate Ansible Galaxy role

Ansible Galaxy roles have the same directory structure as the role when done by hand, but there is an easier way. The command ansible-galaxy has an init option that will create the role’s skeleton.

Git Repository
Create the galaxy role outside of your Ansible repository. Each Galaxy role is stored in its git repository.

  1. Use ansible-galaxy init to generate the role directory structure.
Press + to interact
ansible-galaxy init chocolatey --offline
  1. Use the tree command to view the directory structure of the new Ansible galaxy role.
Press + to interact
tree
  1. Change into the chocolatey directory.
Press + to interact
cd chocolatey
  1. Connect the Ansible Galaxy role to the GitHub repository.
Press + to interact
git init
git add .
git commit -m "init commit"
# Replace <remoteRepositoryURL> with the 
# HTTPS URL of GitHub chocolatey repository.
git remote add origin <remoteRepositoryURL>

Replace <remoteRepositoryURL> with the HTTPS URL of GitHub Chocolatey repository.

  1. View the Git remotes to verify it’s connected to GitHub.
Press + to interact
git remote -v
  1. Push the changes to GitHub.
Press + to interact
git push -u origin master

Replace a role with a Galaxy role

Next, you will copy the role files and tasks; then move the non-galaxy role out of the roles directory.

  1. Change into the ansible directory.
Press + to interact
cd ../ansible
  1. Create a new directory to store the non-Galaxy Chocolatey role.
Press + to interact
mkdir -p nonGalaxy/chocolatey
  1. Move the non-Galaxy Chocolatey role.
Press + to interact
mv roles/chocolatey/* nonGalaxy/chocolatey
  1. Remove the roles/chocolatey directory.
Press + to interact
rmdir roles/chocolatey
  1. Copy the tasks/main.yml to the Galaxy role.
Press + to interact
cp nonGalaxy/chocolatey/tasks/main.yml ../chocolatey/tasks/main.yml
  1. Copy the files contents to the Galaxy role.
Press + to interact
cp nonGalaxy/chocolatey/files/* ../chocolatey/files/
  1. Push the changes to GitHub.
Press + to interact
#change to the galaxy role directory  
cd ../chocolatey
git add .
# Configure user.email
# Replace <Your email> with the actual email
git config --global user.email "<YourEmail>"
# Configure user.name
# Replace <Your name> with the actual name
git config --global user.name "<YourName>"
git commit -m 'added role logic and files' 
git push
  1. Run the site.yml playbook.
Press + to interact
ansible-playbook site.yml -i hosts --ask-vault-pass

Missing role
The role chocolatey was not found.

Using Ansible Galaxy roles

The roles directory is empty. Without the non-galaxy role living in that directory, Ansible won’t load the role. You use a requirements.yml file to deal with that.

A requirements.yml is a file that lists the role dependencies our Ansible codebase has. Using this file, you can download the required roles before running the playbooks that need them.

Let’s create a requirements.yml file in the roles directory.

Press + to interact
- src: https://github.com/Duffney/chocolatey.git 
  scm: git
  version: "master"
  name: chocolatey

Let’s look at the parameters in the file above:

  • src: set to the HTTPS URL of the GitHub repository as the Galaxy role is stored in a Git repository.

  • scm: set to git because that’s the type of source control used.

  • version: defines which code to pull down. Set to master to pull down the code from the master branch.

  • name: specifies the name of the role, chocolatey.

With the requirements defined, install the Galaxy role. To do so, you will use the ansible-galaxy command.

ansible-galaxy install -r roles/requirements.yml
Install Ansible Galaxy role

Run the site.yml playbook.

Press + to interact
ansible-playbook site.yml -i hosts --ask-vault-pass
# skip chocolateyExtension tasks
ansible-playbook site.yml -i hosts --skip-tags chocolateyExtension --ask-vault-pass

Version with Git tags

At some point, you’ll want more control over the use of the role’s version to avoid pulling untested changes. You can gain that level of control by leveraging Git tags.

Within GitHub, you can create releases for your code and tag them. You can use those tags within the requirements.yml to version-lock the role to that tag.

Create a release

  1. Log into GitHub.
  2. Open the Chocolatey repository.
  3. On the right-hand side under Release, click Create a new release.
  4. Input a tag, release title, and description.
  1. Update the requirements.yml to use a tag.
    • Change the version to v1.0 to reference the release tag instead of the master branch.
Press + to interact
- src: https://github.com/Duffney/chocolatey.git 
  scm: git
  version: "v1.0"
  name: chocolatey
  1. Re-install the Galaxy role.
Press + to interact
ansible-galaxy install -r roles/requirements.yml -f
  1. Run the site.yml playbook. Update the <Password> with the password created using the ansible-vault command in the group_vars/linux.yml and group_vars/windows.yml files using the nano editor.
Press + to interact
ansible-playbook site.yml -i hosts --ask-vault-pass
# skip chocolateyExtension tasks
ansible-playbook site.yml -i hosts --skip-tags chocolateyExtension --ask-vault-pass

Practice all the commands in the terminal. We have provided a summarized view of the commands below:

Press + to interact
# initialize the role directory
ansible-galaxy init chocolatey --offline
# View the directory structure
tree
# Change into chocolatey directory
cd chocolatey
# Connect Ansible Galaxy Role repository
git init
# Configure user.email
# Replace <Your email> with the actual email
git config --global user.email "<YourEmail>"
# Configure user.name
# Replace <Your name> with the actual name
git config --global user.name "<YourName>"
git add .
git commit -m "init commit"
# Replace <remoteRepositoryURL> with the 
# HTTPS URL of GitHub chocolatey repository.
git remote add origin <remoteRepositoryURL>
# Verify Connectivity
git remote -v
# Push the changes
git push -u origin master
# End - Connect Ansible Galaxy Role repository
# Change to the ansible directory
cd ../ansible
# Create nonGalaxy/chocolatey directory
mkdir -p nonGalaxy/chocolatey
# Move the contents of roles/chocolatey to nonGalaxy/chocolatey
mv roles/chocolatey/* nonGalaxy/chocolatey
# Remove the roles/chocolatey directory
rm -rf roles/chocolatey
# Copy the tasks
cp nonGalaxy/chocolatey/tasks/main.yml ../chocolatey/tasks/main.yml
# Copy the files
cp nonGalaxy/chocolatey/files/* ../chocolatey/files/
#change to the galaxy role directory  
cd ../chocolatey
git add .
git commit -m 'added role logic and files' 
git push
# Change directory
cd ../ansible
# Execute the playbook
ansible-playbook site.yml -i hosts --ask-vault-pass
# Create requirements.yml
touch roles/requirements.yml
# Add Content
nano roles/requirements.yml
# Contents
# - src: https://github.com/Duffney/chocolatey.git 
#  scm: git
#  version: "master"
#  name: chocolatey
# Save Changes
Press Ctrl + o
Press enter
# Install Role
ansible-galaxy install -r roles/requirements.yml
# Execute the playbook
ansible-playbook site.yml -i hosts --ask-vault-pass
# skip chocolateyExtension tasks
ansible-playbook site.yml -i hosts --skip-tags chocolateyExtension --ask-vault-pass
# Update Content
nano roles/requirements.yml
# Updated Contents
# - src: https://github.com/Duffney/chocolatey.git 
#  scm: git
#  version: "v1.0"
#  name: chocolatey
# Save Changes
Press Ctrl + o
Press enter
# Re-Install Role
ansible-galaxy install -r roles/requirements.yml -f
# Execute the playbook
ansible-playbook site.yml -i hosts --ask-vault-pass
# skip chocolateyExtension tasks
ansible-playbook site.yml -i hosts --skip-tags chocolateyExtension --ask-vault-pass
Terminal 1
Terminal
Loading...

Troubleshooting tips

Missing role
If you receive the error chocolatey was NOT installed successfully: could not find/use git, you need to install git. apt-get install git

In this lesson, you decoupled your codebase from the Ansible Galaxy roles in a different repository.

Get hands-on with 1300+ tech skills courses.