🗂️Module 06 — Collections & Content Structure

- Collection mycompany.platform was created successfully

mycompany
mycompany/platform
mycompany/platform/README.md
mycompany/platform/docs
mycompany/platform/galaxy.yml
mycompany/platform/meta
mycompany/platform/meta/runtime.yml
mycompany/platform/plugins
mycompany/platform/plugins/README.md
mycompany/platform/roles

namespace: mycompany
name: platform
version: 1.0.0
readme: README.md
authors:
  - your name <[email protected]>
description: your collection description
dependencies: {}
license_file: ''
tags: []
repository: http://example.com/repository

Note how little you get — and note the nesting. The scaffolder creates mycompany/platform/, a two-level directory, because that is exactly how collections are stored on disk: <namespace>/<name>/. Every installed collection lives under ansible_collections/<namespace>/<name>/.

Three things to fix immediately:

1. version: 1.0.0 — the scaffolder's optimism. Start at 0.1.0 while the interface is still moving, so you are free to make breaking changes without burning major versions.
2. license_file: '' — empty and invalid. Galaxy rejects a build without a license. Set license_file: LICENSE and add the file, or use the license: key with an SPDX identifier.
3. No plugins/modules/ yet — create the subdirectories you actually need. An empty plugins/ tree is noise.

Also open meta/runtime.yml — it contains only requires_ansible: '>=2.15.0'. Set that honestly to the lowest version you have actually tested against, because consumers get a clear failure instead of a mysterious one.

Modules, plugins of every kind (filter, lookup, inventory, callback, connection, action, test), module_utils, and playbooks — plus roles.

A role is limited to tasks, handlers, templates, files, defaults and vars. A collection is the superset, and it is versioned with declared dependencies on other collections.

The manifest: namespace, name, version (semantic versioning, enforced), readme, authors, description, license or license_file, tags, dependencies on other collections with version ranges, repository and documentation URLs, and build_ignore for files to exclude from the artifact.

It is the collection's identity and its dependency contract.

Three things. requires_ansible declares the minimum ansible-core version, so an old control node fails with a clear message. action_groups lets consumers apply module_defaults to a whole group of modules at once. And plugin_routing handles renames and removals — a redirect keeps an old FQCN working silently, a tombstone fails with guidance.

plugin_routing is the same mechanism the Ansible project used during the 2.10 split, which is why bare yum: still resolves today.

Because consumers pin ranges such as ">=1.4.0,<2.0.0", and that pin only protects them if you honour the contract: MAJOR for breaking changes, MINOR for backwards-compatible additions, PATCH for fixes.

Galaxy enforces the format but cannot enforce the meaning — shipping a breaking change as a MINOR bump silently breaks every consumer who pinned correctly, which is the fastest way to lose a team's trust in your collection.

Created collection for mycompany.platform at /tmp/dist/mycompany-platform-0.1.0.tar.gz

Installing 'mycompany.platform:0.1.0' to '/home/zaeem/lab/collections/ansible_collections/mycompany/platform'
mycompany.platform:0.1.0 was installed successfully

# /home/zaeem/lab/collections/ansible_collections
Collection          Version
------------------- -------
mycompany.platform  0.1.0

Look at the install path. The collection landed at collections/ansible_collections/mycompany/platform/ — the ansible_collections/<namespace>/<name>/ structure is fixed and not negotiable. That is why collections_path points at the directory containing ansible_collections, not at ansible_collections itself, which is a common off-by-one when configuring it by hand.

Now the role is addressed by FQCN — mycompany.platform.webserver rather than webserver. It no longer needs to sit in ./roles/, it is versioned, and ansible-galaxy collection list reports exactly which version is in use.

Try removing --force and re-running the install. Ansible refuses to overwrite an existing collection of the same version — which is correct behaviour, and the reason you bump the version during development rather than rebuilding the same one repeatedly.

ansible-galaxy collection init namespace.name to scaffold, add roles and plugins, set the version in galaxy.yml, then ansible-galaxy collection build to produce a tarball.

Distribution: publish to public Galaxy, upload to a Private Automation Hub or Artifactory for internal use, or simply install from a git tag via requirements.yml, which is often enough for a small team.

The step worth mentioning: install the built tarball locally into ./collections and test against that, not against your source tree — it is the only way to catch packaging mistakes such as a file excluded by build_ignore.

Into the project — collections_path = ./collections in ansible.cfg, with the directory gitignored and rebuilt by CI from a pinned requirements.yml.

That makes the project self-contained and reproducible, rather than depending on whatever versions happen to be in a particular developer's ~/.ansible/collections.

The physical layout under it is fixed: collections/ansible_collections/<namespace>/<name>/.

It adds collections to the search path for unqualified module and role names in a play.

Generally you should not use it — it reintroduces the ambiguity FQCNs exist to remove, since two listed collections defining the same name resolve by list order. ansible-lint flags short names. Use FQCNs, and reach for the keyword only when maintaining older code that already depends on it.

TASK [ansible.builtin.debug] ***************************************
ok: [stg01] => {
    "msg": "stg01 -> STAGING with 1 replicas"
}

TASK [ansible.builtin.debug] ***************************************
ok: [web01] => {
    "msg": "web01 -> PRODUCTION with 6 replicas"
}

{
    "app_replicas": 1,
    "env_name": "STAGING"
}

Notice what you did not have to do. No -e env=staging, no conditional in the playbook, no when: env == 'prod'. The same playbook produced different values purely because -i pointed at a different directory, and Ansible loaded the group_vars sitting beside that inventory automatically.

That automatic adjacency is the whole mechanism, and it is why the directory layout is a correctness concern rather than a tidiness one. Move group_vars/ to the repository root and both commands print the same values — the environments silently merge, and a staging change lands in production.

The safety property worth stating in an interview: with this layout, running against the wrong environment requires typing the wrong path, which is visible in shell history and in CI job definitions. With a shared root group_vars, it requires forgetting a flag — invisible and far easier to do.

A directory per environment under inventories/ — production/, staging/ — each containing its own hosts.yml and its own group_vars/ and host_vars/. Then -i inventories/production loads the inventory and its adjacent variables together.

The critical rule: group_vars/ goes inside each inventory directory, never at the repository root. At the root, all environments share variables and a staging edit reaches production.

Roles, playbooks and collections stay shared; only inventory and variables are per-environment.

Commit: ansible.cfg, requirements.yml with pinned versions, inventories, group_vars (with secrets Vault-encrypted), playbooks, your own roles, lint config.

Ignore: collections/ and galaxy_roles/ — build artifacts rebuilt from requirements.yml — plus vault password files, private keys, *.retry, and any local override config.

The principle: commit the declaration, ignore what it installs. Committing downloaded content bloats the repo and hides dependency changes in enormous diffs.

It is a real trade-off and worth showing you have thought about it. Defaulting to production means a forgotten -i targets production. Defaulting to staging makes a forgotten flag harmless. Setting no default forces every command to be explicit and fails otherwise.

Many teams choose staging or no default for exactly that reason. The genuinely wrong answer is defaulting to production without the team being aware of it.

ansible-platform/
  ansible.cfg
  requirements.yml
  .gitignore
  playbooks/site.yml
  inventories/
    production/
      hosts.yml
      group_vars/all.yml         app_replicas: 6
    staging/
      hosts.yml
      group_vars/all.yml         app_replicas: 1
  collections/                   <- gitignored

# mycompany/platform/galaxy.yml
---
namespace: mycompany
name: platform
version: 0.1.0                        # requirement 2 - start low while unstable
readme: README.md
authors: ["Zaeem Mazhar <[email protected]>"]
description: Internal platform automation
license_file: LICENSE                 # requirement 2 - build fails without it
tags: [infrastructure, linux]
dependencies:
  ansible.posix: ">=1.5.0,<2.0.0"
repository: https://git.internal/ansible/platform
build_ignore:
  - .git
  - molecule

# mycompany/platform/meta/runtime.yml
---
requires_ansible: ">=2.15.0"          # requirement 2

# requirements.yml  -- requirement 5
---
collections:
  - name: https://git.internal/ansible/platform.git
    type: git
    version: v0.1.0
  - name: ansible.posix
    version: "1.5.4"
  - name: community.general
    version: "8.3.0"

# ansible.cfg
[defaults]
collections_path  = ./collections
roles_path        = ./roles
host_key_checking = True
stdout_callback   = yaml
# deliberately NO default inventory - forces -i to be explicit

# playbooks/site.yml  -- requirement 4: no conditional anywhere
---
- name: Configure the web tier
  hosts: web
  become: true
  roles:
    - mycompany.platform.webserver
  post_tasks:
    - name: Show what this environment resolved to
      ansible.builtin.debug:
        msg: "{{ inventory_hostname }} runs {{ app_replicas }} replicas"

# .gitignore  -- requirement 6
collections/
galaxy_roles/
*.retry
*.tar.gz
.vault_pass*
*.pem

The five decisions that matter:

1. group_vars/ under each inventory directory — requirement 3. This is the entire mechanism; at the root, both environments would share one file.
2. No conditional in the playbook — requirement 4. app_replicas differs purely because -i points elsewhere. If you found yourself writing when: env == 'prod', the layout is wrong.
3. version: 0.1.0, not 1.0.0 — below 1.0.0 you are free to break the interface while it settles. Starting at 1.0.0 means every subsequent change is either a lie or a major bump.
4. license_file set and the file present — ansible-galaxy collection build fails without it, and the scaffolder leaves it empty.
5. No default inventory in ansible.cfg — a forgotten -i fails loudly instead of silently choosing an environment.

Verify all seven:

cd mycompany/platform && ansible-galaxy collection build --output-path /tmp/dist --force && cd -
ansible-galaxy collection install /tmp/dist/mycompany-platform-0.1.0.tar.gz -p ./collections --force
ansible-galaxy collection list

ansible-playbook -i inventories/staging    playbooks/site.yml   # 1 replica
ansible-playbook -i inventories/production playbooks/site.yml   # 6 replicas
ansible-playbook playbooks/site.yml                             # FAILS - no inventory
git status --short                                              # collections/ absent

Modules, module_utils, and plugins of every kind — filter, lookup, inventory, callback, connection, action, test — plus playbooks and roles. A role is limited to tasks, handlers, templates, files, defaults and vars.

plugins/modules/create_tenant.py → mycompany.platform.create_tenant. roles/webserver/ → mycompany.platform.webserver. plugins/filter/ entries → mycompany.platform.<filter_name>.

The namespace and name come from galaxy.yml, and on disk everything lives under ansible_collections/<namespace>/<name>/.

Renaming and removing content without breaking consumers. A redirect silently maps an old FQCN to a new one; a tombstone fails with a message naming the replacement.

It is the mechanism the Ansible project used during the 2.10 split, which is why bare yum: still resolves.

Because -i inventories/production loads that directory's inventory and its adjacent group_vars/host_vars automatically. That is what isolates environments.

At the repository root, every environment shares one set of variables, so a staging edit reaches production and the playbook needs conditionals to compensate — which is the smell that tells you the layout is wrong.

Commit ansible.cfg, a pinned requirements.yml, inventories, group_vars (secrets Vault-encrypted), playbooks, your own roles and lint config.

Ignore collections/, galaxy_roles/, vault password files, private keys, *.retry and build artifacts.

The principle: commit the declaration, ignore what it installs.

Below 1.0.0 the interface is understood to be unstable, so you can make breaking changes freely while it settles. Starting at 1.0.0 means every subsequent breaking change requires a major bump — or, more commonly, gets shipped dishonestly as a minor one.

Because the build applies build_ignore and produces exactly what a consumer receives. Testing against source hides packaging bugs — a file you forgot to include, or one you accidentally excluded — which then surface only after publishing.

Generally no. It adds a search path for unqualified names, reintroducing the ambiguity FQCNs exist to remove — two listed collections defining the same name resolve by list order. ansible-lint flags short names. Use it only when maintaining code that already relies on it.

ansible-core itself, the Python version, and every Python library a module needs — boto3, netaddr, kubernetes. Those are control-node dependencies that requirements.yml cannot express.

That gap is exactly what Execution Environments close.

A container image bundling ansible-core, collections and Python dependencies into one immutable, reproducible runtime that behaves identically on a laptop, in CI and in AWX.

ansible-builder builds it from execution-environment.yml, ansible-runner executes Ansible inside it, and ansible-navigator is the CLI that runs playbooks against it.

Behaviour verified against the current official collections documentation and developing collections guide.

Question selection cross-referenced against publicly published 2026 Ansible interview question sets:

• Spacelift — 50+ Top Ansible Interview Questions & Answers for 2026
• GeeksforGeeks — Top 50+ Ansible Interview Questions and Answers
• Vinsys — Top 30 Ansible Interview Questions and Answers 2026
• K21 Academy — Ansible Interview Questions & Answers 2026
• Hirist — Top 25+ Ansible Interview Questions and Answers 2026

Answers were rewritten and deepened rather than reproduced — published versions are usually correct but shallow, and the added operational detail is what differentiates a candidate in the room.