Skip to content
AggregaAggrega
Select language: English

Workload

The architectural role of the Workload kind — why it exists, how it composes with the other two Recipe input kinds (sourced and artifacts), and the full schema surface — lives in ../../architecture/16-recipe-input-composition.md. This page covers the Workload authoring surface: how a Recipe author writes Workload content, what the compiler evaluates when, how Workload fields interact with the Component’s featuresSchema, and which pillars templates inside a Workload can read.

Authoring location

Workload content is authored inline or from file, inside a Recipe or a FeatureRecipe (see FeatureRecipe). A Recipe declares at most one workload:; a FeatureRecipe likewise declares at most one of its own:

# Inline (block scalar)
spec:
workload: |
apiVersion: aggrega.ai/v1beta1
kind: Workload
# ...

or

# File-loaded via $import: (path relative to the Recipe directory)
spec:
workload:
$import: ./workload/workload.yaml

Both forms produce the same post-parse Workload object; the choice is authoring ergonomics. A third form imports a Workload shared across Recipes from a WorkloadLibrary entry, by its bare-name identity: $import: <Library>#/workloads/<entry>. Per the unified file-import vocabulary, $import: accepts a single source — see ../vocabulary/cross-document-ref.md for the broader $ref: / $import: distinction.

Workload YAML is not authored as a standalone catalog entity. There is no catalog/workload/ directory; the Workload grammar exists only as content a Recipe or FeatureRecipe consumes — written inline, in a file beside it, or in a WorkloadLibrary entry. The apiVersion and kind declarations inside the YAML (apiVersion: aggrega.ai/v1beta1, kind: Workload) identify the embedded content for schema validation; they do not make the Workload independently addressable.

Template evaluation

Workload content is Go-templated against the full pillar context before parsing. When a Recipe author writes a template like the following…

replicas: {{ optional .infra `replicas` 1 }}

…the compiler evaluates that template during the Workload sub-pass of rendering, resolves .infra.replicas against the node’s infra payload, and parses the resulting YAML as a Workload document. The Recipe’s locals resolve before the Workload is evaluated, so a Workload template reads them, already resolved, under .locals.

Pillar access inside Workload templates:

  • .values — developer-authored cognitive payload declared in the Aggregate.
  • .infra — Ops-authored physical sizing declared in the Release.
  • .parameters — already interpolated at resolution; visible via .values / .infra wherever the Developer or Ops referenced .parameters.<name> in their authoring.
  • .locals — Recipe-private state resolved in the locals preamble and published at source resolution; available at every Workload template-evaluation site.
  • .context.instance_id — the node’s flattened instance ID; the prefix of the resource names a provider that names synthesized resources after the identity emits.
  • .context.rendered_name — the name a provider that derives its own name for synthesized resources gives them, such as helm’s release name; present only where the provider reports one. See ../templates/rendered-resource-names.md.
  • .context.inject — the post-interception injection pipe, already rewritten by any FeatureRecipe injectMapping during inject mapping.
  • .context.uses — the enriched topology edges outbound from this node, each carrying the target’s resolved provides, labels, and cascading annotations, and, under .context.uses.<alias>.features.<slot>, the attachments that connection carries.
  • .features — the node’s own attachments, each carrying its type, values, infra, and resolved provides. An attachment named for a slot the Component declares in featuresSchema fills that slot (see below). An attachment a connection carries is not among them; it is read under its connection, and a Workload delivers it by naming the connection (see Delivering a credential a connection carries).

See ../vocabulary/data-pillars.md for the full pillar-access contract and ../templates/expansion-matrix.md for where Workload evaluation sits in the template-evaluation sequence.

Field-semantics essentials

The full Workload schema is in ../../architecture/16-recipe-input-composition.md under “The Workload Kind.” The authoring conventions below cover the field-level decisions a Recipe author makes.

form

form declares the workload’s abstract controller shape — the kind of runtime lifecycle it has, independent of any target platform. It is a single string, one of stateless, stateful, daemon, scheduled, task, reference, and defaults to stateless when omitted:

  • stateless — interchangeable, horizontally-scaled replicas with no per-replica identity (the common long-running service).
  • stateful — replicas with stable per-replica identity and per-replica storage. A persistentTemplate volume is a companion of this form.
  • daemon — one instance per eligible host.
  • scheduled — recurring, time-triggered runs.
  • task — a single run to completion.
  • reference — no containers of its own: the component stands for an external endpoint, given as endpoint (a host or URL, piped through as written) and an optional port. The helm provider emits it as a Service of type ExternalName; the compose provider emits nothing for it.

The form carries no platform-native resource kinds itself. Each target provider that synthesizes a Workload maps the form to its own native shape:

formKubernetes (helm)Compose
statelessDeploymentservice (no persistent volume)
statefulStatefulSetservice + named volume
daemonDaemonSethalts the build
scheduledCronJobhalts the build
taskJobhalts the build

The terraform and cloudformation providers render sourced and artifacts-only Recipes and synthesize no Workload: a Recipe declaring workload: bound to either halts, naming the input kinds the provider supports.

When a target provider has no clean mapping for a form, the build halts loudly rather than degrade the workload into a shape that misrepresents the intent — choosing a form a target boundary cannot express is a build-time error, not a silent downgrade. The compose provider halts on daemon, scheduled, and task. The helm provider emits a CronJob for scheduled (see schedule below) and halts only when its schedule is absent or malformed.

apiVersion: aggrega.ai/v1beta1
kind: Workload
form: stateful
containers:
db: { image: "postgres:16", ports: { db: 5432 } }
volumes:
data:
persistentTemplate:
size: "20Gi"
services:
headless:
type: Headless
ports:
db: 5432

schedule

schedule is the cron schedule for a form: scheduled workload — the companion field that gives the recurring form its recurrence. It is a single string in one canonical format:

  • a standard 5-field crontab expression — minute, hour, day-of-month, month, day-of-week (for example 0 0 * * * for daily at midnight, */15 * * * * for every fifteen minutes), or
  • one of the macros @hourly, @daily, @weekly, @monthly, @yearly.

schedule is required when form: scheduled and only meaningful then. A form: scheduled workload with no schedule, a schedule that is neither a 5-field expression nor a recognised macro (a 6-field seconds-prefixed expression, an unrecognised @-token, or a field with illegal characters), or a schedule set on any other form is a build-time halt naming the fix. The helm provider pipes the value verbatim into the emitted CronJob’s spec.schedule.

apiVersion: aggrega.ai/v1beta1
kind: Workload
form: scheduled
schedule: "0 2 * * *" # daily at 02:00
containers:
report:
image: "reporter:1.0"
command: ["/report"]

suspend

suspend holds the recurring schedule of a form: scheduled workload. It is a boolean and defaults to false. With suspend: true the scheduled resource is still rendered with its schedule in place, but no run starts from that schedule until it is resumed, and a run can still be started from the resource by hand. That is the shape for a task that should run only when someone asks for it.

The helm provider emits the field as the CronJob’s spec.suspend: true. On Kubernetes, kubectl create job <name> --from=cronjob/<cronjob> starts a run from the suspended CronJob, and the schedule resumes once spec.suspend is false again. suspend: false renders exactly as an omitted suspend does, so the field changes no output until it is set. The compose provider has no scheduled shape and halts on any form: scheduled workload, suspended or not.

suspend: true on any other form is a build-time halt naming the fix: no other form carries a schedule for it to hold.

apiVersion: aggrega.ai/v1beta1
kind: Workload
form: scheduled
schedule: "0 2 * * *" # documents when it would run; nothing starts it while suspended
suspend: true
containers:
report:
image: "reporter:1.0"
command: ["/report"]

replicas

A single integer for the workload’s replica count. Defaults to 1 when omitted. Use a template expression to drive replicas from Ops-declared sizing:

replicas: {{ optional .infra `replicas` 1 }}

containers vs initContainers

containers is an ordered map keyed on container name. Container 0 (the first map key) matters for pod-spec ordering in Kubernetes output and for default-container semantics. initContainers is an ordered list of init-container entries, each carrying name, image, and the same variable/secret/volume-mount authoring shape as the main containers.

name is optional on an initContainers entry. An entry that omits it is named init-<index>, where the index is the entry’s position in the list, counting from 0. Because the name identifies the container in rendered output and in any diagnostic that names it, an entry worth referring to is worth naming explicitly.

Author-order preservation is a load-bearing contract of the Workload model — the compiler emits containers, volumes, services, container ports, container variables, and container attachments each in the order the Recipe author declared them, on every build. Recipe authors can rely on the ordered shape: when what happens at run time depends on the order (sidecar startup, $(VAR) chaining in environment variables, volumeMounts referencing previously-declared volumes), authoring order IS the runtime order within each of those collections. A container’s environment combines two of them, and across the two the synthesizing providers write the attachment-read entries (attachments delivered as: env) first and the plain variables after them, each kind in authored order — so on a Kubernetes target a variable may reference, as $(NAME), any attachment-read variable of its container and any variable declared before it (see the helm provider’s environment order). A container that gives one name both as a variables entry and as an attachments entry delivered as: env halts the build, because that order alone would decide which of the two values the process sees (see A container gives one environment variable two values).

Container field authoring follows these conventions:

  • image is typically a template expression referencing .values.image (the Developer’s selected image) with optional .infra.* overrides for environment-specific registry prefixing.
  • variables is a plain string → string map for environment variables. The map blends two distinct data sources via Go template expressions: developer-pillar literals (entries whose template expressions read .values / .infra / .locals — payload originating in the Component’s pillars) and cross-component-pipe data (entries whose template expressions read .context.inject.env.<KEY> — payload originating in another component’s provides: and routed through the topology pipe). The two sources flow into the same variables map; authors choose one per entry based on whether the value is component-local or cross-component-derived. Common patterns: LOG_LEVEL: "{{ .values.log_level }}" is developer-pillar (component-local); DB_HOST: "{{ .context.inject.env.DB_HOST }}" is cross-component-pipe (the value originates in a target component’s provides.host routed through the caller’s uses[].inject.env.DB_HOST declaration). Both forms compile to a single Kubernetes env: list on the rendered Deployment; the dual-source semantic is at authoring time only.
  • attachments references slots declared in the Component’s featuresSchema, or, by naming a connection, a slot that connection’s socket declares (see the integration section below).
  • ports is a named-port map (web: 8080, admin: 9901); port names match container-scoped port names and are referenced by services.<service>.ports.<portname>. A port that carries a transport other than the target’s default is authored in the expanded form instead — see Port transport protocols below.
  • volumeMounts references volumes declared elsewhere in the Workload’s volumes: section by name.
  • resources declares the container’s requests and limits — the cpu and memory quantities, and optionally extended-resource keys for GPUs and other devices (see GPU and device workloads below).
  • health uses the intent shape (http: /path, tcp: <port>, exec: [cmd, ...]) — see the Health Probes section below.

volumes

Each volume is exactly one type: ephemeral, configmap, secret, persistent, or persistentTemplate. The types are mutually exclusive inside a single volume declaration; each type carries its own required fields:

volumes:
app-config:
configmap:
source: "{{ .locals.app_cm }}"
data:
persistent:
size: "10Gi"
class: "gp3"
cache:
ephemeral:
sizeLimit: "1Gi"

persistentTemplate produces a per-replica PVC for StatefulSet-shaped translation; in compose translation it degrades to a single shared named volume, with a warning reported alongside the build. The generated file itself carries no note of the degradation — it is byte-for-byte what it would be without the warning.

Per-provider translation. Each provider translates the five volume variants into its native shape:

VariantHelm / helm-chart (K8s)ComposeLoss notes
ephemeralemptyDir: { sizeLimit }service-level tmpfs: entry naming the mount path (in-memory)Compose tmpfs is RAM-backed; helm’s emptyDir is disk-backed on the node by default — semantic divergence in the underlying storage medium. sizeLimit reaches no part of the compose output: the emitted entry is the mount path alone. An authored sizeLimit raises an unsupported-field warning naming it, reported alongside the build rather than written into the generated file.
configmapConfigMap volume reference (consumes a ConfigMap resource emitted by the Recipe’s artifacts: or by a Feature)Service-level configs: reference naming the configmap, mounted at the volume mount’s path; the matching top-level configs: entry comes from the Recipe’s artifacts:Both targets reference the configmap by name and neither reads its content, so the authoring shape is symmetric. What compose loses is K8s ConfigMap’s update-on-rollout semantics: a compose config is fixed at the content the build emitted. A reference no top-level entry resolves halts the build rather than emitting a mount that would be dangling at run time.
secretSecret volume reference (consumes the Secret a credential attachment names — one its FeatureRecipe emits, or one that already exists)env_file: for env-shaped secrets, or a bind-mounted secret file for path-shaped secretsCompose lacks first-class Kubernetes Secret semantics. A path-shaped secret deliberately does not take the configmap variant’s configs: route: an inline config entry would write the secret’s value into the emitted compose file in plaintext, and the compiler never resolves a secret into plaintext. The bind source is a path the operator makes reachable on the compose host, outside any vault-fetch CRD lifecycle.
persistentPVC resource + volume.persistentVolumeClaimNamed volumeCompose named volumes are a flat host-side abstraction; helm’s PVC supports storage class, access mode, and capacity declaration that compose ignores.
persistentTemplateStatefulSet.volumeClaimTemplates (per-replica PVC; companion of form: stateful)Named volume (degraded — single shared volume across replicas, with a warning reported)Compose cannot express per-replica templates. When persistentTemplate is translated to compose, a single named volume is emitted and the reduced fidelity is reported as a warning alongside the build rather than written into the generated file. Workloads relying on per-replica volume isolation should not target compose-only boundaries.

The controller shape is chosen by the workload’s form, not by its volumes. A StatefulSet is emitted when form: stateful; a persistentTemplate volume is a companion of that form — it declares per-replica storage on a workload that already has the per-replica identity a StatefulSet provides. Declaring a persistentTemplate volume on any other form (or on the default stateless) is a build-time error naming the fix: declare form: stateful. The reverse is allowed — a form: stateful workload need not declare a persistentTemplate volume. Authors who want StatefulSet semantics set form: stateful directly.

A form: stateful workload on the helm provider requires a headless governing Service: declare exactly one service with type: Headless in the same Workload. The provider wires the StatefulSet’s serviceName to that headless Service (it provides the stable per-pod network identities a StatefulSet needs). The build halts if no headless service is declared — a StatefulSet has no governing Service to name — or if more than one is, leaving the governing Service ambiguous. A StatefulSet workload may still declare additional non-headless services (for example a ClusterIP service for client access) beside the one headless governing service.

Resource quantities

These Workload values are quantities — amounts written in the notation Kubernetes uses for resources: a container’s (or init container’s) resources.requests and resources.limits values for cpu, for memory and for every extended-resource key, and a volume’s ephemeral.sizeLimit, persistent.size and persistentTemplate.size. The Workload schema types each as a string and does not constrain its form. The provider that synthesizes the Workload for a target checks every quantity it emits, and it checks the Workload as the Recipe’s templates evaluated it, so a value that arrived through infra, a Release parameter or any other template input is judged on the string it rendered to.

A quantity is, with nothing before or after it:

  • an optional sign, + or -;
  • a number with at least one digit — 2, 0.5, .5 or 1.;
  • at most one of an exponent — e or E, an optional sign, then digits, as in 1e3 or 5E-2 — or a unit suffix: a decimal suffix n, u, m, k, M, G, T, P or E (10⁻⁹ up to 10¹⁸, in steps of a thousand), or a binary suffix Ki, Mi, Gi, Ti, Pi or Ei (1024 up to 1024⁶).

500m, 0.5, 2, 128Mi, 1.5Gi, 1e3, 5n and 4u are quantities; lots, 1.5 cores, 1 gigabyte, 10 GB and 1e1.5 are not — an exponent is a whole number. A lone E after the number is the decimal suffix for 10¹⁸ (12E); followed by digits it opens an exponent (1E3).

This is the form Kubernetes’ own quantity parser accepts, with one deliberate difference: a string whose number has no digit — m, Ki, +, ., e5 — is refused, where Kubernetes reads it as zero. That string is exactly what a template leaves behind when the value it interpolates is empty: "{{ .infra.cpu }}m" with an empty cpu renders m. Refusing it turns an empty input into a halt that names the field, rather than into a zero-sized request nothing reports.

What each target does with a quantity:

  • helm emits every quantity verbatim, after checking each one against the form above. A value outside it halts the build with an error naming the node, the field’s path in the Workload — containers.main.resources.requests.cpu, initContainers[0].resources.limits.memory, volumes.data.persistent.size — and the value. See Helm Provider → Workload (synthesized) mode.
  • compose converts cpu and memory into its own units from the parsed value: cpus becomes a decimal core count (500m → 0.5) and memory an exact byte count (1.5Gi → 1610612736). A value that is not a quantity halts the build, and so does a quantity compose cannot represent exactly — a negative amount, a memory amount that is not a whole number of bytes (1500m), or a cpu amount finer than nine decimal places of a core — and the error says which of the two it met. An nvidia.com/gpu count is read the same way and becomes a device count, so one that is not a whole number of devices halts too. compose emits no other extended resource and no volume size, so it checks neither: any other extended-resource key and an ephemeral.sizeLimit are dropped with a warning, and a persistent size shapes nothing in its output. See Compose Provider → Container resources.

The check judges form only. Whether a cluster can schedule the amount, or whether the amount suits its device, is outside it.

services

An ordered map of service exposures. Each service declares its type (ClusterIP, Headless, NodePort, LoadBalancer, Loopback) — how far its ports reach — and a named-port map. Port names must match container port names declared elsewhere in the Workload:

services:
http:
type: ClusterIP
ports:
web: 8080 # must exist in containers.<name>.ports

Multiple services on a single Workload are common for exposing internal and external traffic separately (internal ClusterIP for in-cluster consumers, LoadBalancer for external traffic, ClusterIP for Prometheus scraping).

How far a service’s ports reach. The type states it, and each target renders it in its own terms:

typeReachhelmcompose
ClusterIPthe workload’s peers, on the target’s own networka Service of type ClusterIPpublishes nothing; peers reach the port on the compose network
Headlessthe same, with no cluster addressa Service of type ClusterIP with clusterIP: Nonepublishes nothing
NodePortbeyond the target’s own networka Service of type NodePorteach port published on every host interface, as <service port>:<container port>
LoadBalancerbeyond the target’s own networka Service of type LoadBalancerthe same as NodePort
Loopbackthe host’s own loopback address onlyhalts the build, naming the serviceeach port published on the IPv4 loopback address, as 127.0.0.1:<service port>:<container port>

A service port’s number and the container port it names are two numbers, as a Kubernetes Service’s port and targetPort are: helm writes the entry’s number as the Service port and targets the container port by its name, and compose publishes the entry’s number on the host onto the container port’s number. Where the two numbers are equal, compose writes that number on both sides.

Loopback is for a port that something on the same machine reaches — a browser or an agent running on the host — and that nothing else should. On compose the binding is the IPv4 loopback address alone: the IPv6 loopback address ::1 is not bound, so address the port as 127.0.0.1 rather than through a name that may resolve to ::1. A declared transport is spelled on the entry as on any published port, as in 127.0.0.1:5514:5514/udp.

Where two entries name the same port, the wider reach wins: a port that a NodePort or LoadBalancer entry publishes is published on every interface even when a Loopback entry names it too, whichever of the two is declared first.

On helm a Loopback entry stops the build rather than rendering as something it is not. A Kubernetes Service has no type that binds to a host’s loopback address — which node addresses a NodePort Service listens on is a setting of the whole cluster, not of one Service — so a ClusterIP Service would drop the reach the entry asks for, and a NodePort one would publish the port on every node address the cluster allows. The halt names the node and the service; see A service type the helm provider cannot render.

Synthesized-name convention. When the helm provider synthesizes a Workload’s services, each Service’s metadata.name is derived deterministically from the name the workload’s own controller carries and the service’s authoring key. For a component’s Workload that name is the node’s release name: <release name>-<service-key>. The release name is the component’s identity written into the alphabet a Kubernetes name admits — the same name a chart renders against, readable in a Recipe’s templates as {{ .context.rendered_name }} — so it equals the instance_id wherever the identity carries no underscore and no capital letter. A Workload declaring services.http on node api-server produces a Service named api-server-http; the same Workload on node billing produces billing-http, and on node my_api produces my-zuapi-http. The output filename mirrors the same convention: <release name>-<service-key>-service.yaml. A Recipe publishing the address of such a Service builds it from {{ .context.rendered_name }}, never from {{ .context.instance_id }}, which names no Service wherever the two differ — see ../templates/rendered-resource-names.md.

A Workload a Feature attachment’s FeatureRecipe synthesizes is named after the attachment’s own composed identity instead of a release name: the value its resources carry in their aggrega.ai/component-id label, composed from the host component and the key written under features: behind the opening cfr--. A release name derived there would be the host’s, and would name the attachment’s resources after the host’s own. So a FeatureRecipe whose Workload declares services.scrape, for an attachment stats on node front-door, produces a Deployment cfr--front-door--stats and a Service cfr--front-door--stats-scrape. That first segment never equals the instance_id, and no key in the FeatureRecipe’s template context carries it: on an attachment’s templates {{ .context.rendered_name }} and {{ .context.instance_id }} both name the host (front-door) and {{ .attachment_name }} is the key alone (stats), so {{ .context.rendered_name }}-scrape names the host’s own scrape Service where the host declares one, and never the attachment’s — see ../templates/rendered-resource-names.md. The output file sits behind the prefix every file an attachment emits carries — the host’s name and the attachment’s, each followed by -- — so that Service is written to front-door--stats--cfr--front-door--stats-scrape-service.yaml.

The convention has two practical consequences. First, cross-node collisions are impossible by construction — the name prefix differentiates services across every node in the boundary, because two distinct identities always reach two distinct release names, an attachment’s identity carries both its host and its key, and no component name may open with cfr-- (the build halts on one that does — see Component identity cannot be stamped on what it emits), so two Workloads each declaring services.http produce distinct K8s Service resources with non-overlapping names. The one residue is an attachment identity too long for the target: it is shortened around a digest of the whole, and two shortened identities can in principle meet — see Provenance labels emitted on rendered output. Second, a Workload cannot declare one service key twice — a services: map naming a key twice is refused when the Workload’s YAML is parsed, and the build halts naming the key and its line.

The collision risk that does remain is at the K8s name-length boundary: Kubernetes Service names cap at 63 characters, and the synthesized <release name>-<service-key> form can exceed that limit when both segments are long. The Aggrega compiler does not enforce the limit; the build emits the Service, and Kubernetes rejects it when it is applied. Authors with deeply nested instance IDs (e.g., data-layer.regional.eu-west.primary) plus long service keys should keep the combined length under 63 characters. The same holds for an attachment’s Workload: a composed identity too long for the target is shortened, but the service key appended to it is not, so an attachment Service carrying a long key can still exceed 63 characters and build without a halt.

Provider-specific note (compose). The compose provider derives depends_on automatically from IR uses-edges. Those entries are emitted ungated — they carry service_started semantics regardless of whether the target declares a healthcheck — so a service whose dependencies all come from uses edges emits the short-form list (depends_on: [<target>]). Gating an edge-derived entry on the target’s health is not implemented. The long form is emitted where an entry does carry a condition, which is how a wait on an init container is expressed; see providers/compose.md.

Port transport protocols

A container port is authored in either of two equivalent forms. The bare number is the short form and declares no transport, so the target applies its own default — TCP on every target that has one:

containers:
main:
image: "{{ .values.image }}"
ports:
web: 8080

The expanded form carries the number and the transport together, and is what a port needs when it carries anything other than that default:

containers:
main:
image: "{{ .values.image }}"
ports:
web: 8080 # short form — no transport declared
dns:
port: 53
protocol: UDP # TCP | UDP | SCTP
sigtran:
port: 2905
protocol: SCTP

The two forms may be mixed freely inside one ports map, and a port with no transport to declare stays in the short form.

The transport is declared once, on the container port. A services.<service>.ports entry names a container port and takes that port’s transport with it, so a service exposure cannot disagree with the port the container opened. There is no protocol key on a service port, and authoring one is rejected.

Why the field exists. Deployment targets treat an unspecified transport as the streaming one. A component that needs a datagram port — realtime media, telephony, name resolution, private networking, a game server — could otherwise declare only the number, and the stack would deploy with every gate passing while no client connected, because the traffic is datagram and the port that got opened is not. Declaring the transport is what makes that expressible.

The compiler does not interpret the value. It reads no transport out of a port’s name and does not check the declared transport against what the process behind the port actually speaks: the value is data you declare and the target’s engine emits. A port named dns carrying no protocol key is a TCP port, and a port named web declaring protocol: UDP is a UDP port.

Per-target behaviour.

TargetA port with no transport declaredA declared transport
helmcontainerPort and the Service port carry no protocol keyemitted verbatim as protocol: on the container port and on every Service port naming it
composepublished as <host>:<container>, unchangedpublished as <host>:<container>/tcp or /udp; SCTP has no compose spelling and halts the build rather than publishing a port that would carry a different transport

A container port that no service publishes reaches no part of a compose file at all — that is compose’s standing behaviour for container ports — so a transport declared on such a port has nothing to be spelled onto and does not halt.

Health probes — intent shape

Each container declares its probes under its own health: key (containers.<name>.health), in an abstract intent shape; the Workload has no top-level health. Each provider translates the intent into its native probe shape at synthesis time.

health:
ready:
http: /healthz # intent: HTTP GET probe
timeoutSeconds: 5
live:
tcp: 8080 # intent: TCP socket check
timeoutSeconds: 5
startup:
exec: ["check-ready.sh"] # intent: command exec
timeoutSeconds: 30
periodSeconds: 10

Three intent forms (http:, tcp:, exec:) are mutually exclusive within a single probe declaration. Port resolution for http: without an explicit port takes the alphabetically-first port name the container declares under containers.<name>.ports — the same rule on both targets, so a probe reads the same port whichever one renders it. A container that declares no named port cannot carry an HTTP probe: the build halts with a translation error naming the offending probe.

Per-provider translation. Each provider translates the abstract probe intent into its native shape at synthesis time:

IntentHelm (K8s)ComposeLoss notes
http: /pathhttpGet.path: /path, httpGet.port: <alphabetically-first port name>CMD-SHELL "curl -f http://localhost:<port>/path"Compose lacks a native HTTP probe shape; the CMD-SHELL wrapper depends on curl being present in the container image.
tcp: <port>tcpSocket.port: <port>CMD-SHELL "nc -z localhost <port>"Compose lacks a native TCP probe shape; the CMD-SHELL wrapper depends on nc being present in the container image.
exec: [cmd, ...]exec.command: [cmd, ...]CMD [cmd, ...]One-to-one mapping; both providers carry the command list verbatim.

Compose’s CMD-SHELL wrappers approximate HTTP and TCP probes through shell-evaluable predicates. What compose lacks is the native probe shape, not the timing fields: an authored periodSeconds, timeoutSeconds, failureThreshold and initialDelaySeconds are carried across onto the healthcheck as interval, timeout, retries and start_period — providers/compose.md “Probes” carries the field-by-field mapping. The native exec: shape needs no wrapper at all and translates one-to-one on both targets.

A wrapped probe is translated silently: nothing in the emitted docker-compose.yaml marks it, and no diagnostic reports the wrapping. What the build does report on this path is a probe slot that reaches no output at all — a compose service carries one healthcheck, so where a Workload declares more than one of ready:, live: and startup: only the preferred slot is translated (live over ready over startup) and an unsupported-field warning names the slot translated and the slots dropped.

Provider-specific note (compose). Authoring a health: block on a compose-targeted Workload does not gate depends_on ordering on health: the compose provider’s depends_on entries derived from uses: edges always use service_started semantics, regardless of whether the target Workload declares health probes. Gating those entries on the target’s health is not implemented — the long form that would carry such a condition is itself emitted, for init-container waits, so what is missing is the choice to gate an edge on health rather than the shape to express it. See providers/compose.md for the full inference rules.

K8s-shape pass-through fields — scheduling, serviceAccount, podSecurityContext

The Workload schema accepts three optional top-level fields that exist primarily to thread Kubernetes-native primitives through the helm provider while preserving Aggrega’s structural shape. The compose provider translates the subset that has a Compose analogue and ignores the rest with an emitted warning. Aggrega validates the outer shape but does not police the inner content (see Validation surface below) — the K8s-native inner values pass through verbatim to the helm-rendered pod spec.

scheduling

scheduling groups four K8s-native scheduling primitives — nodeSelector, affinity, tolerations, topologySpreadConstraints — into one block keyed by purpose. Each sub-field is shaped exactly as the corresponding Kubernetes pod-spec field:

apiVersion: aggrega.ai/v1beta1
kind: Workload
scheduling:
nodeSelector:
disktype: ssd
region: us-east-1
tolerations:
- key: dedicated
operator: Equal
value: gpu-workloads
effect: NoSchedule
affinity:
podAntiAffinity:
preferredDuringSchedulingIgnoredDuringExecution:
- weight: 100
podAffinityTerm:
labelSelector:
matchLabels: { app: "{{ .context.instance_id }}" }
topologyKey: kubernetes.io/hostname
topologySpreadConstraints:
- maxSkew: 1
topologyKey: topology.kubernetes.io/zone
whenUnsatisfiable: ScheduleAnyway
containers:
app: { image: "..." }

Provider translation. The helm provider passes each sub-field verbatim into the rendered pod spec. The compose provider translates none of the four: it omits the whole scheduling block, and a warning names it.

serviceAccount

serviceAccount is a plain string carrying the name of the ServiceAccount the workload runs under:

apiVersion: aggrega.ai/v1beta1
kind: Workload
serviceAccount: "{{ .context.rendered_name }}-runner"
containers:
app: { image: "..." }

The name is built from {{ .context.rendered_name }}, the release name the helm provider names the workload’s own resources after, so it is one the cluster accepts whatever the component is called. The field references an existing ServiceAccount; it does not create one. The accompanying RBAC resources (the ServiceAccount object itself, plus Role / RoleBinding / ClusterRole / ClusterRoleBinding) should ship through one of two channels:

  • Recipe artifacts: — when the RBAC is intrinsic to this Recipe (the Recipe knows it needs a specific Role for a specific job).
  • Features with Resource Generation — when the RBAC is cross-cutting (a Workload-Identity FeatureRecipe attaching IAM-bound ServiceAccounts to every component with a particular label).

Setting serviceAccount: without arranging for the named ServiceAccount to exist results in a runtime K8s error at apply time, not a build-time error — the workload schema validation does not cross-check ServiceAccount existence (no compile-time access to the cluster state per the AOT-purity invariant).

The compose provider ignores serviceAccount: with a warning; Compose has no equivalent identity-binding concept.

podSecurityContext

podSecurityContext carries pod-level security primitives — UID, GID, fsGroup, supplementalGroups — that apply to every container in the pod:

apiVersion: aggrega.ai/v1beta1
kind: Workload
podSecurityContext:
runAsUser: 1000
runAsGroup: 3000
fsGroup: 2000
supplementalGroups: [4000, 5000]
containers:
app: { image: "..." }

Field semantics. All four fields are integers (numeric UIDs/GIDs, not strings); runAsUser and runAsGroup set the container processes’ effective UID/GID; fsGroup sets the group ownership for volumes mounted into the pod; supplementalGroups adds additional GIDs to each container’s process group.

Provider translation. The helm provider passes the block verbatim into the rendered pod spec. The compose provider has no equivalent for fsGroup or supplementalGroups and omits each with a warning; runAsUser/runAsGroup translate to the Compose user: 1000:3000 form on every service the Workload produces, sidecars and init containers included, and a runAsGroup with no runAsUser beside it is omitted with a warning. Each container and init container also carries a securityContext of its own — runAsUser, runAsGroup, runAsNonRoot, readOnlyRootFilesystem, allowPrivilegeEscalation, and capabilities.add / capabilities.drop. The helm provider emits it on the container; the compose provider emits readOnlyRootFilesystem as read_only, capabilities.add / capabilities.drop as cap_add / cap_drop, and runAsUser / runAsGroup as the container’s own user, which takes the place of the pod’s; it omits runAsNonRoot, allowPrivilegeEscalation and a runAsGroup written without a runAsUser with a warning each, and warns too where a container’s own runAsUser leaves the pod’s runAsGroup out. providers/compose.md carries the field-by-field mapping.

GPU and device workloads

A workload that needs specialised hardware — a GPU, or another vendor-provided device — expresses two independent concerns: the pod-level runtime the device-enabled node exposes (runtimeClassName), and the per-container quantity of the device the workload claims (an extended-resource key under a container’s resources). A typical GPU workload declares both together, but each stands on its own and either may appear without the other.

Both fields describe compute — the pod and the container that runs on the device — so they belong on a workload that runs containers. A workload that carries only an external endpoint and declares no containers of its own has no pod or container to attach them to: setting runtimeClassName on such an endpoint-only workload halts the build, naming runtimeClassName and the Recipe whose Workload declared it, and with no containers there is nowhere to place a device resource request.

runtimeClassName

runtimeClassName is a single string naming the RuntimeClass the pod runs under — the container runtime a device-enabled node exposes, for example a GPU runtime named nvidia. It is a pod-level selector: it applies to every container in the workload. The compiler pipes the name through verbatim as a deterministic pointer; the cluster resolves it to a RuntimeClass its administrator has configured, at schedule time. Aggrega does not check that a matching RuntimeClass exists — it has no compile-time access to cluster state — so a name with no configured RuntimeClass surfaces as a scheduling error at apply time, not a build-time error.

Extended-resource keys

A container’s resources.requests and resources.limits carry the ordinary cpu and memory quantities and, alongside them, extended-resource keys: vendor- or domain-scoped device quantities keyed by a fully-qualified <domain>/<name> name such as nvidia.com/gpu or amd.com/gpu. The domain segment carries at least one dot, and that dot is what distinguishes an extended key (nvidia.com/gpu) from the bare cpu and memory quantities. Each value is a string quantity ("1", "2") the compiler pipes through verbatim, and the helm provider checks its form before emitting it (see Resource quantities); the cluster’s device plugin resolves and allocates the device at schedule time.

Worked example — a GPU inference workload

apiVersion: aggrega.ai/v1beta1
kind: Workload
runtimeClassName: nvidia
containers:
inference:
image: "{{ .values.image }}"
resources:
requests:
cpu: "2"
memory: "8Gi"
nvidia.com/gpu: "1"
limits:
nvidia.com/gpu: "1"

The workload selects the nvidia runtime for its pod and claims one GPU for the inference container. The GPU quantity appears in both requests and limits: a device is not oversubscribable, so its request and limit are set to the same value.

Provider translation. These are Kubernetes-native concepts. The helm provider emits runtimeClassName on the rendered pod spec and each extended-resource key verbatim under the container’s resources.requests / resources.limits, so they reach the cluster through the Kubernetes output. The compose provider reserves an nvidia.com/gpu count as that many NVIDIA GPUs on the container’s service (see Compose Provider → Container resources); a single host has no runtime-class concept and no analog for any other extended-resource key, so a workload declaring runtimeClassName or another key renders on a compose target without it.

Running on the node’s network

By default a workload runs in a network namespace of its own: its containers see only their own interfaces, and traffic reaches them through the target’s address translation. hostNetwork: true asks for the other arrangement — the workload runs in the node’s own network namespace, so it sees the node’s interfaces and the ports its containers open are reachable on the node’s own addresses, with no translation in between.

That is what a whole class of software needs. Realtime media, telephony, virtual private networking and similar traffic carry the peer’s address inside the payload, so an address rewritten in transit arrives describing somewhere the peer cannot reach; running on the node’s addresses is what keeps the two consistent.

apiVersion: aggrega.ai/v1beta1
kind: Workload
hostNetwork: true
containers:
media:
image: "{{ .values.image }}"
ports:
rtp:
port: 7881
protocol: UDP

What it declares, and what it does not

hostNetwork chooses a network namespace, and that is the whole of it.

  • It declares no ports. The ports a workload opens are still declared under containers.<name>.ports, exactly as they are without it, and they still mean the same thing. Declaring hostNetwork neither adds a port nor removes the need to declare one.
  • It declares no number of ports. An application that wants many contiguous ports — a media server sizing a range to a machine’s processor count, say — configures that range in its own configuration body, from values its operator supplies, the same way it configures anything else it reads at start-up. That is an application setting rather than a workload one, and the workload contract is not where it lives.
  • Nothing is inferred. The compiler reads no meaning from the value and derives it from nothing else: not from a port’s name, not from a component’s type or labels, not from how many ports are declared. A workload runs on the node’s network when, and only when, it says so.

Because it describes compute, hostNetwork belongs on a workload that runs containers. A workload carrying only an external endpoint declares no containers, so it has no network namespace to choose: declaring hostNetwork on an endpoint-only workload halts the build, naming hostNetwork and the Recipe whose Workload declared it.

Provider translation

The helm provider emits hostNetwork: true on the rendered pod spec, which is how Kubernetes expresses the same choice. The declaration reaches the pod spec and nothing else — the emitted Services are identical with and without it.

The compose provider emits network_mode: host on the workload’s own service. One consequence follows from how compose models networks: a service in that mode is not attached to the boundary network, because compose treats attaching to a network and adopting the host’s namespace as alternatives rather than additions. Its peers therefore reach it on the host’s own addresses instead of by service name — which is what host networking means on any target — and every other service on the boundary is unaffected.

Two shapes compose with it on that target. A sidecar container follows the main service onto the host’s network without declaring anything, because it takes the main service’s namespace by naming it. An init container does not: it becomes a service that the main service waits on, so it joins the boundary network in its own right rather than adopting a namespace that would make that wait circular. A workload declaring both hostNetwork and initContainers therefore runs its own service on the node’s network while its init services stay on the boundary network — a narrower arrangement than the single shared namespace the pod shape gives, and one the compose provider names in an unsupported-field warning rather than leaving to be discovered at run time.

A workload that does not declare hostNetwork carries no such key in its output: the key is absent rather than emitted as false.

Attachment integration with the Component’s featuresSchema

The Workload’s containers.<name>.attachments block references credential slots declared in the Component’s featuresSchema — or, for an entry that names a connection, a slot that connection’s socket declares (see Delivering a credential a connection carries); it does not declare new slots. See ../entities/component.md for the featuresSchema authoring surface. from names the slot; it is not the generated Secret’s name.

A containers.<name>.attachments entry renders to a reference to a Secret resource — a Kubernetes secretKeyRef (for as: env) or a secret-backed volume (for as: file) — both of which point at the Secret by name. The synthesizer resolves that name and data key from the slot’s exposed provides: the entry’s rendered secretKeyRef.name is the slot’s .features.<slot>.provides.name and the data key is .features.<slot>.provides.key. The Recipe author writes only from: <slot> and as: env; the synthesizer reads the resolved provides — it does not re-derive the name. This is the same .features.<slot>.provides.<key> read a source Recipe uses for an existingSecret: a single credential slot feeds both a source-Recipe consumer and a synthesized-Workload consumer identically (source/workload symmetry).

Four validation rules govern the integration:

  • Every attachments.<KEY>.from value must match a slot name declared in the Component’s featuresSchema — or, on an entry naming a connection, in that connection’s socket. An unknown slot name is a load-time error.
  • The as: delivery mechanism (env or file) must appear in the slot’s inject: allowlist declared by the Component. A Workload declaring as: file against a slot whose featuresSchema entry specifies inject: [env] is a load-time error.
  • Slots marked inject: [] (blackbox delivery) in the Component’s featuresSchema cannot appear in Workload attachments: blocks at all. Those slots are delivered by the Recipe’s internal plumbing (a Helm chart’s existingSecret parameter, for example), not by Workload exposure.
  • The referenced slot must be referenceable — its fill must publish a provides locator (name, key) for a Secret resource, one its realization emits or one that already exists. A slot filled by an inject-delivered credential (one that writes a value into the inject pipe and publishes no locator) has nothing to point at; referencing it from a Workload attachments: entry is a load-time error. An inject-delivered credential reaches the container through the slot’s inject pipe (a variables entry reading .context.inject.env.<KEY>), not through an attachments: entry.

Provider note. Helm renders the secretKeyRef/secret-volume reference described above. The compose provider has no native env-from-secret primitive; an as: env attachment entry on a compose-targeted Workload renders as an environment entry with an empty value and a warning naming the entry (see the compose provider page), while the referenceability rule (capability-agnostic) still applies.

Example:

# In the Component catalog entity
spec:
featuresSchema:
db_password:
required: true
inject: [env, file] # transparent: Workload may dictate delivery
root_password:
required: true
inject: [] # blackbox: Recipe handles internally
# In the Recipe's Workload
workload: |
containers:
main:
attachments:
DB_PASSWORD: # OK — db_password slot allows env inject
from: db_password
as: env
# ROOT_PASSWORD: ... # rejected at load time: blackbox slot

Delivering a credential a connection carries

A Component’s socket can declare, in usesSchema.<socket>.featuresSchema, the slots each connection wired through it fills — so a component reaching several targets holds one credential per connection rather than one for all of them. Such an attachment is not among the component’s own .features; it sits under its connection, at .context.uses.<alias>.features.<slot>. A Workload entry delivers it by naming the connection beside the slot:

  • on a container’s attachments entry, connection: <alias> beside from: <slot>;
  • on a container’s envFrom entry, connection: <alias> beside secret: <slot> — connection is accepted only beside secret.

Both forms are accepted on every container and every init container. <alias> is the name the connection is written under in the component’s uses block, on the Aggregate or on the Release — the key a Recipe reads the connection by under .context.uses — and <slot> is a slot the socket that connection is wired through declares.

Before any rule above reads the Workload, each entry naming a connection is rewritten onto the name the attachment that connection carries in that slot takes on the component: the alias, a dot, and the slot (gpt.credential). Every rule then runs on the rewritten entry exactly as it runs on an entry naming one of the Component’s own slots: the socket slot’s inject: allowlist governs as:, a socket slot declaring inject: [] cannot be referenced, the attachment filling it must be referenceable, and the provider resolves the Secret’s name and data key from that attachment’s resolved provides — so each connection’s entry references that connection’s own credential. A socket slot declaring sensitive: true is read for the entry exactly as a Component slot’s declaration is. The rewritten entry is what the provider receives; the connection key does not reach it.

Three entries are refused, each naming what it named:

  • an entry naming a connection the component does not draw — the refusal names the connection, the slot, and the connections the component does draw;
  • an entry naming a slot the connection’s socket does not declare — the refusal names the slot, the connection, the socket, and the slots it declares;
  • an entry writing the composed name (from: gpt.credential) itself. A connection’s slot is named by naming the connection, so the composed name is never a second way to reach it.

A connection that carries no attachment in the slot leaves the entry with nothing to reference, and the referenceability rule refuses it. A Workload a FeatureRecipe renders is held to the slots the Feature it implements declares, which reach none of the host component’s connections, so an entry there naming a connection is refused as naming one the component does not draw.

Example:

# In the Component catalog entity
spec:
usesSchema:
models:
featuresSchema:
credential:
sensitive: true
inject: [env]
# In the Recipe's Workload — the component draws connections `gpt` and `nim`
# through the `models` socket, each carrying its own `credential`
workload: |
containers:
main:
attachments:
MODEL_KEY_GPT:
from: credential
connection: gpt
as: env
MODEL_KEY_NIM:
from: credential
connection: nim
as: env

On helm, MODEL_KEY_GPT renders as a secretKeyRef naming the Secret the gpt connection’s credential published and MODEL_KEY_NIM the one the nim connection’s did. On compose, an as: env entry naming a connection is emitted with an empty value and the same partial-support advisory an entry naming one of the Component’s own slots takes.

Validation surface

Every Workload is validated at Recipe load time before any rendering runs. Validation has two stages:

  • Schema validation. The Workload value is unified against the embedded aggrega.ai/v1beta1 Workload schema. Errors carry the field path and the constraint violated (for example, .containers.main.health.ready: multiple oneOf branches matched (branches [0, 1] of 3): expected exactly one). Schema validation enforces every type, enum, range, and disjunction declared in the schema — including the closed-set controller form (one of stateless, stateful, daemon, scheduled, task, reference), the closed-set service type (one of ClusterIP, Headless, NodePort, LoadBalancer, Loopback), the integer port range (1..65535), the probe-shape disjunction (exactly one of http, tcp, exec), and the volume-variant disjunction (exactly one of ephemeral, configmap, secret, persistent, persistentTemplate).
  • Cross-reference validation. Workload attachment references are checked against the Component’s featuresSchema — and, for an entry naming a connection, against the slots that connection’s socket declares — (slot membership, as: delivery allowlist, blackbox exclusion) and against each referenced slot’s resolved provides (referenceability — the fill must publish name/key). These are cross-entity checks that schema-only validation cannot perform.

Both stages produce the same CATALOG_ERROR-prefixed message shape; failures stop the build before any rendering output is produced. Recipe authors get pointed feedback identifying the exact field that failed and the constraint that rejected it.

The K8s-shaped pass-through fields (scheduling.affinity, scheduling.tolerations, scheduling.topologySpreadConstraints, the items lists inside ConfigMap and Secret volumes, lifecycle httpGet hooks) are validated structurally only — Aggrega’s schema constrains their presence and outer shape, but the inner shape of these K8s-API-defined values is the provider’s responsibility (the helm provider hands them to the K8s pod spec verbatim; the compose provider rejects or degrades them as appropriate). A Workload using a misshapen affinity value passes Aggrega validation and surfaces the error during provider synthesis instead.

Resource quantities are strings to the schema in the same way: neither stage checks their form. The synthesizing provider does, on the evaluated Workload, and halts on a value outside the quantity form — see Resource quantities.

Auxiliary resources belong outside the Workload

The Workload describes the workload shape only — containers, volumes, services, replicas, scheduling, security context, service account. It has no additionalResources field and no inline ConfigMap / Secret / CRD declarations.

Recipe authors emit auxiliary resources through two channels outside the Workload:

  • Recipe-level artifacts: — for resources intrinsic to this Recipe (a specific ConfigMap the Recipe’s Workload references, a one-off CRD registration the Recipe needs). The field is a map of named entries; each entry is authored inline or loaded via per-entry $import:. See the Artifacts Mechanism section in ../../architecture/16-recipe-input-composition.md for the three authoring modes.
  • Features with Resource Generation — for cross-cutting concerns attached via Release selectors (a ServiceMonitor Feature attached to every component with metrics exposed, a NetworkPolicy Feature attached to every production workload). See ../entities/featurerecipe.md for the FeatureRecipe authoring surface.

The Workload stays focused on the workload shape; cross-cutting and Recipe-intrinsic auxiliary manifests have their own authoring homes.

Common Workload patterns

The Workload schema is broad — it covers single-container HTTP servers, multi-container sidecar patterns, init-container chains, batch jobs, and stateful services with persistent volumes. Three patterns recur frequently enough that authoring boilerplate from scratch per Recipe is wasteful. The blocks below are copy-paste templates Recipe authors can adapt to specific components.

A pattern several Recipes share can be published once as a WorkloadLibrary entry and imported with $import: <Library>#/workloads/<entry>; the templates here are starting points to adapt, or to publish that way.

Pattern 1 — Server with metrics exposure

A typical web application that serves application traffic on one port and exposes Prometheus-scraped metrics on a separate port. Two services in the Workload — one for the application, one for metrics — keeps Service-mesh policy and load-balancer configuration cleanly separable.

apiVersion: aggrega.ai/v1beta1
kind: Workload
replicas: {{ optional .infra `replicas` 2 }}
containers:
app:
image: "{{ .values.image }}"
ports:
web: {{ optional .values `port` 8080 }}
metrics: {{ optional .values `metrics_port` 9090 }}
variables:
LOG_LEVEL: "{{ optional .values `log_level` "info" }}"
health:
ready:
http: /healthz
timeoutSeconds: 5
live:
http: /healthz
timeoutSeconds: 5
services:
http:
type: ClusterIP
ports:
web: {{ optional .values `port` 8080 }}
metrics:
type: ClusterIP
ports:
metrics: {{ optional .values `metrics_port` 9090 }}

The metrics service is typically annotated for Prometheus discovery via a Feature attachment at the Release surface (e.g., feature.aggrega.ai/prometheus-scrape: "true"); the Workload itself stays clean of provider-specific scrape annotations.

Pattern 2 — Batch job

A workload that runs to completion rather than serving traffic indefinitely. The pattern sets form: task, omits services: entirely — batch jobs do not expose ports — and relies on the target provider’s task shape (a Kubernetes Job on the helm provider; the compose provider has no task shape and halts on form: task). The helm provider pins a Job-valid pod restartPolicy (Never unless the container declares OnFailure), since a Job pod cannot use the Always default.

apiVersion: aggrega.ai/v1beta1
kind: Workload
form: task
containers:
worker:
image: "{{ .values.image }}"
command: ["{{ .values.entrypoint }}"]
args:
- "--config"
- "/etc/config/job.yaml"
variables:
JOB_ID: "{{ .context.instance_id }}-{{ .metadata.release_name }}"
volumeMounts:
- name: config
path: /etc/config
volumes:
config:
configmap:
source: "{{ .context.instance_id }}-config"

The config volume references a ConfigMap the Recipe is expected to emit alongside the Workload via artifacts: (see “Auxiliary resources belong outside the Workload” above) — the Workload itself only declares the consumption side. The identity names it on a provider that names the workload after the identity, as compose does; under helm, which names the workload’s resources after the release name, build the ConfigMap’s name — here and in the artifact — from {{ .context.rendered_name }} instead, so it is one the cluster accepts whatever the component is called.

Pattern 3 — Sidecar pair

A two-container pod where the main container handles application logic and the sidecar handles a cross-cutting concern (TLS termination, log shipping, service-mesh proxy, AI guardrail). Author order in containers: is load-bearing — the helm provider emits containers in declared order; the first key (here, main) is the default-container target for kubectl logs and similar tooling.

apiVersion: aggrega.ai/v1beta1
kind: Workload
replicas: {{ optional .infra `replicas` 2 }}
containers:
main:
image: "{{ .values.app_image }}"
ports:
app: {{ optional .values `app_port` 8080 }}
variables:
UPSTREAM_URL: "http://localhost:{{ optional .values `app_port` 8080 }}"
sidecar:
image: "{{ .values.sidecar_image }}"
ports:
proxy: {{ optional .values `proxy_port` 9000 }}
variables:
PROXY_TARGET: "http://localhost:{{ optional .values `app_port` 8080 }}"
services:
external:
type: ClusterIP
ports:
proxy: {{ optional .values `proxy_port` 9000 }}

The Service exposes the sidecar’s port (not the main container’s), routing external traffic through the sidecar to the main container via localhost. The two containers share the pod’s network namespace, so localhost:<port> reaches the peer container directly. For sidecars that need credential injection (the canonical AI-guardrail pattern), the credential typically lives on the sidecar’s attachments: block rather than the main container’s — keeping the credential scoped to the sidecar’s process boundary.

Pattern selection

The three patterns map to distinct shipping-shape concerns:

  • Server with metrics — long-running services that the cluster keeps alive; multiple Service exposures for traffic separation.
  • Batch job — bounded execution; no Service exposure; relies on Recipe-emitted ConfigMap or external state for input.
  • Sidecar pair — multi-container pod with shared network namespace; the sidecar’s Service exposes the cross-cutting concern.

A fourth pattern — stateful server with persistent volume — sets form: stateful and declares per-replica storage via volumes.<name>.persistentTemplate; the helm provider emits a StatefulSet for the stateful form (see providers/helm.md). The pattern is identical in shape to “server with metrics” with form: stateful, an additional persistentTemplate volume, and exactly one type: Headless service to govern the StatefulSet (the build halts without it); authors needing it adapt Pattern 1 with all three declarations.

Cross-references