# CLAUDE.md — Homelab Integration Guide

**Homelab:** A bare-metal three-node Kubernetes cluster running Talos Linux with a full observability stack, SSO via Authentik, secret management via Vault, and CI/CD infrastructure (Forgejo + Argo CD, deployed).

## Service Integration Routes

**New service? Pick your stack below:**

| Need | Doc | Example |
|------|-----|---------|
| **Authentication** | `project-usage/authentik-oidc.md` | OAuth2 login, RBAC groups, JWT tokens |
| **Async messaging** | `project-usage/sqs-messaging.md` | Kafka topic consumers, fire-and-forget, DLQ |
| **Object storage** | `project-usage/minio-s3.md` | File uploads, backups, log backend |
| **CI/CD pipeline** | `project-usage/cicd-workflow.md` | GitHub Actions syntax, image push, Argo CD sync |
| **Workflows** | `project-usage/temporal-workflows.md` | Long-running jobs, retries, state machines |
| **Database** | `project-usage/database-postgres.md` | CloudNativePG setup, schema migrations, replicas |
| **Monitoring** | `project-usage/monitoring-metrics.md` | Prometheus scrape, Grafana dashboard, alerts |
| **Secrets** | `project-usage/vault-secrets.md` | Store credentials, rotate tokens, seal/unseal |
| **Networking** | `project-usage/networking-ingress.md` | Public HTTPS, hostname routing, TLS |

## Cluster Essentials

**22 namespaces, 18 releases:**
```
Core: cert-manager, ingress-nginx, kube-system, cilium
Storage: longhorn-system, storage (MinIO)
Data: ddb (PostgreSQL), iam (Authentik + Vault)
Observability: logging (Loki + Grafana), monitoring (Prometheus)
Apps: cicd (Forgejo + Argo CD), sqs (Kafka + kmsvc), temporal, story-crater-backend
```

**Architecture principles:**
- Immutable OS (Talos — no SSH, declarative config)
- Secrets in Vault (never commit `.env`, credentials in Secret volumes)
- Helmfile = single source of truth (`helmfile.yaml.gotmpl`)
- Pull-based GitOps (Argo CD, no kubeconfig in CI)
- Federated OIDC (Authentik provider for all services)


## Deployment Checklist

- [ ] Service has Prometheus `/metrics` endpoint or ServiceMonitor
- [ ] All credentials in Vault (never in pod env, ConfigMap, or code)
- [ ] Ingress rule in `k8s/ingress/` with TLS cert
- [ ] Grafana dashboard in `k8s/monitoring/dashboards/svc-<name>.yaml`
- [ ] Alert rules in `k8s/monitoring/alerts/svc-<name>-rules.yaml` (if needed)
- [ ] Helm release in `helmfile.yaml.gotmpl` with correct `needs:` dependencies

## Hard Rules

1. **No kubeconfig in CI** — Argo CD bridges gap (pull-based, never push secrets to runner)
2. **Field name = variable name** — In Vault: `talos put cluster/KAFKA_BOOTSTRAP KAFKA_BOOTSTRAP="..."`
3. **Secrets via volumes** — Never `--env` flag in pod specs (exposes in `kubectl describe`)
4. **External services via Ingress** — All public endpoints via TLS (homelab-ca)
5. **Never commit `.env`** — Only `.env.example` in git; real secrets in Vault

## Git & Release

**Multi-remote push:**
```bash
git push origin main
```

**Incremental commits (service-layer grouped):**
- Foundation & Docs
- Helmfile & Core Infra
- Storage Layer
- Observability Stack
- IAM & Secrets
- CI/CD & GitOps
- Messaging Infrastructure
- Applications & Utilities