{
  "markdown": "# GitOps Homelab 2.0\n\nA production-grade GitOps platform running on bare-metal, built for learning and demonstrating enterprise Kubernetes patterns at homelab scale.\n\n**Stack**: Talos Linux · Kubernetes 1.34 · ArgoCD · Kratix · vcluster · ExternalSecrets · 1Password\n\n## Architecture\n\n```\n┌─────────────────────────────────────────────────────────────┐\n│                    Git (this repo)                          │\n│  addons/ · platform/ · promises/ · workloads/ · terraform/ │\n└──────┬──────────────────────────────┬───────────────────────┘\n       │                              │\n       ▼                              ▼\n┌──────────────┐            ┌──────────────────┐\n│   Terraform  │            │     ArgoCD       │\n│  Bootstrap   │───────────▶│  ApplicationSets │\n└──────────────┘            └────────┬─────────┘\n                                     │\n              ┌──────────────────────┼──────────────────────┐\n              ▼                      ▼                      ▼\n     ┌────────────────┐   ┌──────────────────┐   ┌────────────────┐\n     │  Host Cluster   │   │  Kratix Promises │   │   vclusters    │\n     │  (control-plane)│   │  & Pipelines     │   │  (workloads)   │\n     │                 │   │                  │   │                │\n     │ cert-manager    │   │ VClusterOrch v2  │   │ nginx-gateway  │\n     │ external-secrets│   │ (Go SDK)         │   │ cert-manager   │\n     │ nginx-gateway   │   │                  │   │ external-dns   │\n     │ metallb         │   │  ┌────────────┐  │   │ argocd         │\n     │ kratix          │   │  │ Pipelines  │  │   │                │\n     │ prometheus      │   │  │ render to  │──┼──▶│ sonarr, radarr │\n     │ loki            │   │  │ state repo │  │   │ sabnzbd, wiki  │\n     └────────────────┘   │  └────────────┘  │   └────────────────┘\n                           └──────────────────┘\n```\n\nThree control-plane nodes (Talos Linux, PXE-booted via Matchbox) run the host cluster. ArgoCD manages everything declaratively. Kratix promises provide platform APIs — a `VClusterOrchestratorV2` request provisions an entire tenant cluster with its own ArgoCD, networking, TLS, DNS, and observability.\n\nSecrets never live in Git. All credentials flow through 1Password → ExternalSecrets.\n\nFor the full architecture deep-dive, see [docs/architecture.md](docs/architecture.md).\n\n## Repository Structure\n\n```\n.\n├── addons/                        # ArgoCD addon definitions (the \"what to deploy\" layer)\n│   ├── charts/application-sets/   #   Helm chart that renders one ApplicationSet per addon\n│   ├── cluster-roles/             #   Addons by role: control-plane, vcluster\n│   ├── clusters/                  #   Per-cluster overrides (the-cluster, vcluster-media)\n│   └── environments/              #   Per-environment config (production, staging, development)\n│\n├── platform/                      # Kratix ResourceRequests (the \"what to provision\" layer)\n│   └── vclusters/                 #   vcluster provisioning requests\n│\n├── promises/                      # Kratix Promise definitions (the \"how to provision\" layer)\n│   ├── vcluster-orchestrator-v2/  #   Active: Go SDK pipeline for full vcluster lifecycle\n│   └── _archived/                 #   Superseded v1 bash promises (kept for reference)\n│\n├── workloads/                     # Application definitions deployed inside vclusters\n│   └── vcluster-media/            #   Media stack: sonarr, radarr, sabnzbd, otterwiki\n│\n├── terraform/                     # Infrastructure as Code\n│   ├── cluster/                   #   ArgoCD bootstrap, ExternalSecrets operator, Cloudflare\n│   └── modules/cloudflare/        #   DNS zone management\n│\n├── matchbox/                      # PXE/iPXE bare-metal provisioning for Talos Linux\n│   ├── groups/                    #   MAC-address to profile mappings\n│   ├── profiles/                  #   Boot profiles (kernel + initramfs + machine config)\n│   └── talos-machineconfigs/      #   Talos machine configuration patches\n│\n├── docs/                          # Architecture, operations, troubleshooting guides\n├── hack/                          # Development and testing utilities\n├── images/                        # Container image sources (kubectl)\n├── scripts/                       # Git hooks setup\n└── flake.nix                      # Nix dev environment (kubectl, tofu, helm, talosctl, k9s)\n```\n\n## GitOps Layers\n\nThe platform uses three declarative layers, each driven by Git:\n\n| Layer | Directory | Engine | Purpose |\n|-------|-----------|--------|---------|\n| **Addons** | `addons/` | ArgoCD ApplicationSets | Cluster services (cert-manager, monitoring, networking) |\n| **Platform** | `platform/` | Kratix Promises | Infrastructure provisioning (vclusters, future: databases) |\n| **Workloads** | `workloads/` | ArgoCD (inside vcluster) | Application deployments (media stack) |\n\nAddon value files are layered with precedence: `environments/` → `cluster-roles/` → `clusters/`. See [addons/README.md](addons/README.md) for details.\n\n## Quick Start\n\n```bash\n# 1. Enter the development environment (provides all CLI tools)\nnix develop\n\n# 2. Bootstrap the cluster (after Talos nodes are running)\ncd terraform/cluster\ntofu init && tofu apply\n\n# 3. Access ArgoCD\nargocd login argocd.cluster.integratn.tech\n```\n\n## Key Workflows\n\n### Provision a vcluster\n```bash\n# Create a resource request\ncp platform/vclusters/vcluster-media.yaml platform/vclusters/vcluster-new.yaml\n# Edit the spec, commit, push — Kratix handles the rest\n```\n\n### Add a workload to a vcluster\n```bash\n# Add app definition under workloads/<cluster-name>/addons/\n# The vcluster's ArgoCD picks it up automatically\n```\n\n### Update a promise pipeline\n```bash\n# Modify Go code in promises/vcluster-orchestrator-v2/workflows/\n# Push — GitHub Actions builds and publishes the new image\n# Refresh the kratix-promises ArgoCD app to pick up the change\n```\n\nSee [docs/operations.md](docs/operations.md) for full runbooks.\n\n## Infrastructure\n\n| Component | Details |\n|-----------|---------|\n| **Nodes** | 3× control-plane (Talos 1.11.5), PXE-booted |\n| **Network** | 10.0.4.0/24 cluster, MetalLB L2 (10.0.4.200-253) |\n| **Ingress** | nginx-gateway-fabric, Gateway API |\n| **TLS** | cert-manager, Let's Encrypt (Cloudflare DNS-01) |\n| **DNS** | external-dns → Cloudflare |\n| **Secrets** | 1Password Connect → ExternalSecrets operator |\n| **Monitoring** | kube-prometheus-stack, Loki, Promtail |\n| **Storage** | NFS (Unraid), config-nfs-client / data-nfs-client |\n\n## Documentation\n\n| Guide | Description |\n|-------|-------------|\n| [Architecture](docs/architecture.md) | Full architecture, ADRs, data flows, security model |\n| [Bootstrap](docs/bootstrap.md) | PXE boot, Talos setup, initial cluster creation |\n| [Addons](docs/addons.md) | ApplicationSet mechanics, value file precedence |\n| [Promises](docs/promises.md) | Kratix promise development and pipeline design |\n| [vclusters](docs/vclusters.md) | vcluster lifecycle, networking, storage |\n| [Observability](docs/observability.md) | Metrics, logs, dashboards |\n| [Operations](docs/operations.md) | Runbooks, troubleshooting, common tasks |\n| [Terraform](docs/terraform.md) | IaC workflow for cluster bootstrap |\n| [MCP Servers](docs/mcp.md) | In-cluster MCP tool servers for LLM agents |\n| [Kargo](docs/kargo.md) | Automated image and chart version updates — PR bot with per-target merge policy |\n| [CLAUDE.md](CLAUDE.md) | Operating manual for coding agents working in this repo |\n| [Knowledge bundle](docs/okf/index.md) | OKF concepts covering the repo *and* the live cluster |\n\n## CI/CD\n\n| Workflow | Trigger | Purpose |\n|----------|---------|---------|\n| [Build Go SDK Promises](.github/workflows/build-go-sdk-promises.yaml) | `promises/*/workflows/**` | Build and publish Go promise pipeline images |\n| [Build kubectl Image](.github/workflows/build-kubectl-image.yaml) | `images/kubectl/**` | Multi-arch kubectl container image |\n| [Validate Promises](.github/workflows/validate-promises.yaml) | `promises/**/*.yaml` | Block `kind: Secret` in promise output |\n",
  "bytes": 8037,
  "sha": "4f3a5bd3d8e2cdd15787fda2cb203ee6264b78662934e7bdcd19d28eb117358b",
  "repo_slug": "jamesatintegratnio/gitops_homelab_2_0",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/okf_jamesatintegratnio_gitops_homelab_2_0_do_72ce11b0/readme"
}