Module boundary routing — placing whole sub-modules into boundaries
This example compiles two capabilities — a Thanos metrics read tier over
object storage and a document database speaking the MongoDB wire protocol —
from one Developer-authored Aggregate, and places each into a boundary of its
own from the Release.
Both capabilities are modules: reusable sub-aggregates that each compose
several single-workload components and wire their own internal edges. The
Aggregate names the two modules and nothing about where they run. The Release
places each whole module with one aggregates: entry per boundary — the operator
decides where a capability runs without tracking, or restating, what is inside
it.
Files
| File | Role |
|---|---|
aggregate.yaml | Developer intent: imports the metrics module (core/thanos) and the document-database module (core/ferretdb). |
manifest.yaml | Maps every component type the two modules contribute to its synth helm Recipe, the credential Feature the metrics module attaches to the realization that emits a Secret from each of the module’s two key parameters, and the scrape Feature to its FeatureRecipe. |
release.yaml | Operator record: routes each module into its own boundary, sizes one component of one module, and attaches the scrape Feature to it. |
What it demonstrates
- Routing a whole module into a boundary. A boundary’s
aggregates:entry is keyed by the module’s name in the Aggregate. It places every component the module contains, so the emitted artifacts for all three metrics components land under theobservabilityboundary and both document-database components underdata. - Naming no components at all is the primary shape. The
databoundary routes the document-database module with a baredocuments: {}. Every component in it is placed and takes its own schema defaults; the Release needs the module’s name and nothing else about it. - Configuring a routed component by its local name. A routing entry may also
configure individual components of the module it routes, addressed by the
local name each carries inside that module —
query, notmetrics.query, because inside the module that is the only name it has. Naming one component says nothing about the others: herequeryis sized and given a scrape target while the object store and the store gateway are routed in on their defaults. - A routed component is a component of that boundary. It inherits the
boundary’s annotation cascade like any other, which is what gives every
resource of a routed module the boundary’s
aggrega.ai/namespacevalue — including the components the routing entry never mentions. - Routing is placement, not a different kind of membership. A component routed in with nothing said about it renders the same as the same component named directly in that boundary with an empty body. The two spellings are two ways to say where a component belongs, not two behaviours.
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:
aggrega scaffold --example module-boundary-routingIt then prints the commands to run next. The first changes into the new folder:
cd module-boundary-routingBuild
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:
aggrega build --release release.yaml --auto-pullRendered artifacts land under dist/. The Kubernetes target renders plain
manifests offline — no chart pull is required.
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 `module-boundary-routing` folder yet, call the `scaffold` tool once with `example` set to `module-boundary-routing` and no `dir`: it writes the example into a new `module-boundary-routing` folder. Then call the `build` tool with `workspace_root` set to `module-boundary-routing`, `release` set to `release.yaml`, `auto_pull` set to true and `write` set to true. Tell me which files the build wrote; they are under `module-boundary-routing/dist/`.What the placed stacks look like
Each boundary’s directory is the artifact root for everything placed in it, so
the two modules’ components separate on disk by the boundary that routed them:
dist/observability/helm/ metrics-zdobjstore, metrics-zdstore, metrics-zdquerydist/data/helm/ documents-zdproxy, documents-zdbackendThe filenames carry each component’s identity with the module separator written
out, because a dot is not a character every resource name can hold — metrics.store
in the Aggregate is metrics-zdstore in the cluster. Composing a module is the
only thing that puts a separator in an identity, so a component you name directly
is spelled the same in both places.
Every resource carries the routing boundary’s namespace and records which boundary placed it. The store gateway is never named in the routing entry and still inherits both:
metadata: name: metrics-zdstore namespace: observability [… omitted: the labels every rendered document carries] annotations: aggrega.ai/boundary-path: observability [… omitted: the annotation naming the Recipe that rendered it]The same holds for the four Secrets the metrics module’s credential Feature
emits for the object store’s key pair and the one the store gateway presents to
it: each lands under observability with that namespace, beside the workload
that reads it.
The scrape Feature attached to the routed query component renders its own
artifact under that same boundary, carrying the operator’s scrape settings:
apiVersion: monitoring.coreos.com/v1kind: ServiceMonitormetadata: name: metrics-zdquery-scrape [… omitted: the namespace, labels and annotations every rendered document carries]spec: selector: matchLabels: app.kubernetes.io/name: metrics-zdquery endpoints: - port: http interval: 30s path: /metrics