Advanced Ansible Part 2: Collections+

A set of modules together is a called a collection. Like ansible.builtin. I’ve used collections in the past to use the modules it provided but never really created them. In this post I want to take you on my journery to learn more about these collections.

To create a collection we need to do the following:

ansible-galaxy collection init <namespace name>.<collection name>

# EXAMPLE:
ansible-galaxy collection init local.random

This will build the scaffold collection.

sebas@pop-os:~/Desktop$ tree local/
local/
└── random
    ├── galaxy.yml		# Is a metadata file where information about the collection is written
    ├── plugins			# Place where custom code will be placed and used for roles in the collection.
    │   └── README.md
    └── README.md		# Collection documentation place.

The README.md files gives some direction which information can be used or created in that folder. With the information from the README’s and a side by side comparision from ansible-collection and the Ansible Docs we can see how the structure is build.

Adding our own custom module

Create a folder called modules in the plugins folder, in this folder we place the python file we’ve created in advanced part 1.
Lets create a new folder in the root of random, called roles. when we go into roles we can generate a new role with ansible-galaxy init <name role> .

Place this code snippet in the main.yml tasks;

---
- name: Test that my module works
  pokemon_info:						# Name of the file we've added to modules folder
    type: pokemon					# python var
    name: "{{ poke_name }}"			# Variable which will be used in the playbook
  register: result

- debug: var=result

Create a playbook outside this folder somewhere different then the collection; Place the following code snippet inside the playbook

---
- name: talk to Role 					# Name playbook
  hosts: localhost						# Which hosts to connect to
  roles:								
    - role: local.random.pokemon_info	# local.random is the collection name with pokemon_info as module
      vars:
        poke_name: "charmander"			# Variable which will be used inside the module.

We cant just run it now, sadly our Ansible doesnt know anything about this collection. To make our Ansible know this collection we must do the following:

• Go into the collection, to the folder with galaxy.yml in it.
• Create a tar file with ansible-galaxy collection build, this will produce a collection-name-version.tgz file.
• Install the tgz file with ansible-galaxy collection install <collection-name-version>.tar.gz.

When installed we can do ansible-playbook <playbook-name>.yml, when changing up the collection with new info or added functionality and you want to test locally we need to do the following;

• rm -rf ~/.ansible This removes everything in the .ansible folder, there is probably a better way but not found it yet.
• Bump the version in the galaxy.yml in the collection.
• Create a new tar file with the previous build command and install the new version.

Now the new functionality can be used in the playbooks.

Conclusion

The majority of the collection was fun to do and create but i’ve struggled much when I changed the collection. I couldn’t see the changes but after some web browsing I found a helpfull comment that helped me get my newer version up and running.

• Tags:
• Ansible
• Feature