Working with Collections

1. Understanding Collections

Ansible Collections are a distribution format for Ansible content that includes playbooks, roles, modules, and other components. They allow you to organize and share Ansible content in a structured way.

2. Installing Collections

Collections can be installed using the ansible-galaxy command-line tool.

ansible-galaxy collection install community.docker

3. Using Collection Modules

After installing a collection, you can use its modules in your playbooks by specifying the full namespace and module name.

- name: Create a Docker container
  community.docker.docker_container:
    name: web_server
    image: nginx
    ports:
      - "80:80"

4. Setting Collection Path

You can configure where Ansible looks for collections using the ANSIBLE_COLLECTIONS_PATH environment variable or in ansible.cfg.

[defaults]
collections_paths = /opt/ansible/collections:/home/user/my_collections

5. Creating Custom Collections

To create a custom collection, you must follow the directory structure and metadata format.

my_collection/
├── meta/
│   └── main.yml
├── roles/
│   └── my_role/
│       ├── tasks/
│       │   └── main.yml
│       └── handlers/
│           └── main.yml
└── modules/
    └── my_module.py

6. Defining Collection Dependencies

Collection dependencies are defined in the meta/main.yml file to ensure that required collections are installed before using the current one.

---
requires_ansible: ">=2.15"
collections:
  - ansible.posix
  - community.docker

7. Using Collections in Playbooks

To use collections in playbooks, you must reference them with their full namespace and module name.

- name: Manage Docker containers
  hosts: localhost
  tasks:
    - name: Start a container
      community.docker.docker_container:
        name: web_server
        image: nginx
        ports:
          - "80:80"

8. Listing Collections

You can list installed collections using the ansible-galaxy collection list command.

ansible-ggaxy collection list community.docker

9. Upgrading Collections

To upgrade collections, use the ansible-galaxy collection install command with the --upgrade flag.

ansible-galaxy collection install community.docker --upgrade

10. Verifying Collections

You can verify the integrity and correctness of collections using ansible-galaxy collection verify.

ansible-galaxy collection verify community.docker

11. Building Collections

To build a collection into a distributable format, use the ansible-galaxy collection build command.

ansible-galaxy collection build

12. Publishing Collections

To publish a collection to Ansible Galaxy, you must first build it and then upload it using the ansible-galaxy collection publish command.

ansible-galaxy collection publish community.docker-2.6.0.tar.gz