NATS — un Aggregate, due target, autenticazione facoltativa
Questo esempio compila un singolo server di messaggistica NATS (pub-sub, request-reply, accodamento) a partire da un unico Aggregate scritto dallo sviluppatore in due realizzazioni:
- Docker Compose per lo sviluppo locale, e
- la Recipe helm sintetizzata che esegue l’immagine upstream ufficiale
natsdirettamente su Kubernetes (nessun chart esterno).
La Recipe helm sintetizzata è il percorso Kubernetes preferito: dipende solo da un tag di immagine ufficiale anziché da un chart di terze parti, e il suo insieme di risorse renderizzato è esattamente ciò che dichiara il carico di lavoro.
Lo stesso aggregate.yaml guida entrambe. Per ogni realizzazione cambia solo il livello di Recipe selezionato dal Manifest. Un secondo Aggregate, aggregate-auth.yaml, mostra lo stesso server con una credenziale inject-value per la password associata per il percorso Compose; aggregate-helm-synth-auth.yaml associa una credenziale referenziabile per il percorso helm sintetizzato.
File
| File | Ruolo |
|---|---|
aggregate.yaml | Intento dello sviluppatore: un componente bus di tipo core/messaging/nats, nessuna credenziale — il server funziona senza autenticazione. |
aggregate-auth.yaml | Lo stesso server con una credenziale inject-value per la password associata allo slot facoltativo password del componente (percorso Compose). |
aggregate-helm-synth-auth.yaml | Lo stesso server con una credenziale referenziabile associata per il percorso helm sintetizzato — il valore viene materializzato come un Secret Kubernetes a cui fa riferimento il Deployment. |
manifest-compose.yaml | Mappa il tipo NATS sulla Recipe Compose (compose/nats) e la credenziale su dotenv-secret. |
manifest-helm-synth.yaml | Mappa il tipo NATS sulla Recipe helm sintetizzata (helm/nats) e la credenziale su k8s-secret-from-parameter. |
release-compose.yaml / release-helm-synth.yaml | Documenti dell’operatore per le due realizzazioni, nessuna autenticazione. |
release-compose-auth.yaml / release-helm-synth-auth.yaml | Documenti dell’operatore che abilitano l’autenticazione. |
Che cosa dimostra
- Un’unica superficie di authoring, molti target. Un unico Aggregate è la fonte di verità su che cosa è lo stack. Ogni Manifest dice come realizzarlo.
- Un server di messaggistica senza stato. In questa forma essenziale NATS instrada i subject in memoria con l’archiviazione su file di JetStream disabilitata, quindi il componente è tipizzato come
server. Su Kubernetes la Recipe sintetizzata renderizza un Deployment a replica singola senza alcun volume persistente; il servizio Compose espone il server per lo sviluppo locale. - Sintesi del Workload (Kubernetes). La Recipe helm sintetizzata dichiara un Workload — un Deployment più un Service ClusterIP che esegue l’immagine ufficiale
nats— che il provider helm traduce in manifest Kubernetes senza alcun chart esterno. L’insieme di risorse renderizzato è esattamente ciò che dichiara il Workload. Poiché il nomenatsè portato sia da una Recipe Compose sia da una helm sintetizzata, i Manifests vi fanno riferimento con ambito di provider comecompose/natsehelm/nats. - Autenticazione facoltativa, deterministica in ogni caso. L’autenticazione di NATS è disattivata per impostazione predefinita. Quando non è associata alcuna credenziale, nessuna delle due realizzazioni abilita l’autenticazione e il rendering è identico byte per byte tra un’esecuzione e l’altra. Quando è associata una credenziale, il valore iniettato abilita l’autenticazione utente/password su entrambe le realizzazioni.
Generare l’esempio
Puoi eseguire la build di questo esempio con i comandi qui sotto, oppure farla eseguire al tuo assistente IA.
Scrivi l’esempio in una nuova cartella che porta il suo nome:
aggrega scaffold --example nats-messagingPoi stampa i prossimi comandi da eseguire. Il primo ti porta nella nuova cartella:
cd nats-messagingBuild
Questo workspace non contiene alcun .aggrega-config.yaml, quindi le entità della libreria standard vengono risolte dal registry dell’hub, hub.aggrega.ai, e non serve alcun flag di catalogo; --auto-pull scrive durante il build il lockfile che manca a un clone appena creato:
# 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-pullGli artefatti renderizzati finiscono sotto dist/.
Con un assistente AI
Un assistente IA configurato con gli strumenti di Aggrega può fare lo stesso: incolla questo prompt nell’assistente.
Usa solo gli strumenti di Aggrega e non creare tu alcuna cartella. Se la cartella del workspace non contiene ancora una cartella `nats-messaging`, chiama una volta lo strumento `scaffold` con `example` impostato su `nats-messaging` e senza `dir`: scrive l’esempio in una nuova cartella `nats-messaging`. Poi chiama lo strumento `build` una volta per ogni Release, in questo ordine — `release-compose.yaml`, `release-helm-synth.yaml`, `release-compose-auth.yaml` e `release-helm-synth-auth.yaml` — ogni volta con `workspace_root` impostato su `nats-messaging`, `release` impostato su quel file, `auto_pull` impostato su true e `write` impostato su true. Dimmi quali file ha scritto ciascuna build; si trovano in `nats-messaging/dist/`.Nota sulla consegna delle credenziali
Sul percorso Compose la credenziale è un segreto inject-value (aggregate-auth.yaml): il suo valore viene consegnato sulla pipe d’ambiente del componente e il server viene avviato con i flag di autenticazione utente/password.
Il percorso helm sintetizzato usa una credenziale referenziabile (aggregate-helm-synth-auth.yaml): il valore viene materializzato come Secret Kubernetes, il Deployment vi fa riferimento tramite un secretKeyRef env, e il server viene avviato con i flag --user/--pass che leggono quella variabile d’ambiente. La password in chiaro quindi non compare mai nel manifest del Deployment — solo nel Secret.
Il valore origin negli Aggregates autenticati è un segnaposto di sviluppo; fornisci un valore reale tramite la tua sorgente di credenziali per qualsiasi distribuzione reale.