Provider Architecture
A provider renders a Recipe’s input kinds into provider-native manifest files. When a Recipe declares capability: helm, capability: compose, or any other provider name, the compiler dispatches rendering to the provider that serves that name. This chapter covers how a provider is realised as a provider-rendering Plugin, how dispatch works, and the plugin-socket contract that binds the compiler to each provider.
What this chapter does not cover: the three-input-kinds composition model (source: + valuesMapping:, workload:, artifacts: — each accepting inline content or $import:) that a Recipe uses to produce its output. That model is cross-cutting across every provider and lives in ../../architecture/16-recipe-input-composition.md, including the Provider Capability Matrix that maps which input kind each provider supports.
The provider-rendering Plugin
Provider rendering is served by a Plugin with pluginType: provider. The provider-rendering Plugin:
- serves one or more provider names — declared in
spec.provider.capabilities. The provider name a Recipe names (spec.capability: helm) binds to the provider-rendering Plugin whosespec.provider.capabilitieslist includes that name. When more than one Plugin serves the same target, the workspace chooses between them via a provider binding in.aggrega-config.yaml, resolved ataggrega pulland recorded in the lockfile; with no binding and exactly one candidate that candidate is used, and with no binding and more than one candidate the build halts loudly, naming the candidate plugins. - carries its provider-socket metadata in the same block —
spec.providerholds the capability list above alongside the rest of the provider’s declarations.spec.provider.workloadSchemais a JSON Schema 2020-12 declaration documenting how the platform-owned Workload kind translates into this provider’s native output; the standard-library catalog declares it on providers that synthesize, as the documented translation contract.spec.provider.wellKnownAnnotationsenumerates theaggrega.ai/boundary annotations the provider reads. Synthesized-input (workload:) support is a property of the provider, enforced at render time — not determined byworkloadSchema’s presence.
See ../entities/plugin.md for the full field-level authoring surface of the Plugin entity, including the spec.provider block.
Per-provider dispatch
Every Recipe declares exactly one capability: at the top of its spec. The compiler reads this field and dispatches rendering to the provider that serves the name. A Recipe cannot target multiple providers at once. Multi-provider composition happens at the Release level: a boundary can hold mixed-provider components, and each provider’s contributors at the boundary’s evaluated assembly path are assembled independently — one assembly per (path, provider) tuple.
The dispatch path for a single node:
- The compiler resolves the Recipe URI for this node through the Manifest’s three-tier lookup under the target provider’s mapping section. The Manifest’s provider-axis grouping is what makes “the same Component, different Recipes for different providers” a natural pattern.
- The resolved Recipe’s
spec.capabilityidentifies the provider name to dispatch to. - The compiler binds the provider for that name: it resolves the provider-rendering Plugin whose
spec.provider.capabilitieslist includes the name and renders through that Plugin’s guest. Rendering is Wasm-only — there is no in-host renderer to fall back to, so a provider name that resolves to no serving Plugin halts the build loudly at routing time. - The provider is invoked with the per-node render context (pillar values,
.context.*projections, the Recipe’s input kinds). - The provider returns rendered output. The compiler routes the rendered files to the per-
(path, provider)assembler keyed on the boundary’s evaluateddirectory:joined with the per-componentsubDirectory:. Two boundaries that evaluate to the same path under the same provider share an assembler — the canonical pattern is a parent boundary plus two child boundaries withdirectory: "{{ .parent_boundary.directory }}"collapsing into one merged assembly.
See ../entities/manifest.md for the Manifest’s provider-axis dispatch shape, and ../entities/recipe.md for the Recipe-side single-provider declaration. The per-(path, provider) assembly model and the path-template variable allowlist that controls evaluated paths are documented in ../path-template-variables.md.
The Wasm plugin contract
Provider rendering runs inside a WebAssembly sandbox. The Go compiler is the host; the provider-rendering Plugin is the guest. For each node, the compiler hands the plugin the node’s render context, and the plugin returns the files it rendered. This contract is uniform across every provider:
- A canonical binary encoding in both directions. The compiler encodes the render context — the node’s values and attachments, the parsed
.workload, the evaluated artifact entries, the name-only listing of a resolved.source, and the boundary metadata — as canonical CBOR (RFC 8949 §4.2.1) and hands it to the plugin. The plugin answers in the same encoding with the list of files it rendered — each a path relative to the node’s output root and the exact bytes to write there, optionally with the format the file is in — beside any diagnostics. Every export of the socket, from rendering one node to assembling a boundary and wiring a cross-boundary link, carries this encoding in both directions, and each language’s plugin development kit decodes and encodes it for the plugin. An answer that is not the export’s output shape in this encoding halts the build. The plugin contract documents each export’s payload. - No filesystem access. Plugins cannot read arbitrary files from the host filesystem. A source a Recipe names — a chart in a registry, a module in a repository — is resolved by the compiler before the plugin runs; the plugin receives a name-only listing of it and asks the compiler for the files it selects through a host function, which answers only for files under that node’s source.
- No network access. Plugins are deterministic and hermetic, and open no connection of their own. An external input a plugin needs while rendering — a remote schema a chart’s values reference — is requested through the compiler’s external-input host function, which answers from the content the workspace pinned for that reference.
- Deterministic output. Given identical input and the same plugin version, a plugin must produce byte-identical output. This is the contract that makes the compiler’s byte-identical output guarantee hold end-to-end through the plugin layer. A build run with
--verify-determinismrenders every node twice and halts when a node’s two renders differ.
The plugin-socket architecture at the broader extensibility level, including the other Wasm sockets in the compilation pipeline (the governance socket’s transform and verdict roles), lives in ../../architecture/14-extensibility.md.
Aggrega’s standard-library providers
The helm, helm-chart, compose, terraform, and cloudformation providers together form the standard-library provider set. They cover the common deployment targets without requiring enterprise teams to author their own providers.
helm supports all three input kinds: sourced (an upstream Helm chart fetched through the Helm SDK with the Recipe’s valuesMapping output as the chart’s overrides), synthesized (flat Kubernetes YAML — a controller object chosen by the Workload’s form (Deployment, StatefulSet, DaemonSet, Job, or CronJob) plus Services and PVCs — emitted from a parsed Workload), and artifacts (standalone YAML files alongside the chart output). See the Provider Capability Matrix in ../../architecture/16-recipe-input-composition.md for which of the three kinds it accepts.
helm-chart supports sourced mode (umbrella-chart composition: one chart per boundary, one sub-chart per component) and artifacts: riding alongside it, in both authoring forms. An $import:-loaded artifacts: entry is Go-templated by Aggrega first, then injected into the chart’s templates/ directory pre-render; an inline-content artifacts: entry is evaluated the same way and placed at the sub-chart root, with no provenance merged in, where the chart’s own templates read it via Helm’s .Files.Get / .Files.Glob. A standalone artifacts-only Recipe is not one of the kinds it declares, and neither is the synthesized kind: the umbrella orchestrates sub-charts, while the Workload kind is a leaf concept that belongs inside each sub-chart (the helm provider’s domain).
compose supports sourced (loads a compose file and deep-merges the valuesMapping overlay), synthesized (emits compose services: + volumes: + networks: from a parsed Workload for the stateless and stateful forms, with degraded volume handling for persistentTemplate — per-replica PVCs collapse to a single shared named volume with a warning; the daemon, scheduled, and task forms have no compose mapping and halt loudly), and artifacts (compose fragments whose top-level keys services: / networks: / volumes: / configs: merge into the per-boundary combined docker-compose.yaml). Artifacts may ride alongside either of the other two kinds, and a standalone artifacts-only Recipe — artifacts: with no source: and no workload: — is a kind this provider declares as well: its fragments merge on the same rules, so the node contributes exactly what it declares and needs no Workload standing in for compute it does not have.
terraform supports sourced (vendors a Terraform module verbatim and supplies the valuesMapping output as the arguments of that component’s module block in the boundary’s root configuration) and artifacts (emits an authored HCL or .tf.json body as its template evaluates, without rewriting it). It does not offer the synthesized input kind — there is no faithful mapping from the platform Workload kind to arbitrary Terraform resources. The provider emits configuration and never runs Terraform; runtime-dependent values stay as ${ ... } interpolation strings the Terraform runtime resolves at apply time.
cloudformation renders a boundary into one AWS CloudFormation stack template, assembling the resource fragments its components author into a single pure-JSON template, surfacing each component’s provides as stack Outputs, and wiring uses edges as Fn::GetAtt within a stack and as Fn::ImportValue / Fn::GetStackOutput across stacks. It supports sourced and artifacts input and emits configuration without ever running CloudFormation; runtime-only values stay as CloudFormation intrinsics.
The provider reference index routes you to each provider’s own reference page; which input kinds each one accepts is answered by the capability matrix in ../../architecture/16-recipe-input-composition.md.
Custom providers
Enterprise teams authoring their own providers follow the same pattern as the standard library: author a provider-rendering Plugin (pluginType: provider) declaring the provider name(s) it serves in spec.provider.capabilities, alongside the rest of its spec.provider metadata, then ship the Wasm artifact implementing the rendering contract above. The compiler treats custom providers identically to standard-library providers; per-provider dispatch works on the provider name declared by the Recipe.
Authoring one is documented rather than deferred. Authoring a provider builds a working provider guest end to end — the describe() self-report, the build, the Plugin entity, the attachment, and a render whose output you can read. The Wasm plugin developer guide is the reference for the entity and the publish lifecycle, and the plugin contract documents each socket’s payload and result shapes. Guests are authored in Go, Rust or TypeScript against the plugin development kit.