NATS — un Aggregate, deux cibles, authentification facultative
Cet exemple compile un seul serveur de messagerie NATS (pub-sub, request-reply, mise en file d’attente) à partir d’un seul Aggregate écrit par le développeur en deux réalisations :
- Docker Compose pour le développement local, et
- la Recipe helm synthétisée qui exécute l’image upstream officielle
natsdirectement sur Kubernetes (aucun chart externe).
La Recipe helm synthétisée est le chemin Kubernetes privilégié : elle ne dépend que d’un tag d’image officiel plutôt que d’un chart tiers, et son ensemble de ressources rendu est exactement ce que déclare la charge de travail.
Le même aggregate.yaml pilote les deux. Seule la couche de Recipe sélectionnée par le Manifest change d’une réalisation à l’autre. Un second Aggregate, aggregate-auth.yaml, montre le même serveur avec une information d’identification inject-value de mot de passe rattachée pour le chemin Compose ; aggregate-helm-synth-auth.yaml rattache une information d’identification référençable pour le chemin helm synthétisé.
Fichiers
| Fichier | Rôle |
|---|---|
aggregate.yaml | Intention du développeur : un composant bus de type core/messaging/nats, sans information d’identification — le serveur s’exécute sans authentification. |
aggregate-auth.yaml | Le même serveur avec une information d’identification inject-value de mot de passe rattachée au slot facultatif password du composant (chemin Compose). |
aggregate-helm-synth-auth.yaml | Le même serveur avec une information d’identification référençable rattachée pour le chemin helm synthétisé — la valeur est matérialisée sous forme d’un Secret Kubernetes que référence le Deployment. |
manifest-compose.yaml | Associe le type NATS à la Recipe Compose (compose/nats) et l’information d’identification à dotenv-secret. |
manifest-helm-synth.yaml | Associe le type NATS à la Recipe helm synthétisée (helm/nats) et l’information d’identification à k8s-secret-from-parameter. |
release-compose.yaml / release-helm-synth.yaml | Documents de l’opérateur pour les deux réalisations, sans authentification. |
release-compose-auth.yaml / release-helm-synth-auth.yaml | Enregistrements de l’opérateur qui activent l’authentification. |
Ce qu’il démontre
- Une seule surface de rédaction, plusieurs cibles. Un seul Aggregate est la source de vérité sur ce qu’est la stack. Chaque Manifest dit comment la réaliser.
- Un serveur de messagerie sans état. Dans cette forme minimale, NATS achemine les subjects en mémoire avec le stockage sur fichier de JetStream désactivé, si bien que le composant est typé comme un
server. Sur Kubernetes, la Recipe synthétisée rend un Deployment à réplique unique sans volume persistant ; le service Compose expose le serveur pour le développement local. - Synthèse de Workload (Kubernetes). La Recipe helm synthétisée déclare un Workload — un Deployment plus un Service ClusterIP exécutant l’image officielle
nats— que le fournisseur helm traduit en manifestes Kubernetes sans aucun chart externe. L’ensemble de ressources rendu est exactement ce que déclare le Workload. Comme le nomnatsest porté à la fois par une Recipe Compose et par une helm synthétisée, les Manifests les référencent avec une portée de fournisseur sous les nomscompose/natsethelm/nats. - Authentification facultative, déterministe dans tous les cas. L’authentification de NATS est désactivée par défaut. Lorsqu’aucune information d’identification n’est rattachée, aucune des deux réalisations n’active l’authentification et le rendu est identique octet par octet d’une exécution à l’autre. Lorsqu’une information d’identification est rattachée, la valeur injectée active l’authentification utilisateur/mot de passe sur les deux réalisations.
Générer l’exemple
Vous pouvez construire cet exemple avec les commandes ci-dessous, ou le faire construire pour vous par votre assistant IA.
Écrivez l’exemple dans un nouveau dossier qui porte son nom :
aggrega scaffold --example nats-messagingElle affiche ensuite les prochaines commandes à exécuter. La première vous place dans le nouveau dossier :
cd nats-messagingBuild
Ce workspace ne contient aucun .aggrega-config.yaml, si bien que les entités de la bibliothèque standard sont résolues depuis le registre du hub, hub.aggrega.ai, et aucune option de catalogue n’est nécessaire ; --auto-pull écrit pendant le build le lockfile qui manque à un clone récent :
# 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-pullLes artefacts rendus atterrissent sous dist/.
Avec un assistant IA
Un assistant IA configuré avec les outils d’Aggrega peut faire de même : collez-lui ce prompt.
Utilisez uniquement les outils Aggrega et ne créez vous-même aucun dossier. Si le dossier de l’espace de travail ne contient pas encore de dossier `nats-messaging`, appelez une fois l’outil `scaffold` avec `example` défini sur `nats-messaging` et sans `dir` : il écrit l’exemple dans un nouveau dossier `nats-messaging`. Appelez ensuite l’outil `build` une fois pour chaque Release, dans cet ordre — `release-compose.yaml`, `release-helm-synth.yaml`, `release-compose-auth.yaml` et `release-helm-synth-auth.yaml` —, chaque fois avec `workspace_root` défini sur `nats-messaging`, `release` défini sur ce fichier, `auto_pull` défini sur true et `write` défini sur true. Indiquez-moi quels fichiers chaque build a écrits ; ils se trouvent sous `nats-messaging/dist/`.Note sur la livraison des informations d’identification
Sur le chemin Compose, l’information d’identification est un secret inject-value (aggregate-auth.yaml) : sa valeur est livrée sur le pipe d’environnement du composant et le serveur est démarré avec des flags d’authentification utilisateur/mot de passe.
Le chemin helm synthétisé utilise une information d’identification référençable (aggregate-helm-synth-auth.yaml) : la valeur est matérialisée sous forme de Secret Kubernetes, le Deployment la référence via un secretKeyRef d’environnement, et le serveur est démarré avec les flags --user/--pass qui lisent cette variable d’environnement. Le mot de passe en clair n’apparaît donc jamais dans le manifeste du Deployment — seulement dans le Secret.
La valeur origin dans les Aggregates authentifiés est un espace réservé de développement ; fournissez une valeur réelle via votre source d’informations d’identification pour tout déploiement réel.