Ir al contenido
AggregaAggrega
Seleccionar idioma: Español
Esta página se tradujo automáticamente. Lee el original en inglés.

NATS — un Aggregate, dos destinos, autenticación opcional

Este ejemplo compila un único servidor de mensajería NATS (pub-sub, request-reply, colas) a partir de un único Aggregate escrito por el desarrollador a dos realizaciones:

  • Docker Compose para el desarrollo local, y
  • la Recipe helm sintetizada que ejecuta la imagen upstream oficial nats directamente en Kubernetes (sin chart externo).

La Recipe helm sintetizada es la ruta preferida de Kubernetes: depende solo de un tag de imagen oficial en lugar de un chart de terceros, y su conjunto de recursos renderizado es exactamente lo que declara la carga de trabajo.

El mismo aggregate.yaml impulsa ambas. Solo cambia por realización la capa de Recipe que selecciona el Manifest. Un segundo Aggregate, aggregate-auth.yaml, muestra el mismo servidor con una credencial de contraseña inject-value vinculada para la ruta de Compose; aggregate-helm-synth-auth.yaml vincula una credencial referenciable para la ruta helm sintetizada.

Archivos

ArchivoRol
aggregate.yamlIntención del desarrollador: un componente bus de tipo core/messaging/nats, sin credencial — el servidor funciona sin autenticación.
aggregate-auth.yamlEl mismo servidor con una credencial de contraseña inject-value vinculada al slot opcional password del componente (ruta de Compose).
aggregate-helm-synth-auth.yamlEl mismo servidor con una credencial referenciable vinculada para la ruta helm sintetizada — el valor se materializa como un Secret de Kubernetes al que hace referencia el Deployment.
manifest-compose.yamlAsigna el tipo NATS a la Recipe de Compose (compose/nats) y la credencial a dotenv-secret.
manifest-helm-synth.yamlAsigna el tipo NATS a la Recipe helm sintetizada (helm/nats) y la credencial a k8s-secret-from-parameter.
release-compose.yaml / release-helm-synth.yamlDocumentos del operador para las dos realizaciones, sin autenticación.
release-compose-auth.yaml / release-helm-synth-auth.yamlDocumentos del operador que habilitan la autenticación.

Lo que demuestra

  • Una única superficie de autoría, muchos destinos. Un único Aggregate es la fuente de verdad sobre qué es el stack. Cada Manifest dice cómo realizarlo.
  • Un servidor de mensajería sin estado. En esta forma mínima, NATS enruta los subjects en memoria con el almacenamiento en archivos de JetStream deshabilitado, así que el componente se tipa como server. En Kubernetes la Recipe sintetizada renderiza un Deployment de una sola réplica sin volumen persistente; el servicio de Compose expone el servidor para el desarrollo local.
  • Síntesis de Workload (Kubernetes). La Recipe helm sintetizada declara un Workload — un Deployment más un Service ClusterIP que ejecuta la imagen oficial nats — que el proveedor helm traduce a manifiestos de Kubernetes sin ningún chart externo. El conjunto de recursos renderizado es exactamente lo que declara el Workload. Como el nombre nats lo llevan tanto una Recipe de Compose como una helm sintetizada, los Manifests las referencian con ámbito de proveedor como compose/nats y helm/nats.
  • Autenticación opcional, determinista en cualquier caso. La autenticación de NATS está desactivada de forma predeterminada. Cuando no hay ninguna credencial vinculada, ninguna de las dos realizaciones habilita la autenticación y el renderizado es idéntico byte a byte entre ejecuciones. Cuando hay una credencial vinculada, el valor inyectado habilita la autenticación de usuario/contraseña en ambas realizaciones.

Generar el ejemplo

Puedes compilar este ejemplo con los comandos de abajo, o hacer que tu asistente de IA lo compile por ti.

Escribe el ejemplo en una carpeta nueva con su nombre:

Terminal window
aggrega scaffold --example nats-messaging

Después imprime los comandos que hay que ejecutar a continuación. El primero entra en la carpeta nueva:

Terminal window
cd nats-messaging

Compilación

Este workspace no lleva ningún .aggrega-config.yaml, así que las entidades de la biblioteca estándar se resuelven desde el registro del hub, hub.aggrega.ai, y no se necesita ningún flag de catálogo; --auto-pull escribe durante la compilación el lockfile que le falta a un clon recién creado:

Terminal window
# Local development (Docker Compose), no authentication
aggrega build --release release-compose.yaml --auto-pull
# Kubernetes (synthesized helm Recipe, official image), no authentication
aggrega build --release release-helm-synth.yaml --auto-pull
# The same realizations with authentication enabled
aggrega build --release release-compose-auth.yaml --auto-pull
aggrega build --release release-helm-synth-auth.yaml --auto-pull

Los artefactos renderizados quedan en dist/.

Con un asistente de IA

Un asistente de IA configurado con las herramientas de Aggrega puede hacer lo mismo: pégale este prompt.

Usa solo las herramientas de Aggrega y no crees tú ninguna carpeta. Si la carpeta del espacio de trabajo aún no contiene una carpeta `nats-messaging`, llama una vez a la herramienta `scaffold` con `example` establecido en `nats-messaging` y sin `dir`: escribe el ejemplo en una nueva carpeta `nats-messaging`. Después llama a la herramienta `build` una vez por cada Release, en este orden — `release-compose.yaml`, `release-helm-synth.yaml`, `release-compose-auth.yaml` y `release-helm-synth-auth.yaml` —, cada vez con `workspace_root` establecido en `nats-messaging`, `release` establecido en ese archivo, `auto_pull` establecido en true y `write` establecido en true. Dime qué archivos escribió cada compilación; están en `nats-messaging/dist/`.

Nota sobre la entrega de credenciales

En la ruta de Compose la credencial es un secreto inject-value (aggregate-auth.yaml): su valor se entrega por la tubería de entorno del componente y el servidor se inicia con flags de autenticación de usuario/contraseña.

La ruta helm sintetizada usa una credencial referenciable (aggregate-helm-synth-auth.yaml): el valor se materializa como un Secret de Kubernetes, el Deployment hace referencia a él mediante un secretKeyRef de entorno, y el servidor se inicia con los flags --user/--pass que leen esa variable de entorno. Por tanto, la contraseña en texto plano nunca aparece en el manifiesto del Deployment — solo en el Secret.

El valor origin de los Aggregates autenticados es un marcador de posición de desarrollo; proporciona un valor real a través de tu fuente de credenciales para cualquier despliegue real.