Communitygithub.com

Nuvraxis/nuvraxis-plugins

Helm-Chart-Regeln für Nuvraxis Next.js-Apps – ein Chart pro App in charts/ (benannt nach der App), veröffentlicht auf oci://ghcr.io/nuvraxis/charts und synchronisiert von Argo CD; Chart.yaml version/appVersion werden nur von release.yaml gesetzt; Deployment mit Startup/Liveness/Readiness-Probes auf /api/health, nicht-root, read-only Security Context, emptyDir für .next/cache, ConfigMap + vorhandenes Secret via envFrom, Service, Ingress mit cert-manager, HPA, PDB, ServiceAccount, Topology Spread; keine Helm-Hooks; helm lint --strict + kubeconform. Verwende dies, wenn das Repository charts/, Chart.yaml, values*.yaml, templates/*.yaml mit Helm-Syntax enthält, oder eine Argo CD Application, oder wenn darum gebeten wird, die App auf Kubernetes bereitzustellen, zu skalieren, zu exponieren oder zu konfigurieren.

Was ist nuvraxis-plugins?

Diese Skill definiert eine strikte Vorlage und Regeln für Helm-Charts von Next.js-Anwendungen, die mit Nuvraxis und Argo CD betrieben werden. Der Fokus liegt auf einem einzigen Chart pro Anwendung im Verzeichnis `charts/<app>/`. Versionierung und AppVersion werden zentral in der CI/CD-Pipeline (release.yaml) gesteuert, nicht manuell in der Chart.yaml. Das Chart enthält fertige Kubernetes-Manifeste für Deployment, Service, Ingress (mit cert-manager), HPA, PDB, ServiceAccount und Topology Spread Constraints. Es zwingt zu einem sicheren und optimierten Standard: nicht-root, read-only Root Filesystem, keine CPU-Limits, Probes auf `/api/health` (nicht auf `/`), Konfiguration über ConfigMap und ein extern existierendes Secret. Argo CD synchronisiert das Chart entweder direkt aus Git oder aus einem OCI-Registry. Die Skill validiert die Charts mit `helm lint --strict` und überprüft die generierten YAML-Dateien mit kubeconform gegen reale Kubernetes-Schemata, anstatt Unit-Tests der Template-Logik durchzuführen. Empfohlen wird diese Skill, wenn ein Repository eine Helm-Chart-Struktur mitbringt oder wenn eine Next.js-App auf Kubernetes deployed und gemanagt werden soll.

Funktioniert mit~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/Nuvraxis/nuvraxis-plugins/tree/HEAD/plugins/nuvraxis-frontend/skills/helm-nextjs
Original anzeigen→Alle Skills durchsuchen

In Ihrer bevorzugten KI fragen

Öffnet einen neuen Chat, in dem dieser Agent-Skill bereits geladen ist.

OpenAIChatGPTClaudeClaudeGeminiGeminiGrokGrokPerplexityPerplexityDeepSeekDeepSeek

Dokumentation

Helm-Chart für eine Next.js-App

Verwende für charts/<app>/ und wie Argo CD es konsumiert. Das ausgeführte Image stammt von docker-nextjs; die Pipeline, die beides veröffentlicht, ist github-actions.

Das Vorlagenverzeichnis charts/__APP__/ ist die Quelle der Wahrheit. Alle Werte mit Kommentaren: references/values.md. Argo CD-Verdrahtung: references/argocd.md.

Regeln

  1. Ein Chart pro App im Pfad charts/<app>/ im Stammverzeichnis des App-Repositorys. Warum dort: Argo CD kann es direkt von Git synchronisieren (path: charts/<app>) für eine Entwicklungsumgebung und aus der OCI-Registry für die Produktion, mit den gleichen Dateien; es liegt außerhalb von apps/, ist also weder im Docker-Build-Kontext noch ein pnpm-Workspace-Paket; und das Chart ändert sich im selben PR wie der dazugehörige Code. Das Chart ist absichtlich als Einzel-App konzipiert: kein Umbrella, keine Subcharts. Generische, wertegesteuerte Vorlagen (wie das Backend-Umbrella-Chart) nur dort, wo eine einzelne App den Schalter benötigt: Ingress, HPA, PDB, Topology Spread.

  2. version oder appVersion niemals von Hand bearbeiten. Beide bleiben 0.0.0 in Git. release.yaml führt helm package --version X.Y.Z --app-version vX.Y.Z aus dem Tag vX.Y.Z aus, sodass das veröffentlichte Chart und der Image-Tag immer übereinstimmen.

  3. image.tag hat als Standardwert appVersion; setze es nur für git-synchronisierte Umgebungen. Aus der OCI ist appVersion der Release-Tag und das Image ist ghcr.io/nuvraxis/<app>:vX.Y.Z. Aus Git synchronisiert ist appVersion 0.0.0, daher setzt die Argo CD Application image.tag: sha-<short-sha> (oder main). image.repository ist immer klein geschrieben.

  4. Probes: Startup, Liveness und Readiness, alle auf /api/health. Der Startup-Probe (2s × 30) deckt den Boot ab; Liveness und Readiness starten erst danach. Die Route berührt niemals eine Abhängigkeit, sodass ein Datenbankausfall keine Pods neu startet. Zeige einen Probe nicht auf /: das rendert eine Seite.

  5. Der Security Context entspricht dem Image: uid/gid 1001, runAsNonRoot, readOnlyRootFilesystem, keine Privilege Escalation, alle Capabilities entfernt, RuntimeDefault seccomp. automountServiceAccountToken: false sowohl beim ServiceAccount als auch beim Pod: Die App ruft keine Kubernetes-API auf.

  6. .next/cache ist ein emptyDir mit einem sizeLimit. Es ist der einzige beschreibbare Pfad (/app/apps/<app>/.next/cache). Das Limit verhindert, dass ein ausufernder Image-Cache den Knoten füllt.

  7. Konfiguration über envFrom: eine ConfigMap aus values.config, und ein bereits vorhandenes Secret.

    config:
  API_BASE_URL: https://api.nuvraxis.com
existingSecret: portal-secrets

    Das Chart templatet niemals Secret-Werte: kein kind: Secret mit data aus values, kein --set secret=…. Das Secret wird von External Secrets, Sealed Secrets oder einem Operator erstellt, und nur sein Name steht in den values. Eine ConfigMap-Änderung rollt die Pods über die Annotation checksum/config neu.

  8. Keine NEXT_PUBLIC_* im Chart. Sie werden beim Image-Build eingebrannt (siehe docker-nextjs); sie zur Laufzeit zu setzen, bewirkt nichts.

  9. Ressourcen: Requests für CPU und Speicher, ein Speicher-Limit, kein CPU-Limit. CPU-Limits drosseln einen Node-Server während Lastspitzen und erhöhen die Tail-Latenz; das Speicher-Limit bleibt, weil der Node-Heap auf das wächst, was ihm gegeben wird.

  10. Hohe Verfügbarkeit standardmäßig: 2 Replicas, PDB maxUnavailable: 1, Rolling Update mit maxUnavailable: 0, Topology Spread über Zonen und Nodes (ScheduleAnyway). Mit autoscaling.enabled lässt das Deployment replicas weg, sodass Argo CD und der HPA sich nicht darum streiten.

  11. Ingress ist optional, TLS über cert-manager-Annotationen. ingress.enabled, className, hosts, tls mit einem secretName und cert-manager.io/cluster-issuer in den Annotationen. Für Streaming-Antworten auf ingress-nginx füge nginx.ingress.kubernetes.io/proxy-buffering: "off" hinzu; für Ratenbegrenzung limit-rps (siehe nextjs-security).

  12. Keine Helm-Hooks, kein lookup, keine zufälligen Werte. Argo CD rendert das Chart mit helm template und wendet das Ergebnis an: Hooks werden zu Argo-Hooks mit anderer Semantik, lookup gibt nichts zurück, und randAlphaNum ändert sich bei jeder Synchronisierung und zeigt die App dauerhaft als nicht synchronisiert an. Alles, was gerendert wird, muss eine reine Funktion der Werte sein.

  13. Private GHCR-Pakete benötigen Pull-Berechtigungen. GHCR-Pakete sind beim ersten Push privat. Für Images: ein docker-registry-Secret mit einem Token, das read:packages hat, referenziert in imagePullSecrets (Produktionswerte referenzieren ghcr-pull). Für das Chart in Argo CD: ein Repository-Secret mit enableOCI: "true" (siehe references/argocd.md). Oder mache die Pakete in GitHub öffentlich, wenn der Code öffentlich ist.

  14. values-production.yaml enthält nur, was in der Produktion anders ist. Schichte es: -f values.yaml -f values-production.yaml. Kopiere nicht die Standardwerte hinein.

  15. Validiere mit helm lint --strict und helm template | kubeconform -strict. Warum kubeconform statt helm-unittest: Die Fehler, die ein Einzel-App-Chart tatsächlich hat, sind falsche Feldnamen, Typen oder API-Versionen in der gerenderten Ausgabe, was kubeconform gegen die realen Kubernetes-Schemata ohne Testcode erkennt. helm-unittest testet die Template-Logik, die dieses Chart kaum hat. Lint und validiere beide Werte-Dateien, wie pr.yaml es tut.

Hinzufügen von Dingen

BedarfÄnderung
Eine Runtime-Umgebungsvariableconfig: in values (nicht geheim) oder ein Schlüssel im vorhandenen Secret
Ein GeheimnisFüge es dem externen Secret hinzu; im Chart ändert sich nichts
Ein weiterer Port oder SidecarBegründe es zuerst; eine Next-App benötigt einen Port
Ein Cron-JobEin separates Chart oder eine separate App, nicht dieses Deployment
NetworkPolicyFüge templates/networkpolicy.yaml hinzu, umschaltbar über networkPolicy.enabled

Überprüfen

helm lint --strict charts/<app>
helm lint --strict charts/<app> -f charts/<app>/values-production.yaml
helm template <app> charts/<app> -f charts/<app>/values-production.yaml \
  | docker run --rm -i ghcr.io/yannh/kubeconform:v0.8.0 -strict -summary -kubernetes-version 1.34.0 -

Quellen

Individual skills in this repo

This repo contains 4 individual skills — each has its own dedicated page.

Nuvraxis/nuvraxis-plugins

>- Biome 2.5 setup and rules for Nuvraxis monorepos — root biome.json with pinned $schema, VCS ignore, formatter settings, the recommended preset with a11y and the react/next domains, nursery policy, organize imports, overrides, nested per-package configs ("extends": "//"), biome check --write locally, biome ci in CI, VS Code settings, and migrating from ESLint/Prettier. Use when the repo has biome.json or biome.jsonc, @biomejs/biome in package.json, .eslintrc*/eslint.config.*/.prettierrc* to migrate, or when fixing lint and formatting errors.

Nuvraxis/nuvraxis-plugins

>- Dockerfile rules for Next.js standalone apps in a pnpm + Turborepo monorepo — multi-stage build (turbo prune → pnpm fetch/offline install → turbo build → minimal runner), pinned Node 26 Alpine by digest, checksum-verified pnpm binary, non-root uid 1001, read-only root filesystem with a writable .next/cache, HEALTHCHECK on /api/health, build args only for NEXT_PUBLIC_* values, BuildKit secrets and cache mounts, multi-arch, OCI labels and .dockerignore. Use when the repo has a Dockerfile, .dockerignore, compose file, or next.config with output "standalone", or when asked to containerise, shrink, harden or debug an image.

Nuvraxis/nuvraxis-plugins

>- GitHub Actions conventions for Nuvraxis Next.js apps — exactly three workflows: pr.yaml (every PR to any branch: Biome, stylelint, typecheck/test/build with turbo --affected, Docker build + health check, helm lint + kubeconform; publishes nothing), main.yaml (push to main: one multi-arch image to GHCR tagged sha-SHORTSHA and main, provenance + SBOM, gha cache), release.yaml (tag vX.Y.Z: verify on main, retag the existing image without rebuilding, package and push the Helm chart to OCI, GitHub Release with chart, digest and SBOM). Minimal permissions per job, GITHUB_TOKEN only, pinned action majors. Use when editing .github/workflows/*, adding a CI step, or debugging a failed run or release.

Nuvraxis/nuvraxis-plugins

>- Production rules for Next.js 16 App Router apps at Nuvraxis — Server/Client Component boundaries, Cache Components ("use cache", cacheLife, cacheTag, updateTag), Server Actions, route handlers, env handling, instrumentation, output standalone and the /api/health route. Use when the project has "next" in package.json, an app/ or src/app/ directory, next.config.ts, proxy.ts, instrumentation.ts, or files named page.tsx, layout.tsx, route.ts, loading.tsx, error.tsx.

Verwandte Skills

steipete/sag

ElevenLabs text-to-speech with mac-style say UX.

community

steipete/oracle

Oracle CLI second-model review/debug/refactor/design with selected files, dry-run token checks, API or browser engine.

community

steipete/peekaboo

Capture and automate macOS UI with the Peekaboo CLI.

community

mattpocock/design-an-interface

Generate multiple radically different interface designs for a module using parallel sub-agents. Use when user wants to design an API, explore interface options, compare module shapes, or mentions "design it twice".

community

mattpocock/prototype

Build a throwaway prototype to flesh out a design — a runnable terminal app for state/business-logic questions, or several radically different UI variations toggleable from one route.

community

mattpocock/grill-me

Interview the user relentlessly about a plan or design until reaching shared understanding, resolving each branch of the decision tree. Use when user wants to stress-test a plan, get grilled on their design, or mentions "grill me".

community