Communitygithub.com

Nuvraxis/nuvraxis-plugins

Reglas de Helm charts para aplicaciones Next.js de Nuvraxis — un chart por aplicación en charts/ (nombrado según la app), publicado en oci://ghcr.io/nuvraxis/charts y sincronizado por Argo CD; Chart.yaml version/appVersion establecidos solo por release.yaml; Deployment con sondas startup/liveness/readiness en /api/health, contexto de seguridad no root de solo lectura, emptyDir para .next/cache, ConfigMap + Secret existente mediante envFrom, Service, Ingress con cert-manager, HPA, PDB, ServiceAccount, distribución topológica; sin hooks de Helm; helm lint --strict + kubeconform. Úsalo cuando el repositorio tenga charts/, Chart.yaml, values*.yaml, templates/*.yaml con sintaxis Helm, o una aplicación Argo CD, o cuando se pida desplegar, escalar, exponer o configurar la app en Kubernetes.

¿Qué es nuvraxis-plugins?

Esta habilidad define un conjunto estandarizado de reglas para crear y gestionar Helm charts para aplicaciones Next.js en el ecosistema Nuvraxis. Su propósito principal es asegurar que cada aplicación tenga un único chart ubicado en `charts/<app>/`, publicado en un registro OCI (ghcr.io/nuvraxis/charts) y sincronizado por Argo CD, tanto para entornos de desarrollo (desde git) como de producción (desde el registro). La versión del chart y la imagen se gestionan exclusivamente mediante `release.yaml` a partir de la etiqueta git, evitando ediciones manuales. La habilidad detalla configuraciones de seguridad (no root, sistema de archivos de solo lectura), sondas de salud en `/api/health` (startup, liveness, readiness), uso de emptyDir para caché de Next.js, inyección de configuración mediante ConfigMap y Secret existente, alta disponibilidad con 2 réplicas, PDB y distribución topológica, e Ingress opcional con TLS mediante cert-manager. También prohíbe hooks de Helm, plantillas de secretos y valores aleatorios. Se aplica cuando el repositorio contiene `charts/`, `Chart.yaml`, `values*.yaml` y `templates/*.yaml` con sintaxis Helm, una aplicación Argo CD, o cuando se solicita desplegar, escalar, exponer o configurar la aplicación en Kubernetes. La validación se realiza con `helm lint --strict` y `helm template | kubeconform -strict`.

Compatible con~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/Nuvraxis/nuvraxis-plugins/tree/HEAD/plugins/nuvraxis-frontend/skills/helm-nextjs
Ver original→Ver todas las habilidades

Preguntar en tu IA favorita

Abre un nuevo chat con esta habilidad de agente ya precargada.

OpenAIChatGPTClaudeClaudeGeminiGeminiGrokGrokPerplexityPerplexityDeepSeekDeepSeek

Documentación

Chart de Helm para una app Next.js

Úsalo para charts/<app>/ y cómo Argo CD lo consume. La imagen que ejecuta proviene de docker-nextjs; el pipeline que publica ambos es github-actions.

La plantilla charts/__APP__/ es la fuente de verdad. Todos los valores comentados: references/values.md. Conexión con Argo CD: references/argocd.md.

Reglas

  1. Un chart por app, en charts/<app>/ dentro de la raíz del repositorio de la app. ¿Por qué ahí?: Argo CD puede sincronizarlo directamente desde git (path: charts/<app>) para un entorno de desarrollo y desde el registro OCI para producción, con los mismos archivos; está fuera de apps/, por lo que no está ni en el contexto de compilación de Docker ni en un paquete del workspace pnpm; y el chart cambia en el mismo PR que el código que lo necesita. El chart es intencionadamente de una sola app: sin umbrella, sin subcharts. Plantillas genéricas basadas en valores (como el chart umbrella de backend) solo donde una sola app necesita el cambio: ingress, HPA, PDB, distribución topológica.

  2. Nunca edites manualmente version o appVersion. Ambos permanecen como 0.0.0 en git. release.yaml ejecuta helm package --version X.Y.Z --app-version vX.Y.Z a partir de la etiqueta vX.Y.Z, por lo que el chart publicado y la etiqueta de la imagen siempre coinciden.

  3. image.tag por defecto es appVersion; establécelo solo para entornos sincronizados por git. Desde OCI, appVersion es la etiqueta de lanzamiento y la imagen es ghcr.io/nuvraxis/<app>:vX.Y.Z. Sincronizado desde git, appVersion es 0.0.0, por lo que la aplicación Argo CD establece image.tag: sha-<short-sha> (o main). image.repository siempre va en minúsculas.

  4. Sondas: startup, liveness y readiness, todas en /api/health. La sonda startup (2s × 30) cubre el arranque; liveness y readiness solo se inician después de ella. La ruta nunca toca una dependencia, por lo que una caída de la base de datos no reinicia los pods. No apuntes una sonda a /: renderiza una página.

  5. El contexto de seguridad coincide con la imagen: uid/gid 1001, runAsNonRoot, readOnlyRootFilesystem, sin escalado de privilegios, todas las capabilities eliminadas, seccomp RuntimeDefault. automountServiceAccountToken: false tanto en la ServiceAccount como en el pod: la app no llama a la API de Kubernetes.

  6. .next/cache es un emptyDir con sizeLimit. Es la única ruta de escritura (/app/apps/<app>/.next/cache). El límite evita que un caché de imágenes descontrolado llene el nodo.

  7. Configuración mediante envFrom: un ConfigMap desde values.config, y un Secret que ya existe.

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

    El chart nunca crea plantillas de valores secretos: no hay kind: Secret con data de valores, ni --set secret=…. El Secret es creado por External Secrets, Sealed Secrets o un operador, y solo su nombre está en los valores. Un cambio en el ConfigMap reinicia los pods mediante la anotación checksum/config.

  8. No uses NEXT_PUBLIC_* en el chart. Se incluyen en la compilación de la imagen (ver docker-nextjs); establecerlos en tiempo de ejecución no tiene efecto.

  9. Recursos: solicitudes de CPU y memoria, un límite de memoria, sin límite de CPU. Los límites de CPU estrangulan un servidor Node durante ráfagas e inflan la latencia de cola; el límite de memoria se mantiene porque el heap de Node crece hasta lo que se le asigna.

  10. Alta disponibilidad por defecto: 2 réplicas, PDB maxUnavailable: 1, actualización progresiva con maxUnavailable: 0, distribución topológica entre zonas y nodos (ScheduleAnyway). Con autoscaling.enabled el Deployment omite replicas, por lo que Argo CD y el HPA no compiten por ello.

  11. Ingress es opcional, TLS mediante anotaciones de cert-manager. ingress.enabled, className, hosts, tls con secretName, y cert-manager.io/cluster-issuer en anotaciones. Para respuestas en streaming en ingress-nginx añade nginx.ingress.kubernetes.io/proxy-buffering: "off"; para limitación de tasa, limit-rps (ver nextjs-security).

  12. Sin hooks de Helm, sin lookup, sin valores aleatorios. Argo CD renderiza el chart con helm template y aplica el resultado: los hooks se convierten en hooks de Argo con semántica diferente, lookup no devuelve nada, y randAlphaNum cambia en cada sincronización y muestra la app permanentemente desincronizada. Todo lo renderizado debe ser una función pura de los valores.

  13. Los paquetes privados de GHCR necesitan credenciales de pull. Los paquetes GHCR son privados al primer push. Para imágenes: un Secret docker-registry con un token que tenga read:packages, referenciado en imagePullSecrets (los valores de producción referencian ghcr-pull). Para el chart en Argo CD: un Secret de repositorio con enableOCI: "true" (ver references/argocd.md). O haz los paquetes públicos en GitHub si el código es público.

  14. values-production.yaml contiene solo lo que difiere en producción. Capa: -f values.yaml -f values-production.yaml. No copies los valores por defecto en él.

  15. Valida con helm lint --strict y helm template | kubeconform -strict. ¿Por qué kubeconform en lugar de helm-unittest?: los errores que realmente tiene un chart de una sola app son nombres de campo, tipos o versiones de API incorrectos en la salida renderizada, que kubeconform detecta contra los esquemas reales de Kubernetes sin código de prueba. helm-unittest afirma lógica de plantillas, que este chart apenas tiene. Lint y valida ambos archivos de valores, como hace pr.yaml.

Añadir cosas

NecesidadCambio
Una variable de entorno en tiempo de ejecuciónconfig: en valores (no secreto) o una clave en el Secret existente
Un secretoañádelo al Secret externo; nada en el chart cambia
Otro puerto o sidecarjustifícalo primero; una app Next necesita un puerto
Un cron jobun chart o app separados, no este Deployment
NetworkPolicyañade templates/networkpolicy.yaml, activado por networkPolicy.enabled

Verificar

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 -

Fuentes

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.

Skills relacionados

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