From a75502bd5bbb2681ba4a808e58ea4358d044d9c4 Mon Sep 17 00:00:00 2001 From: Janis Eccarius Date: Sat, 6 Jun 2026 14:56:23 +0200 Subject: [PATCH] docs(claude): add scaffold-service skill Skill that guides creating a new NowChess microservice (blue/green Rollout + active/preview Services + HPA + image registration across overlays + Kargo automation) and adding/changing configuration, with the kustomize build + kubectl dry-run validation gate. Co-Authored-By: Claude Opus 4.8 --- .claude/skills/scaffold-service/SKILL.md | 109 +++++++++++++++++++++++ 1 file changed, 109 insertions(+) create mode 100755 .claude/skills/scaffold-service/SKILL.md diff --git a/.claude/skills/scaffold-service/SKILL.md b/.claude/skills/scaffold-service/SKILL.md new file mode 100755 index 0000000..35afb76 --- /dev/null +++ b/.claude/skills/scaffold-service/SKILL.md @@ -0,0 +1,109 @@ +--- +name: scaffold-service +description: Scaffold a new NowChess microservice or add/change configuration in this GitOps repo. Use when asked to "add a microservice", "add a new service", "wire a new deployment", "add an env var / ConfigMap", "add a new config", or "register a new image" for the nowchess stack. Knows the base + overlay + image-automation layout and the kustomize/dry-run validation gate. +--- + +# Scaffold a NowChess service / configuration (GitOps) + +A NowChess microservice is an Argo Rollouts **blue/green Rollout** with an +**active + preview Service pair**, an **HPA**, environment via a shared +**ConfigMap** + **Secrets**, and an **image** registered (and tag-automated via +Kargo) in every region/stage overlay. + +Always read the existing `nowchess-account` service as the reference example +before writing — copy its shape, don't invent one. + +Files that define the base stack (`nowchess/base/`): + +| File | Holds | +|------|-------| +| `nowchess-rollouts.yaml` | one `Rollout` per service | +| `nowchess-services.yaml` | `-active` + `-preview` Services | +| `nowchess-hpa.yaml` | one `HorizontalPodAutoscaler` per service | +| `nowchess-env-config.yaml` | shared `nowchess-env-config` ConfigMap | +| `kustomization.yaml` | resource list + `rollout-transform.yaml` + openapi schema | + +Overlays: `nowchess/{eu-central-1-prod,eu-central-1-staging,htwg-1-prod}/` — +each `kustomization.yaml` sets namespace, patches HPA replicas + ConfigMap, and +pins `images:` tags. Image tag bumps are automated by Kargo under +`kargo-projects/nowchess/`. + +--- + +## Mode A — Add a new microservice `` (service name `nowchess-`) + +1. **Pick a unique container port.** Check the ports already used in + `nowchess-services.yaml` (8080 core, 8083 account, 8087 bot-platform, …) and + choose a free one. Use the same port for container, active and preview. + +2. **Rollout** — append a `Rollout` to `nowchess/base/nowchess-rollouts.yaml`, + modelled on `nowchess-account`: + - `metadata.name` + `labels.app` + `selector.matchLabels.app` = + `nowchess-`. + - `spec.strategy.blueGreen.activeService: nowchess--active`, + `previewService: nowchess--preview` (match the existing blueGreen + block). + - `image: ghcr.io/now-chess/now-chess-systems/:latest`, + `imagePullPolicy: Always`, `imagePullSecrets: ghcr-pull-secret`. + - `envFrom` the `nowchess-env-config` ConfigMap; add only the extra `env` + this service needs (reuse the existing secret refs where applicable). + - Update the grafana scrape annotation `metrics_portNumber` to the chosen port. + +3. **Services** — append `nowchess--active` and `nowchess--preview` to + `nowchess/base/nowchess-services.yaml` (`selector.app: nowchess-`, the + chosen port). Both are required — blue/green needs the pair. + +4. **HPA** — append a `HorizontalPodAutoscaler` to + `nowchess/base/nowchess-hpa.yaml` with + `scaleTargetRef: { apiVersion: argoproj.io/v1alpha1, kind: Rollout, name: nowchess- }`. + + `nowchess-rollouts.yaml`, `-services.yaml`, `-hpa.yaml` are already in the + base `kustomization.yaml` `resources:` — **no new resource entry needed** for + these. Only add to `resources:` when you create a brand-new file. + +5. **Register the image in every overlay.** In each + `nowchess//kustomization.yaml` add to `images:`: + ```yaml + - name: ghcr.io/now-chess/now-chess-systems/ + newTag: + ``` + If staging caps replicas, also add the per-overlay HPA patch + (`maxReplicas: 1`) like the sibling services in `eu-central-1-staging`. + +6. **Kargo image automation** — add the new image to the warehouse subscription + and promotion steps under `kargo-projects/nowchess/` (mirror an existing + service entry in `ncs-warehouse.yaml` and `ncs-promotion-template.yaml`) so + tag bumps are automated. + +7. **Secrets / RBAC** — if the service needs DB creds, JWT keys, or coordinator + RBAC, add the refs the same way `account`/`coordinator` do. Never commit + plaintext secrets — re-seal with `scripts/seal-secrets.sh`. + +## Mode B — Add / change configuration + +- **Shared env var** → add the key to `nowchess/base/nowchess-env-config.yaml`, + then override per environment with a ConfigMap patch in each overlay's + `kustomization.yaml` (see the `nowchess-env-config` patch in + `eu-central-1-staging`). +- **New ConfigMap / Secret file** → create the YAML, add it to the relevant + `kustomization.yaml` `resources:`, and wire it into the Rollout via `envFrom` + / `valueFrom` (the `rollout-transform.yaml` nameReference rules already remap + ConfigMap/Secret names inside Rollouts). +- **Region-specific value** → patch it in the overlay only; keep the base + generic. + +--- + +## Validation gate (always, before reporting done) + +For **every** changed overlay path: + +```bash +kustomize build --enable-helm nowchess/ # renders clean +kustomize build --enable-helm nowchess/ | kubectl apply --dry-run=client -f - +``` + +Both must succeed for all three overlays (`eu-central-1-prod`, +`eu-central-1-staging`, `htwg-1-prod`). Fix and re-run until clean. Then report +the files touched and the overlays validated. Do not apply to a live cluster +unless explicitly asked — Argo CD syncs from `main`.