Menu
Article Ansible

Ansible: Collections & FQCN

mow

mow

• 2 min read

Hey!

In our Ansible 101 guide, we learned about roles. But there is another thing in Ansible called collections. In this blog post I want to explain what collections are used for and what an FQCN (Fully Qualified Collection Name) is.

So what is a collection? Basically, it is a distribution format for shipping packaged Ansible content. It can contain:

  • Modules
  • Plugins
  • Roles
  • Playbooks
  • Documentation
  • Dependencies (information of required other roles, collections...)

FQCN (Fully Qualified Collection Name)

You may have already noticed the way that Ansible modules are called, such as

- name: install apache2
  ansible.builtin.apt: # <-- FQCN
    name: apache2
    state: present

This is the FQCN for the apt module. The collection name is "ansible.builtin" and we are using the "user" module contained in that collection. The "builtin" is the default ansible internal collection containing the ansible "core".

Community collections

The cool thing about collections is that they can be built and shared by the Ansible community. There are many collections out there. For example the community.general collection:

Community.General — Ansible Community Documentation

You will find really a lot of collections on ansible galaxy or GitHub:

Ansible Galaxy

Collection Structure

Like in a role (feel free to check out my blog post about roles here) a collection is sturctured by directories. The basic structure looks like this (source: Ansible docs):

collection/
├── docs/
├── galaxy.yml
├── meta/
│   └── runtime.yml
├── plugins/
│   ├── modules/
│   │   └── module1.py
│   ├── inventory/
│   └── .../
├── README.md
├── roles/
│   ├── role1/
│   ├── role2/
│   └── .../
├── playbooks/
│   ├── files/
│   ├── vars/
│   ├── templates/
│   └── tasks/
└── tests/

Example: Call the terraform module from community collection

Let's say we want to use ansible to manage some terraform deployments. There is a terraform module in the community.general collection. So first we need to install that collection using ansible galaxy:

ansible-galaxy collection install community.general

Then we can start using the installed collection in our playbooks (source: ansible docs):

- hosts: my_tf_host
  tasks:
    - name: Basic deploy of a service
      community.general.terraform:
        project_path: '{{ project_dir }}'
        state: present

This is a very simple example, but it should show you how you can use collections. You can also create your own collections using the structure shown above!
That's it for now. The best way to learn this stuff is to try it out! Feedback is always appreciated!

Mow

Share