Homelabv4/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code when working with this repository.

Overview

Homelabv4 is a fully automated Kubernetes homelab deployment using ArgoCD App-of-Apps pattern for GitOps-based continuous delivery. It replaces the Helmfile-based Homelabv5 with declarative ArgoCD Application CRDs, sync waves for ordering, and Kubernetes Jobs for complex hooks.

Deployment

Bootstrap (one-time)

# Prerequisites: ArgoCD must already be running on the cluster
# Replace <GIT_REPO_URL> in all Application CRDs with your actual repo URL
# Then:
kubectl apply -f bootstrap.yaml

How It Works

1. bootstrap.yaml creates a root Application pointing to argocd-apps/
2. ArgoCD discovers all Application CRDs in argocd-apps/infrastructure/ and argocd-apps/apps/
3. Sync waves control deployment order (lower waves first)
4. ArgoCD waits for resources to be healthy before advancing waves
5. PreSync/PostSync hook Jobs handle complex initialization

Verify Deployment

kubectl get applications -n argocd
kubectl get pods -A | grep -v Running | grep -v Completed

Architecture

Sync Wave Scheme

Wave	Phase	Components
-1	Bootstrap	Prometheus CRDs
1-7	Core Net	Cilium, Istio, cert-manager, metrics-server, envoy-gateway
10-14	Storage	Rook-Ceph, CNPG, Redis, MariaDB, Scylla operators
20-23	Security	Vault, ESO, Reloader, Authentik, Kyverno, Tetragon, CrowdSec
30-31	Net Extra	External-DNS, Netbird, Mosquitto
40-43	Monitoring	Prometheus, Grafana, Kiali, Checkov
50-52	Apps	GitLab, ArgoCD, n8n, Nextcloud, TeslaMate, HA, Frigate, etc.

Directory Structure

Homelabv4/
├── bootstrap.yaml              # Root App-of-Apps
├── argocd-apps/                # Application CRDs
│   ├── infrastructure/         # ~35 infra Applications
│   └── apps/                   # ~10 user Applications
├── infrastructure/             # Source files for infra
│   └── <service>/
│       ├── values.yaml         # Helm values
│       └── manifests/          # Raw K8s manifests
├── apps/                       # Source files for apps
│   └── <app>/
│       ├── values.yaml
│       └── manifests/
├── charts/                     # Local Helm charts
├── hooks/                      # Shared hook RBAC
├── environments/               # Environment config
└── scripts/                    # Manual scripts

Key Patterns

Multi-Source Applications

Most Applications use 3 sources:

1. Remote Helm chart repo
2. Git repo ref for values files
3. Git repo path for raw manifests

Hook Jobs

Complex initialization (Vault init, OAuth sync) uses K8s Jobs with ArgoCD hook annotations:

• argocd.argoproj.io/hook: PreSync or PostSync
• argocd.argoproj.io/hook-delete-policy: BeforeHookCreation
• Jobs use argocd-hook-sa ServiceAccount with cluster-admin

Secrets Flow

Vault → External Secrets Operator → Kubernetes Secrets → Apps

Common Operations

Add a New Application

1. Create apps/<name>/values.yaml with Helm values
2. Create apps/<name>/manifests/ with any raw manifests
3. Create argocd-apps/apps/<name>.yaml Application CRD
4. Commit and push — ArgoCD auto-syncs

Update Helm Values

1. Edit infrastructure/<service>/values.yaml or apps/<app>/values.yaml
2. Commit and push — ArgoCD auto-syncs

Force Sync

argocd app sync <app-name>

Important Notes

• Git repo URL: Replace <GIT_REPO_URL> placeholder in all Application CRDs
• Secrets: Never commit secrets — use Vault + ExternalSecret
• Domain: All services use *.kube.huskypup.net
• Storage: Default StorageClass is rook-ceph-block
• Ingress: Istio VirtualServices + Envoy Gateway HTTPRoutes
• mTLS: Istio ambient mesh with STRICT PeerAuthentication