NATS — um Aggregate, dois destinos, autenticação opcional
Este exemplo compila um único servidor de mensageria NATS (pub-sub, request-reply, filas) a partir de um único Aggregate escrito pelo desenvolvedor para duas realizações:
- Docker Compose para o desenvolvimento local, e
- a Recipe helm sintetizada que executa a imagem upstream oficial
natsdiretamente no Kubernetes (sem chart externo).
A Recipe helm sintetizada é o caminho preferido do Kubernetes: ela depende apenas de uma tag de imagem oficial em vez de um chart de terceiros, e o seu conjunto de recursos renderizado é exatamente o que a carga de trabalho declara.
O mesmo aggregate.yaml conduz ambas. Só muda por realização a camada de Recipe selecionada pelo Manifest. Um segundo Aggregate, aggregate-auth.yaml, mostra o mesmo servidor com uma credencial de senha inject-value vinculada para o caminho do Compose; aggregate-helm-synth-auth.yaml vincula uma credencial referenciável para o caminho helm sintetizado.
Arquivos
| Arquivo | Papel |
|---|---|
aggregate.yaml | Intenção do desenvolvedor: um componente bus do tipo core/messaging/nats, sem credencial — o servidor roda sem autenticação. |
aggregate-auth.yaml | O mesmo servidor com uma credencial de senha inject-value vinculada ao slot opcional password do componente (caminho do Compose). |
aggregate-helm-synth-auth.yaml | O mesmo servidor com uma credencial referenciável vinculada para o caminho helm sintetizado — o valor é materializado como um Secret do Kubernetes que o Deployment referencia. |
manifest-compose.yaml | Mapeia o tipo NATS para a Recipe do Compose (compose/nats) e a credencial para dotenv-secret. |
manifest-helm-synth.yaml | Mapeia o tipo NATS para a Recipe helm sintetizada (helm/nats) e a credencial para k8s-secret-from-parameter. |
release-compose.yaml / release-helm-synth.yaml | Documentos do operador para as duas realizações, sem autenticação. |
release-compose-auth.yaml / release-helm-synth-auth.yaml | Documentos do operador que habilitam a autenticação. |
O que ele demonstra
- Uma única superfície de autoria, muitos destinos. Um único Aggregate é a fonte da verdade sobre o que o stack é. Cada Manifest diz como realizá-lo.
- Um servidor de mensageria sem estado. Nesta forma enxuta, o NATS roteia subjects na memória com o armazenamento em arquivo do JetStream desabilitado, então o componente é tipado como
server. No Kubernetes, a Recipe sintetizada renderiza um Deployment de réplica única sem volume persistente; o serviço do Compose expõe o servidor para o desenvolvimento local. - Síntese de Workload (Kubernetes). A Recipe helm sintetizada declara um Workload — um Deployment mais um Service ClusterIP que executa a imagem oficial
nats— que o provedor helm traduz em manifestos do Kubernetes sem nenhum chart externo. O conjunto de recursos renderizado é exatamente o que o Workload declara. Como o nomenatsé usado tanto por uma Recipe do Compose quanto por uma helm sintetizada, os Manifests as referenciam com escopo de provedor comocompose/natsehelm/nats. - Autenticação opcional, determinística em qualquer caso. A autenticação do NATS vem desligada por padrão. Quando nenhuma credencial está vinculada, nenhuma das duas realizações habilita a autenticação e a renderização é idêntica byte a byte entre execuções. Quando uma credencial está vinculada, o valor injetado habilita a autenticação por usuário/senha nas duas realizações.
Gerar o exemplo
Você pode fazer o build deste exemplo com os comandos abaixo, ou pedir ao seu assistente de IA que faça o build por você.
Escreva o exemplo em uma nova pasta com o nome dele:
aggrega scaffold --example nats-messagingEm seguida ele imprime os próximos comandos a executar. O primeiro entra na pasta nova:
cd nats-messagingBuild
Este workspace não traz nenhum .aggrega-config.yaml, então as entidades da biblioteca padrão são resolvidas a partir do registro do hub, hub.aggrega.ai, e nenhuma flag de catálogo é necessária; --auto-pull escreve durante o build o lockfile que falta a um clone novo:
# Local development (Docker Compose), no authenticationaggrega build --release release-compose.yaml --auto-pull
# Kubernetes (synthesized helm Recipe, official image), no authenticationaggrega build --release release-helm-synth.yaml --auto-pull
# The same realizations with authentication enabledaggrega build --release release-compose-auth.yaml --auto-pullaggrega build --release release-helm-synth-auth.yaml --auto-pullOs artefatos renderizados ficam em dist/.
Com um assistente de IA
Um assistente de IA configurado com as ferramentas do Aggrega pode fazer o mesmo: cole este prompt nele.
Use somente as ferramentas do Aggrega e não crie nenhuma pasta você mesmo. Se a pasta do workspace ainda não contiver uma pasta `nats-messaging`, chame a ferramenta `scaffold` uma vez com `example` definido como `nats-messaging` e sem `dir`: ela grava o exemplo em uma nova pasta `nats-messaging`. Depois chame a ferramenta `build` uma vez para cada Release, nesta ordem — `release-compose.yaml`, `release-helm-synth.yaml`, `release-compose-auth.yaml` e `release-helm-synth-auth.yaml` —, cada vez com `workspace_root` definido como `nats-messaging`, `release` definido como esse arquivo, `auto_pull` definido como true e `write` definido como true. Diga-me quais arquivos cada build gravou; eles ficam em `nats-messaging/dist/`.Nota sobre a entrega da credencial
No caminho do Compose, a credencial é um segredo inject-value (aggregate-auth.yaml): o seu valor é entregue no pipe de ambiente do componente e o servidor é iniciado com flags de autenticação por usuário/senha.
O caminho helm sintetizado usa uma credencial referenciável (aggregate-helm-synth-auth.yaml): o valor é materializado como um Secret do Kubernetes, o Deployment o referencia por meio de um secretKeyRef de ambiente, e o servidor é iniciado com os flags --user/--pass que leem essa variável de ambiente. Por isso, a senha em texto puro nunca aparece no manifesto do Deployment — apenas no Secret.
O valor origin nos Aggregates autenticados é um espaço reservado de desenvolvimento; forneça um valor real por meio da sua fonte de credenciais em qualquer implantação real.