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) Compose runtime definitions

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

4) Architecture docs

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

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

• No full generated inventory document pipeline is present yet.
• Some Terraform files still include generated boilerplate comments requiring ongoing cleanup.
• Ansible/NixOS operational layers are not yet implemented in a way that provides authoritative inventory in this repo.

These limitations are expected for the current adoption stage.