Skip to content
AggregaAggrega
Select language: English

NATS — one Aggregate, two targets, optional authentication

This example compiles a single NATS messaging server (pub-sub, request-reply, queueing) from one Developer-authored Aggregate to two realizations:

  • Docker Compose for local development, and
  • the synthesized helm Recipe running the official upstream nats image directly on Kubernetes (no external chart).

The synthesized helm Recipe is the preferred Kubernetes path: it depends only on an official image tag rather than a third-party chart, and its rendered resource set is exactly what the workload declares.

The same aggregate.yaml drives both. Only the Recipe layer selected by the Manifest changes per realization. A second Aggregate, aggregate-auth.yaml, shows the same server with an inject-value password credential attached for the Compose path; aggregate-helm-synth-auth.yaml attaches a referenceable credential for the synthesized helm path.

Files

FileRole
aggregate.yamlDeveloper intent: one bus component of type core/messaging/nats, no credential — the server runs without authentication.
aggregate-auth.yamlThe same server with an inject-value password credential attached to the component’s optional password slot (Compose path).
aggregate-helm-synth-auth.yamlThe same server with a referenceable credential attached for the synthesized helm path — the value is materialized as a Kubernetes Secret the Deployment references.
manifest-compose.yamlMaps the NATS type to the Compose Recipe (compose/nats) and the credential to dotenv-secret.
manifest-helm-synth.yamlMaps the NATS type to the synthesized helm Recipe (helm/nats) and the credential to k8s-secret-from-parameter.
release-compose.yaml / release-helm-synth.yamlOperator records for the two realizations, no authentication.
release-compose-auth.yaml / release-helm-synth-auth.yamlOperator records that enable authentication.

What it demonstrates

  • One authoring surface, many targets. A single Aggregate is the source of truth for what the stack is. Each Manifest says how to realize it.
  • A stateless messaging server. In this lean shape NATS routes subjects in memory with JetStream file storage disabled, so the component is typed as a server. On Kubernetes the synthesized Recipe renders a single-replica Deployment with no persistent volume; the Compose service exposes the server for local development.
  • Workload synthesis (Kubernetes). The synthesized helm Recipe declares a Workload — a Deployment plus a ClusterIP Service running the official nats image — that the helm provider translates into Kubernetes manifests with no external chart. The rendered resource set is exactly what the Workload declares. Because both a Compose and a synthesized helm Recipe carry the name nats, the Manifests reference them provider-scoped as compose/nats and helm/nats.
  • Optional authentication, deterministic either way. NATS authentication is off by default. When no credential is attached, neither realization enables authentication and the render is byte-identical across runs. When a credential is attached, the injected value enables user/password authentication on both realizations.

Scaffold the example

You can build this example with the commands below, or have your AI assistant build it for you.

Write the example into a new folder named after it:

Terminal window
aggrega scaffold --example nats-messaging

It then prints the commands to run next. The first changes into the new folder:

Terminal window
cd nats-messaging

Build

This workspace carries no .aggrega-config.yaml, so the standard-library entities resolve from the hub registry, hub.aggrega.ai, and no catalog flag is needed; --auto-pull writes the lockfile a fresh clone lacks during the build:

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

Rendered artifacts land under dist/.

With an AI assistant

An AI assistant set up with Aggrega’s tools can do the same: paste this prompt into it.

Use the Aggrega tools only, and create no folder yourself. If the Workspace folder holds no `nats-messaging` folder yet, call the `scaffold` tool once with `example` set to `nats-messaging` and no `dir`: it writes the example into a new `nats-messaging` folder. Then call the `build` tool once for each Release, in this order — `release-compose.yaml`, `release-helm-synth.yaml`, `release-compose-auth.yaml` and `release-helm-synth-auth.yaml` — each time with `workspace_root` set to `nats-messaging`, `release` set to that file, `auto_pull` set to true and `write` set to true. Tell me which files each build wrote; they are under `nats-messaging/dist/`.

Credential delivery note

On the Compose path the credential is an inject-value secret (aggregate-auth.yaml): its value is delivered on the component’s environment pipe and the server is started with user/password authentication flags.

The synthesized helm path uses a referenceable credential (aggregate-helm-synth-auth.yaml): the value is materialized as a Kubernetes Secret, the Deployment references it through an env secretKeyRef, and the server is started with --user/--pass flags reading that environment variable. The plaintext password therefore never appears in the Deployment manifest — only in the Secret.

The origin value in the authenticated Aggregates is a development placeholder; supply a real value through your credential source for any real deployment.