From 052c881fb727475a969143b08155f4841eed0e6d Mon Sep 17 00:00:00 2001 From: Janis Date: Wed, 29 Apr 2026 21:19:55 +0200 Subject: [PATCH] feat: add initial documentation and configuration files for Claude and Redis applications --- CLAUDE.md | 163 ++++++++++++++++++++++++ eu-central-1/argo-apps/redis/redis.yaml | 27 ++++ redis/eu-central-1/kustomization.yaml | 3 + redis/eu-central-1/values.yaml | 16 +++ 4 files changed, 209 insertions(+) create mode 100644 CLAUDE.md create mode 100644 eu-central-1/argo-apps/redis/redis.yaml create mode 100644 redis/eu-central-1/kustomization.yaml create mode 100644 redis/eu-central-1/values.yaml diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..2644746 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,163 @@ +# CLAUDE.md + +This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. + +## Quick Commands + +### Building & Validation +```bash +# Build manifests (with Helm support) +kustomize build --enable-helm > output.yaml + +# Validate without applying +kustomize build --enable-helm | kubectl apply --dry-run=client -f - + +# Apply manifests to cluster +kustomize build --enable-helm | kubectl apply -f - + +# Apply single manifest +kubectl apply -f +``` + +### Monitoring & Inspection +```bash +# Watch Argo CD applications +kubectl -n argocd get applications -w +argocd app list + +# Check component status +kubectl -n get pods +kubectl -n logs -f deployment/ + +# Describe resource +kubectl -n describe + +# Check application sync status +argocd app get +kubectl -n argocd describe application +``` + +### Common Operations +```bash +# Port forward to Argo CD UI +kubectl port-forward -n argocd svc/argocd-server 8080:443 + +# Get Argo CD admin password +kubectl -n argocd get secret argocd-initial-admin-secret \ + -o jsonpath="{.data.password}" | base64 --decode + +# Port forward to Kargo API +kubectl port-forward -n kargo svc/kargo-api 8443:443 + +# Check certificate status +kubectl get certificate -A +kubectl describe certificate -n +``` + +## Architecture Overview + +### Component Structure +The repo has three parallel hierarchies for **components**, **regions**, and **deployments**: + +1. **Components** (`argocd/`, `cert-manager/`, `kargo/`, `argo-rollouts/`): + - `base/` - core Kustomization and Helm values + - `/` (e.g., `eu-central-1/`) - region-specific overrides and values + +2. **Regions** (`eu-central-1/`): + - `root-apps-app.yaml` - root Argo CD application that syncs all other apps + - `argo-apps/` - Argo Application resources for each component + +3. **Projects** (`kargo-projects/orchestration-stack/`): + - Defines Kargo Warehouse, Stages, Promotions for progressive delivery + +### Key Components +- **Argo CD**: Declarative GitOps CD tool - watches this repo and syncs manifests +- **Cert-Manager**: Automates certificate lifecycle (self-signed CA, can add Let's Encrypt) +- **Kargo**: Progressive delivery platform - multi-stage promotions with health checks +- **Argo Rollouts**: Advanced deployment strategies (canary, blue-green) + +### How It Works +1. Git commit → Webhook fires → Argo CD fetches latest manifests → Kustomize builds → kubectl applies +2. Sealed Secrets in Git are encrypted at rest, decrypted only in cluster +3. Kargo watches Warehouse for new Freight → auto-promotes or waits for approval → updates Argo CD apps + +## Important Patterns + +### Kustomization Pattern +Each component follows `base/` + `/` pattern: +- `base/` has shared config, disabled Helm charts (kustomization.yaml) +- `/` enables Helm and overrides values with regional specifics +- To add a new region: copy `eu-central-1/` to new region dir, update domain/values + +### Sealed Secrets +- Store encrypted secrets in `secrets/` directory +- Use `kubeseal` CLI to encrypt before committing +- Never commit plaintext credentials +- Sealing keys are NOT in Git (stored in cluster) + +### Build with --enable-helm +All Kustomize builds must use `--enable-helm` flag because components use Helm charts. Forgetting this is a common mistake. + +### Namespace & Labels +Components deploy to dedicated namespaces: +- `argocd` - Argo CD +- `cert-manager` - Cert-Manager +- `kargo` - Kargo +Avoid cross-namespace resource references; use Argo CD Applications for composition. + +## File Locations Reference + +``` +argocd/base/values.yaml # Argo CD Helm values (base) +argocd/eu-central-1/values.yaml # Argo CD regional overrides +cert-manager/eu-central-1/cert-issuer.yaml # CA issuer config +kargo/base/values.yaml # Kargo Helm values +kargo-projects/orchestration-stack/ # Kargo project definitions +eu-central-1/root-apps-app.yaml # Root Argo CD app (entry point) +secrets/ # Sealed secrets storage +scripts/deploy-to-cluster.sh # One-shot cluster bootstrap +``` + +## Common Tasks + +### Add a New Region +1. Create `eu-west-1/` directory structure mirroring `eu-central-1/` +2. Copy component overlays and update domain/version values +3. Create `eu-west-1/root-apps-app.yaml` pointing to regional resources +4. Test: `kustomize build --enable-helm eu-west-1/` + +### Update Component Versions +1. Edit Helm chart version in `//kustomization.yaml` +2. Validate: `kustomize build --enable-helm //` +3. Apply: `kustomize build --enable-helm // | kubectl apply -f -` + +### Create a New Secret +1. Create plaintext secret: `kubectl -n create secret generic my-secret --from-literal=key=value --dry-run=client -o yaml > secret.yaml` +2. Encrypt: `kubeseal -f secret.yaml -w sealed-secret.yaml` +3. Move to `secrets/` directory and commit +4. Cluster controller auto-decrypts when applied + +### Sync Application Manually +```bash +argocd app sync +# or force sync if stuck +argocd app sync --force +``` + +## Debugging Tips + +- Use `--dry-run=client` to validate before applying +- Check `kubectl -n describe pod ` for startup errors +- Use `kubectl -n logs ` for runtime issues +- Verify Git repository credentials: `kubectl -n argocd get secret repo-credentials -o yaml` +- For Argo CD sync failures: `kubectl -n argocd describe application ` +- Use `kustomize build . -v` for verbose Kustomize output + +## Documentation Index + +- **README.md** - Overview, prerequisites, quick start, installation steps +- **ARCHITECTURE.md** - Detailed system design, data flows, security layers +- **DEPLOYMENT_GUIDE.md** - Step-by-step installation for different scenarios +- **CONFIGURATION.md** - Configuration customization guide +- **CONTRIBUTING.md** - Commit message conventions, testing guidelines, release process +- **TROUBLESHOOTING.md** - Common issues and solutions diff --git a/eu-central-1/argo-apps/redis/redis.yaml b/eu-central-1/argo-apps/redis/redis.yaml new file mode 100644 index 0000000..72c01a9 --- /dev/null +++ b/eu-central-1/argo-apps/redis/redis.yaml @@ -0,0 +1,27 @@ +apiVersion: argoproj.io/v1alpha1 +kind: Application +metadata: + name: redis + namespace: argocd +spec: + project: default + destination: + namespace: redis + server: https://kubernetes.default.svc + sources: + - repoURL: https://charts.bitnami.com/bitnami + chart: redis + targetRevision: 20.x + helm: + valueFiles: + - $values/redis/eu-central-1/values.yaml + - repoURL: git@git.janis-eccarius.de:NowChess/GitOps.git + path: ./redis/eu-central-1 + ref: values + targetRevision: main + syncPolicy: + automated: + prune: true + selfHeal: true + syncOptions: + - CreateNamespace=true diff --git a/redis/eu-central-1/kustomization.yaml b/redis/eu-central-1/kustomization.yaml new file mode 100644 index 0000000..b83b23e --- /dev/null +++ b/redis/eu-central-1/kustomization.yaml @@ -0,0 +1,3 @@ +apiVersion: kustomize.config.k8s.io/v1beta1 +kind: Kustomization +resources: [] diff --git a/redis/eu-central-1/values.yaml b/redis/eu-central-1/values.yaml new file mode 100644 index 0000000..8a9adfa --- /dev/null +++ b/redis/eu-central-1/values.yaml @@ -0,0 +1,16 @@ +architecture: standalone + +auth: + enabled: false + +master: + resources: + requests: + cpu: 50m + memory: 64Mi + limits: + cpu: 200m + memory: 128Mi + + persistence: + enabled: false