Ansible Collections Design Prompt

You are a senior Ansible engineer who has packaged collections for distribution — namespacing roles, modules, and plugins for sharing.

I will provide:
- The collection purpose
- Current state (using community collections or building own)
- Goal (consume / build / migrate)

Your job:

1. **Collections basics**:
   - Distribution unit for Ansible content
   - Contains roles, modules, plugins, playbooks
   - Namespaced: `namespace.collection_name`
   - Installed via ansible-galaxy collection
2. **FQCN (Fully Qualified Collection Name)**:
   - `namespace.collection.module`
   - E.g., `amazon.aws.ec2_instance`
   - Required since Ansible 2.10
   - `ansible.builtin` for built-in modules
3. **For requirements.yml**:
   - List collections + versions
   - `ansible-galaxy collection install -r requirements.yml`
   - Lock versions for reproducibility
4. **For collection structure**:
   ```
   mycollection/
   ├── galaxy.yml
   ├── README.md
   ├── plugins/
   │   ├── modules/
   │   ├── filter/
   │   └── lookup/
   ├── roles/
   │   └── myrole/
   ├── playbooks/
   ├── docs/
   └── tests/
   ```
5. **For building**:
   - `ansible-galaxy collection build`
   - Tarball output
   - Test before publish
6. **For publishing**:
   - Galaxy.ansible.com (public)
   - Private repo (Automation Hub, simple HTTP)
7. **For installing private**:
   - `ansible-galaxy collection install <url>`
   - Or from tarball
8. **For version constraint**:
   - `>=1.0.0,<2.0.0`
   - Semver

Mark DESTRUCTIVE: collection upgrade with breaking changes, private collection version conflicts, removing collection in production.

---

Collection purpose: [DESCRIBE]
Current state: [DESCRIBE]

Why this prompt works

Collections are modern distribution. This prompt walks them.

How to use it

1. Use FQCN.
2. Pin versions in requirements.
3. Test collections before commit.
4. Document in galaxy.yml.

Useful commands

# Install
ansible-galaxy collection install community.general

# From requirements
ansible-galaxy collection install -r requirements.yml

# List installed
ansible-galaxy collection list

# Build own
cd mycollection/
ansible-galaxy collection build

# Install local
ansible-galaxy collection install mycollection-1.0.0.tar.gz

# Publish
ansible-galaxy collection publish mycollection-1.0.0.tar.gz --api-key <key>

Patterns

requirements.yml

collections:
- name: community.general
  version: '>=8.0.0,<9.0.0'
- name: amazon.aws
  version: '>=7.0.0'
- name: kubernetes.core
  version: '>=3.0.0'
- name: my_org.my_collection
  source: https://gitlab.example.com/api/v4/projects/123/packages/generic/my_collection
  type: url

roles:
- name: geerlingguy.docker
  version: 7.0.0

ansible-galaxy install -r requirements.yml

Playbook with FQCN

- hosts: web
  tasks:
  - name: Install Docker
    ansible.builtin.package:           # built-in
      name: docker.io
      state: present

  - name: Create container
    community.docker.docker_container:
      name: web
      image: nginx:latest
      state: started

  - name: Configure cloud LB
    amazon.aws.elb_application_lb:
      name: web-alb
      state: present

Custom collection structure

my_org/my_collection/
├── galaxy.yml
├── README.md
├── LICENSE
├── plugins/
│   ├── modules/
│   │   └── my_module.py
│   ├── filter/
│   │   └── my_filter.py
│   └── lookup/
│       └── my_lookup.py
├── roles/
│   ├── role1/
│   │   ├── defaults/main.yml
│   │   └── tasks/main.yml
│   └── role2/
├── playbooks/
│   └── deploy.yml
├── meta/
│   └── runtime.yml
└── tests/
    └── unit/

galaxy.yml

namespace: my_org
name: my_collection
version: 1.2.3
readme: README.md
authors:
- Platform Team <platform@example.com>
description: Internal automation collection
license: ['Apache-2.0']
tags:
- automation
- internal
repository: https://gitlab.example.com/my_org/my_collection
issues: https://gitlab.example.com/my_org/my_collection/-/issues
dependencies:
  community.general: '>=8.0.0'
build_ignore:
- '*.tar.gz'
- '.git*'

Usage of custom collection’s role

- hosts: web
  roles:
  - role: my_org.my_collection.role1

Common findings this catches

• FQCN missing → deprecation warning → migrate.
• Version conflict → pin compatible.
• Module not found → check ansible-galaxy collection list.
• Private install fails → API token auth.
• Build fails → galaxy.yml syntax.
• Module from different collection same name → use FQCN.
• Old playbook with with_items → modern collection style.

When to escalate

• Mass FQCN migration — staged.
• Collection publish strategy — design.
• Private hub — engineering.