Overview

This site describes the homelab, its operating procedures, and the decisions behind its design. The repository stores infrastructure code in kubernetes/, terraform/, and ansible/. Published documentation is in docs/.

Find the right document

For cluster configuration and reconciliation boundaries, read Kubernetes and GitOps.
For Proxmox, DNS, Talos, and other managed infrastructure, read Terraform.
For host configuration and maintenance playbooks, read Ansible.
For rack positions, hardware, and management addresses, read the hardware inventory.
For maintenance and incident procedures, start with the runbooks or the alert runbook index.
For accepted design constraints, read the architecture decisions.

GitOps boundaries

The Talos staging cluster reconciles the main branch of this repository from kubernetes/clusters/staging. The production cluster reconciles the separate igresc/gitops repository. Changes under kubernetes/clusters/prod in this repository do not change the running production cluster.

Operations

Documentation map

platform/ documents the main infrastructure tools and their repository layout.
hardware/ records the physical rack and device inventory.
services/ contains service operating guides.
runbooks/ contains maintenance, recovery, and incident procedures.
decisions/ records accepted architecture decisions.
repository/ documents the tools that build and publish this site.

Keep each document's canonical copy under docs/. Source directories may link to this site, but must not duplicate its instructions.

docs/overview.md