Collections

FQCN, namespaces, and the modern content distribution model.

7 min readAnsible AutomationProvision

What Are Collections?

Collections are the modern distribution format for Ansible content. A collection packages modules, plugins, roles, and playbooks into a single unit. They replaced Galaxy roles as the primary way to share and consume Ansible automation.

Fully Qualified Collection Names

Every collection item has a fully qualified collection name (FQCN) in the format namespace.collection.name. Using FQCNs is best practice — it prevents naming conflicts and makes dependencies explicit.

FQCN usage


# Short name (ambiguous)
- name: Install nginx
  apt:
    name: nginx

# FQCN (explicit)
- name: Install nginx
  ansible.builtin.apt:
    name: nginx

# Community collection
- name: Create Docker container
  community.docker.docker_container:
    name: web
    image: nginx
    state: started

ansible.builtin contains all modules included with Ansible core. Community collections require separate installation.

Installing Collections

Install collections


# Install a single collection
ansible-galaxy collection install community.docker

# Install a specific version
ansible-galaxy collection install community.docker:5.0.0

# Install from requirements
ansible-galaxy collection install -r requirements.yml

# Install to project-local directory
ansible-galaxy collection install -p collections/ community.docker

Collections install to ~/.ansible/collections by default. Project-local installs keep dependencies with your code.

Collection Structure

Collection directory layout


collections/ansible_collections/namespace/collection/
  galaxy.yml           # Collection metadata
  plugins/
    modules/           # Custom modules
    lookup/            # Lookup plugins
    filter/            # Filter plugins
    callback/          # Callback plugins
  roles/
    my_role/           # Bundled roles
  playbooks/
    deploy.yml         # Reusable playbooks
  docs/                # Documentation
  tests/               # Tests

Collections follow a standardized structure. Galaxy metadata in galaxy.yml defines the collection name, version, and dependencies.

Collections unify content

Before collections, Ansible content was split across Galaxy roles, plugins, and modules. Collections bundle everything into one installable unit. This is the modern standard.

Essential Collections

Collection	Purpose
ansible.builtin	Core modules included with Ansible
community.general	General-purpose modules and plugins
community.docker	Docker and Podman management
amazon.aws	AWS resource management
azure.azcollection	Azure resource management
community.postgresql	PostgreSQL management
ansible.posix	POSIX system administration

FQCN is best practice

Always use FQCNs in production code. Short names work but can collide when different collections define modules with the same name. FQCNs are unambiguous.

Mark this lesson complete to store local progress and unlock a cleaner resume path the next time you visit.

Stage 4 · Provision

Roles & Collections