73 lines
3.1 KiB
Markdown
73 lines
3.1 KiB
Markdown
|
# 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
|