mirror of
https://gitlab.kube.huskypup.net/Scooby/Homelabv4.git
synced 2026-08-20 23:16:49 +00:00
107 lines
3.9 KiB
Markdown
107 lines
3.9 KiB
Markdown
# 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
|