llms.txt

# Talos Linux Multi-Environment Deployment Platform

> Sovereign air-gapped Kubernetes platform built on Talos Linux v1.12. Deploys a management cluster with full observability, PKI, identity (OIDC), security scanning, S3 storage, and GitOps across Scaleway, libvirt/KVM, and VMware airgap environments. Uses OpenTofu for infrastructure, Flux v2 for day-2 GitOps, and OpenBao for secrets and state storage.

## Project Context
- [README.md](README.md): Project overview and quick start
- [CLAUDE.md](CLAUDE.md): Comprehensive project context (architecture, commands, debugging)
- [AGENTS.md](AGENTS.md): AI agent context file (stack, patterns, gotchas)
- [CONTRIBUTING.md](CONTRIBUTING.md): Development workflow and conventions

## Architecture & Decisions
- [Roadmap](docs/roadmap.md): 3-gate implementation roadmap with dependency graph
- [Technology Stack](docs/techno.md): Complete component inventory with versions
- [ADR-001: Cilium CNI](docs/adr/001-cilium-cni.md): Why Cilium over Flannel
- [ADR-002: Block Storage](docs/adr/002-block-storage-evaluation.md): Why no distributed block storage
- [ADR-003: Garage S3](docs/adr/003-garage-sole-s3.md): Garage as sole S3 provider
- [ADR-004: Woodpecker CI/CD](docs/adr/004-woodpecker-cicd.md): Why Woodpecker over FluxCD
- [ADR-005: Podman Quadlet](docs/adr/005-podman-quadlet-ci.md): CI VM deployment method
- [ADR-006: Flux SSH](docs/adr/006-flux-ssh-static-key.md): Flux Git authentication
- [ADR-007: OpenBao](docs/adr/007-openbao-secrets-manager.md): OpenBao as secrets manager
- [ADR-008: Random Secrets](docs/adr/008-random-id-secrets.md): Auto-generated secrets
- [ADR-009: State Backend](docs/adr/009-state-backend-openbao.md): HTTP state backend via OpenBao
- [ADR-010: VictoriaMetrics](docs/adr/010-victoriametrics-observability.md): Observability stack choice
- [ADR-011: Trivy](docs/adr/011-trivy-node-collector-disabled.md): Node collector disabled for Talos
- [ADR-012: Garage Job](docs/adr/012-garage-k8s-job.md): Post-deploy setup via K8s Job
- [ADR-013: Service Mesh](docs/adr/013-kuma-mesh-deferred.md): Service mesh deferred
- [ADR-014: Backstage](docs/adr/014-backstage-deferred.md): Developer portal deferred
- [ADR-015: WireGuard](docs/adr/015-wireguard-ipv6-deferred.md): WireGuard + IPv6 deferred
- [ADR-016: Envoy DLP](docs/adr/016-envoy-dlp-deferred.md): Data loss prevention deferred
- [ADR-017: CozyStack](docs/adr/017-cozystack-paas-gate3.md): PaaS layer for Gate 3
- [ADR-018: Tetragon](docs/adr/018-tetragon-over-falco.md): Why Tetragon over Falco
- [ADR-019: Matchbox](docs/adr/019-matchbox-bare-metal.md): Bare metal/degraded VM provisioning
- [ADR-020: Kamaji](docs/adr/020-kamaji-kaas.md): KaaS alternative to Cozystack
- [ADR-021: Security Hardening](docs/adr/021-security-hardening.md): Consolidated security audit findings and remediations
- [ADR-022: Production Readiness](docs/adr/022-production-readiness-checklist.md): Production readiness checklist

## Documentation (Diataxis)
- [Landing Page](docs/index.md): What this is and where to go
- [Getting Started](docs/tutorials/getting-started.md): Prerequisites and first deployment
- [How to Deploy](docs/how-to/deploy.md): Deploy to any supported environment
- [How to Troubleshoot](docs/how-to/troubleshoot.md): Symptom/cause/fix table + health checks
- [Command Reference](docs/reference/commands.md): All Makefile targets, variables, env vars
- [Configuration Reference](docs/reference/config.md): Helm values, TF variables, env vars
- [CI/CD Reference](docs/reference/ci-cd.md): Woodpecker pipeline stages and secrets
- [Architecture](docs/explanation/architecture.md): Two-phase model, state, secrets, PKI, CAPI (Mermaid diagrams)
- [Bootstrap Mechanics](docs/explanation/bootstrap.md): 5 chicken-and-egg problems and their solutions (Mermaid diagrams)
- [Security Model](docs/explanation/security.md): Threat model, PKI trust chain, policy inventory
- [How to Upgrade](docs/how-to/upgrade.md): Upgrade workflow, rollback, arbor staging

## Infrastructure
- [Makefile](Makefile): Root orchestration with all deployment targets
- [vars.mk](vars.mk): Version pinning (Talos, Kubernetes, Cilium)
- [Talos Cluster Module](modules/talos-cluster/main.tf): Shared machine secrets and configs
- [Scaleway Environment](envs/scaleway/main.tf): Scaleway cluster infrastructure
- [CI Pipeline](.woodpecker.yml): Woodpecker CI pipeline (validate + 8 deploy stages)

## Kubernetes Stacks
- [cni](stacks/cni/main.tf): Cilium CNI deployment
- [pki](stacks/pki/main.tf): OpenBao + cert-manager + CA secrets
- [monitoring](stacks/monitoring/main.tf): VictoriaMetrics + VictoriaLogs + Headlamp
- [identity](stacks/identity/main.tf): Kratos + Hydra + Pomerium
- [security](stacks/security/main.tf): Trivy + Tetragon + Kyverno
- [storage](stacks/storage/main.tf): local-path + Garage + Velero + Harbor
- [flux-bootstrap](stacks/flux-bootstrap/main.tf): Flux v2 GitOps
- [external-secrets](stacks/external-secrets/): ESO + ClusterSecretStore (Flux only)

## Bootstrap
- [Bootstrap Module](bootstrap/main.tf): Platform pod Terraform (OpenBao + Gitea + Woodpecker)
- [Platform Pod Manifest](bootstrap/platform-pod.yaml): Podman pod spec (6 containers)
- [Setup Sidecar](bootstrap/tofu/): Auto-init KMS, CI setup, repo push, secrets export

## GitOps Manifests
- [Flux Root Kustomization](clusters/management/kustomization.yaml): Day-2 reconciliation entry point

## Configuration
- [Cilium Values](stacks/cni/values.yaml): Cilium Helm values
- [Monitoring Values](stacks/monitoring/values-vm-stack.yaml): VictoriaMetrics stack values
- [PKI Values](stacks/pki/values-openbao-infra.yaml): OpenBao infra Helm values
- [Identity Values](stacks/identity/values-hydra.yaml): Hydra Helm values
- [Storage Values](stacks/storage/values-harbor.yaml): Harbor registry Helm values

## Design
- [HLD/LLD System Design](docs/design/001-hld-lld.md): Complete high-level and low-level design
- [HLD Talos Platform](docs/hld-talos-platform.md): High-Level Design document (English)

## Scripts
- [Cosign Sign](scripts/cosign-sign.sh): Image signing pipeline for Woodpecker CI