Project

General

Profile

Wiki » Ansible »

👩‍💻 Contributor Guide: Adding a New Ansible Inventory

📖 Purpose

This guide explains how to add a new Ansible inventory to the repository and ensure its documentation is automatically generated and indexed by the inventory documentation workflow.

The system treats inventories as source-of-truth artifacts. Documentation is derived entirely from inventory files and updated automatically by CI.

🛠 Steps to Add a New Inventory

1. Create the inventory folder

Each inventory lives in its own directory under inventory/.

Create a new folder using a short, descriptive name:

inventory/myservice/

Naming guidelines:

  • Lowercase
  • Hyphenated if needed
  • Represents a logical service, role, or domain
  • Avoid environment-specific names unless required

2. Create inventory.ini

Inside the new folder, create an inventory.ini file:

inventory/myservice/inventory.ini

This file must use standard INI-style Ansible inventory syntax.

Example:

[myservice]
myservice-0 ansible_host=10.0.10.50

[linux:children]
myservice

This file is the only required input for documentation generation.

3. Define hosts correctly

Hosts may include inline variables:

myservice-0 vms_proxmox_node=pve-1 ansible_host=10.0.10.50

Guidelines:

  • The first token on the line must be the hostname
  • All variables must be key=value pairs
  • Quoted values and JSON-like strings are supported

✅ These are treated as one host, not multiple entries.

4. Use groups intentionally

Groups help drive both playbook targeting and documentation clarity.

Supported group types:

[group]
[group:vars]
[group:children]

Example:

[db]
pg-0
pg-1

[db:vars]
postgres_port=5432

[services:children]
db

All group relationships are reflected in generated documentation.

⚠️ Duplicate Host Awareness

The documentation generator tracks all hosts across all inventories.

If a host is defined in more than one inventory:

  • A warning is logged
  • The host appears once in the Global Host Index
  • All owning inventories are listed

📌 Note — Duplicate Hosts

Defining the same host in multiple inventories can lead to:

  • Conflicting variables
  • Unexpected group membership
  • Non-deterministic playbook behavior

Contributors should strongly prefer one authoritative inventory per host and refactor shared concerns into groups or variables instead.

If CI is run in --strict mode, duplicate hosts will fail the workflow.

5. Commit your changes

Once your inventory is added:

git add inventory/myservice/
git commit -m "feat(inventory): add myservice inventory"
git push

No documentation files should be edited manually.

⚙️ What Happens Next (Automation)

On push or pull request, the Generate Inventory Docs GitHub Action runs automatically.

It executes:

scripts/generate_inventory_docs.py

The script will:

✅ Parse the new inventory
✅ Generate per-inventory documentation at:

docs/inventory/myservice.md

✅ Update the global inventory index at:

docs/inventory/README.md
inventory/README.md

✅ Highlight multi-host inventories with 📌
✅ Detect and warn about duplicate hosts

All documentation updates are committed automatically.

📂 Example

After adding:

inventory/redis/inventory.ini

With:

[redis]
redis-0 vms_proxmox_node=pve-2

[services:children]
redis

The workflow generates:

  • docs/inventory/redis.md
  • Updated docs/inventory/README.md
  • Updated inventory/README.md

No manual documentation required.

✅ Contributor Expectations

  • Use valid INI syntax

  • Place exactly one inventory per folder

  • Name inventories clearly and consistently

  • Avoid duplicate host definitions across inventories

  • Review PR diffs — you should see:

    • New or updated files under docs/inventory/
    • Updated inventory indexes

🧭 Summary

Adding a new inventory is straightforward:

  1. Create a folder under inventory/
  2. Add inventory.ini
  3. Define hosts and groups cleanly
  4. Commit and push

The automation handles everything else — parsing, documentation, indexing, and validation.