# 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)
```bash
# 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
```bash
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
```bash
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