GitOps Homelab 2.0 Knowledge Bundle
Bundle OKF 0.2 · 34 conceitos · JamesAtIntegratnIO/gitops_homelab_2_0
Open source Repository Open in the app JSON README (API)
About
# GitOps Homelab 2.0 Knowledge Bundle
An [OKF](https://github.com/GoogleCloudPlatform/knowledge-catalog) bundle
describing this repository and the live cluster it manages (`the-cluster`).
Start with [Getting started](getting-started.md); consult
[known issues](cluster/known-issues.md) for the current warts.
# Start here
* [Getting started](getting-started.md) - orientation: what this platform is, how to navigate the bundle, and how it was produced.
# Platform design
* [Platform architecture](platform/architecture.md) - the big picture: Talos + ArgoCD + Kratix + vclusters, and the ADRs behind them.
* [GitOps flow, end to end](platform/gitops-layers.md) - how a change travels through bootstrap, addons, promises, and workloads.
* [Secret management](platform/secret-management.md) - the 1Password → ExternalSecrets design and its enforcement layers.
* [Networking](platform/networking.md) - Cilium, MetalLB, Gateway API, DNS, TLS, and the full address plan.
* [Storage](platform/storage.m
Details
- Kind
- OKF bundles
- Topic
- Cloud & DevOps
- Publisher
- jamesatintegratnio
- Origin
- okf_github
- Category
- dados
- Version
- 0.2
- Stars
- 2
- Open pull requests
- 9
- Last push
- 2026-09-09T14:34:01Z
- Repository state
- ativo
- Language
- Go
- Added
- 2026-09-09 12:02:17
- Updated
- 2026-09-09 12:02:17
- Origin id
JamesAtIntegratnIO/gitops_homelab_2_0:docs/okf/index.md
README
# GitOps Homelab 2.0
A production-grade GitOps platform running on bare-metal, built for learning and demonstrating enterprise Kubernetes patterns at homelab scale.
**Stack**: Talos Linux · Kubernetes 1.34 · ArgoCD · Kratix · vcluster · ExternalSecrets · 1Password
## Architecture
```
┌─────────────────────────────────────────────────────────────┐
│ Git (this repo) │
│ addons/ · platform/ · promises/ · workloads/ · terraform/ │
└──────┬──────────────────────────────┬───────────────────────┘
│ │
▼ ▼
┌──────────────┐ ┌──────────────────┐
│ Terraform │ │ ArgoCD │
│ Bootstrap │───────────▶│ ApplicationSets │
└──────────────┘ └────────┬─────────┘
│
┌──────────────────────┼──────────────────────┐
▼ ▼ ▼
┌────────────────┐ ┌──────────────────┐ ┌────────────────┐
│ Host Cluster │ │ Kratix Promises │ │ vclusters │
│ (control-plane)│ │ & Pipelines │ │ (workloads) │
│ │ │ │ │ │
│ cert-manager │ │ VClusterOrch v2 │ │ nginx-gateway │
│ external-secrets│ │ (Go SDK) │ │ cert-manager │
│ nginx-gateway │ │ │ │ external-dns │
│ metallb │ │ ┌────────────┐ │ │ argocd │
│ kratix │ │ │ Pipelines │ │ │ │
│ prometheus │ │ │ render to │──┼──▶│ sonarr, radarr │
│ loki │ │ │ state repo │ │ │ sabnzbd, wiki │
└────────────────┘ │ └────────────┘ │ └────────────────┘
└──────────────────┘
```
Three 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.
Secrets never live in Git. All credentials flow through 1Password → ExternalSecrets.
For the full architecture deep-dive, see [docs/architecture.md](docs/architecture.md).
## Repository Structure
```
.
├── addons/ # ArgoCD addon definitions (the "what to deploy" layer)
│ ├── charts/application-sets/ # Helm chart that renders one ApplicationSet per addon
│ ├── cluster-roles/ # Addons by role: control-plane, vcluster
│ ├── clusters/ # Per-cluster overrides (the-cluster, vcluster-media)
│ └── environments/ # Per-environment config (production, staging, development)
│
├── platform/ # Kratix ResourceRequests (the "what to provision" layer)
│ └── vclusters/ # vcluster provisioning requests
│
├── promises/ # Kratix Promise definitions (the "how to provision" layer)
│ ├── vcluster-orchestrator-v2/ # Active: Go SDK pipeline for full vcluster lifecycle
│ └── _archived/ # Superseded v1 bash promises (kept for reference)
│
├── workloads/ # Application definitions deployed inside vclusters
│ └── vcluster-media/ # Media stack: sonarr, radarr, sabnzbd, otterwiki
│
├── terraform/ # Infrastructure as Code
│ ├── cluster/ # ArgoCD bootstrap, ExternalSecrets operator, Cloudflare
│ └── modules/cloudflare/ # DNS zone management
│
├── matchbox/ # PXE/iPXE bare-metal provisioning for Talos Linux
│ ├── groups/ # MAC-address to profile mappings
│ ├── profiles/ # Boot profiles (kernel + initramfs + machine config)
│ └── talos-machineconfigs/ # Talos machine configuration patches
│
├── docs/ # Architecture, operations, troubleshooting guides
├── hack/ # Development and testing utilities
├── images/ # Container image sources (kubectl)
├── scripts/ # Git hooks setup
└── flake.nix # Nix dev environment (kubectl, tofu, helm, talosctl, k9s)
```
## GitOps Layers
The platform uses three declarative layers, each driven by Git:
| Layer | Directory | Engine | Purpose |
|-------|-----------|--------|---------|
| **Addons** | `addons/` | ArgoCD ApplicationSets | Cluster services (cert-manager, monitoring, networking) |
| **Platform** | `platform/` | Kratix Promises | Infrastructure provisioning (vclusters, future: databases) |
| **Workloads** | `workloads/` | ArgoCD (inside vcluster) | Application deployments (media stack) |
Addon value files are layered with precedence: `environments/` → `cluster-roles/` → `clusters/`. See [addons/README.md](addons/README.md) for details.
## Quick Start
```bash
# 1. Enter the development environment (provides all CLI tools)
nix develop
# 2. Bootstrap the cluster (after Talos nodes are running)
cd terraform/cluster
tofu init && tofu apply
# 3. Access ArgoCD
argocd login argocd.cluster.integratn.tech
```
## Key Workflows
### Provision a vcluster
```bash
# Create a resource request
cp platform/vclusters/vcluster-media.yaml platform/vclusters/vcluster-new.yaml
# Edit the spec, commit, push — Kratix handles the rest
```
### Add a workload to a vcluster
```bash
# Add app definition under workloads/<cluster-name>/addons/
# The vcluster's ArgoCD picks it up automatically
```
### Update a promise pipeline
```bash
# Modify Go code in promises/vcluster-orchestrator-v2/workflows/
# Push — GitHub Actions builds and publishes the new image
# Refresh the kratix-promises ArgoCD app to pick up the change
```
See [docs/operations.md](docs/operations.md) for full runbooks.
## Infrastructure
| Component | Details |
|-----------|---------|
| **Nodes** | 3× control-plane (Talos 1.11.5), PXE-booted |
| **Network** | 10.0.4.0/24 cluster, MetalLB L2 (10.0.4.200-253) |
| **Ingress** | nginx-gateway-fabric, Gateway API |
| **TLS** | cert-manager, Let's Encrypt (Cloudflare DNS-01) |
| **DNS** | external-dns → Cloudflare |
| **Secrets** | 1Password Connect → ExternalSecrets operator |
| **Monitoring** | kube-prometheus-stack, Loki, Promtail |
| **Storage** | NFS (Unraid), config-nfs-client / data-nfs-client |
## Documentation
| Guide | Description |
|-------|-------------|
| [Architecture](docs/architecture.md) | Full architecture, ADRs, data flows, security model |
| [Bootstrap](docs/bootstrap.md) | PXE boot, Talos setup, initial cluster creation |
| [Addons](docs/addons.md) | ApplicationSet mechanics, value file precedence |
| [Promises](docs/promises.md) | Kratix promise development and pipeline design |
| [vclusters](docs/vclusters.md) | vcluster lifecycle, networking, storage |
| [Observability](docs/observability.md) | Metrics, logs, dashboards |
| [Operations](docs/operations.md) | Runbooks, troubleshooting, common tasks |
| [Terraform](docs/terraform.md) | IaC workflow for cluster bootstrap |
| [MCP Servers](docs/mcp.md) | In-cluster MCP tool servers for LLM agents |
| [Kargo](docs/kargo.md) | Automated image and chart version updates — PR bot with per-target merge policy |
| [CLAUDE.md](CLAUDE.md) | Operating manual for coding agents working in this repo |
| [Knowledge bundle](docs/okf/index.md) | OKF concepts covering the repo *and* the live cluster |
## CI/CD
| Workflow | Trigger | Purpose |
|----------|---------|---------|
| [Build Go SDK Promises](.github/workflows/build-go-sdk-promises.yaml) | `promises/*/workflows/**` | Build and publish Go promise pipeline images |
| [Build kubectl Image](.github/workflows/build-kubectl-image.yaml) | `images/kubectl/**` | Multi-arch kubectl container image |
| [Validate Promises](.github/workflows/validate-promises.yaml) | `promises/**/*.yaml` | Block `kind: Secret` in promise output |