beatz174-bit
64 lines
3.1 KiB
Markdown
64 lines
3.1 KiB
Markdown
# Source-of-Truth Boundaries
|
|
|
|
This repository has multiple layers. Knowing the authority for each layer prevents accidental drift.
|
|
|
|
## Boundary summary
|
|
|
|
| Layer | Primary authority | Purpose |
|
|
|---|---|---|
|
|
| Application/runtime container composition | `services-up.sh` + Compose files under `core/`, `apps/`, `monitoring/` | What runs in the Docker environment and how services are wired. |
|
|
| Docker shared baseline inputs | `default-network.yml`, `default-environment.env`, `secrets/stack-secrets.env` | Shared network/env material applied during compose rendering. |
|
|
| Infrastructure inventory and reconciliation | Terraform under `infrastructure/terraform/` | Codified inventory of existing infrastructure and relationships, especially Proxmox VMs and selected Docker mirrors. |
|
|
| Secret policy and inventory | `docs/security-secrets.md` + `secrets/inventory.json` + local secret files in `secrets/` | What secrets exist, where they are expected, and what automation should parse. |
|
|
| Host/device configuration bootstrap (emerging) | Ansible under `infrastructure/ansible/` | Gradual inventory/configuration layer for hosts/devices; validation-first at current stage. |
|
|
|
|
## Practical meaning
|
|
|
|
### Docker runtime decisions
|
|
|
|
Change Compose files and `services-up.sh` when changing runtime behavior.
|
|
|
|
Do **not** assume Terraform Docker resources are the deployment source for day-to-day service runtime.
|
|
|
|
### Infrastructure inventory decisions
|
|
|
|
Use Terraform when documenting/reconciling existing:
|
|
|
|
- Proxmox VM config and identifiers.
|
|
- Physical host metadata.
|
|
- Select Docker container details that are intentionally mirrored.
|
|
|
|
Do **not** treat Terraform as a full replacement for Compose operations in this repo.
|
|
|
|
- Dynu public DNS records remain authoritative at Dynu.
|
|
- Terraform Dynu configuration mirrors/reconciles Dynu DNS state for documentation and controlled drift management.
|
|
- Imported Dynu Terraform state reflects actual provider-side DNS state at import time.
|
|
|
|
|
|
### Ansible bootstrap decisions
|
|
|
|
Use Ansible under `infrastructure/ansible/` to build inventory and configuration structure incrementally.
|
|
|
|
At the current stage:
|
|
|
|
- Do **not** treat Ansible as replacement authority for Docker runtime operations.
|
|
- Do **not** treat Ansible as replacement authority for Terraform inventory/reconciliation.
|
|
- NixOS remains outside Ansible authority unless explicitly adopted in a later phase.
|
|
|
|
## Declared config vs observed/runtime state
|
|
|
|
- **Declared config**: files in this repository (Compose, Terraform, docs).
|
|
- **Observed/runtime state**: live Docker/Proxmox reality and Terraform state snapshots.
|
|
|
|
Brownfield workflows reconcile these two safely and incrementally.
|
|
|
|
## Guardrails for contributors and Codex
|
|
|
|
- Do not mass-import or mass-reconcile everything at once.
|
|
- Keep imports/reconciliation scoped to one object (or small set) at a time.
|
|
- Keep `ignore_changes` surgical and justified.
|
|
- Prefer shaped outputs (inventory-ready) over raw provider object dumps.
|
|
- Do not commit `.tfstate`, real `.tfvars`, or real secret files.
|
|
|
|
See [docs/terraform-workflows.md](terraform-workflows.md) for step-by-step procedures.
|