homelab/CLAUDE.example.md

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:

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