Advanced Ansible: Collections+
==============================

Published  : 25 April 2025
Reading    : 3 min
Tags       : Ansible
URL        : https://ctrl-find.nl/posts/ansible_collections/
Plain text : https://ctrl-find.nl/posts/ansible_collections/index.txt

------------------------------------------------------------


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:
```bash
ansible-galaxy collection init <namespace name>.<collection name>

# EXAMPLE:
ansible-galaxy collection init local.random
```
This will build the scaffold collection.

```bash
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](https://github.com/ansible-collections/community.docker/tree/main) and the [Ansible Docs](https://docs.ansible.com/ansible/latest/collections/community/docker/index.html#plugins-in-community-docker) 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](https://ctrl-find.nl/posts/2025/ansible/custom_module/).\
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;
```bash
---
- 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
```bash
---
- 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.





------------------------------------------------------------
NAVIGATION

  [index]  https://ctrl-find.nl/posts/index.txt

  [<< prev] Advanced Ansible: Custom modules
            https://ctrl-find.nl/posts/ansible_custom_modules/index.txt


  [next >>] The dangers of using a random KMS license server
            https://ctrl-find.nl/posts/internet_kms_service/index.txt

------------------------------------------------------------

CTRL-Find — Debugging all systems
https://ctrl-find.nl/