docker/docs/infrastructure-inventory.md

Infrastructure Inventory Model

This repository treats infrastructure inventory as first-class documentation.

Intent

The goal is not only deployment configuration, but also a maintainable map of:

• what hosts/VMs exist,
• how they are identified,
• what selected runtime objects are mirrored into Terraform,
• what outputs can be consumed by docs and future tooling.

Current inventory sources

1) Terraform Proxmox layer

infrastructure/terraform/proxmox/ contains imported/reconciled VM resources and local metadata for physical hosts.

This is currently the most structured host/VM inventory in the repo.

2) Terraform Docker layer

infrastructure/terraform/docker/ contains selective Docker container resources used as documentation-oriented mirrors.

These resources should match existing running containers, not redefine runtime composition strategy.

3) Ansible bootstrap layer

infrastructure/ansible/ provides an emerging inventory/configuration scaffold for hosts and devices.

Current scope is intentionally limited to structure, variables scaffolding, and safe validation workflows.

4) Compose runtime definitions

Compose files define intended service runtime composition, networking, labels, and integration.

5) Architecture docs

docs/architecture.md provides a human-readable topology view based on repository configuration and observed runtime signals.

6) Dynu DNS read-only inventory

scripts/dynu/ and docs/dynu-dns-inventory.md provide a strictly read-only DNS inventory workflow:

• fetch Dynu DNS data with GET-only API usage,
• correlate Dynu hostnames with Traefik Host(...) labels in Compose sources,
• generate local JSON and markdown artifacts for documentation pipelines.

Dynu write operations are intentionally blocked in this repository stage.

Output shaping expectations

When adding Terraform outputs for documentation/tooling:

• prefer concise inventory maps/lists,
• include stable identifiers and roles,
• avoid raw giant provider objects where possible,
• include descriptions so future consumers understand intent.

Limitations today

• Generated host topology document: docs/generated/host-topology.md (via scripts/docs/build_host_topology.sh).
• No full generated inventory document pipeline is present yet.
• Some Terraform files still include generated boilerplate comments requiring ongoing cleanup.
• Ansible is currently a bootstrap inventory/configuration layer and is not authoritative for full operations yet.
• NixOS operational management is not yet implemented as an Ansible authority in this repo.

These limitations are expected for the current adoption stage.