Binding a workload to what an attachment publishes
A single stateless app rendered on Kubernetes by the helm provider’s Workload synthesis — no external chart. The app runs under a cloud identity its Component declares a slot for and the Release fills: the attachment filling the slot emits one Kubernetes ServiceAccount and publishes its name, and the app’s Recipe binds the pod to that published name.
The teaching point is the direction of the flow. The producer states the name once; the consumer reads it. Nothing on the consuming side restates a value the producer already owns, so the two cannot drift apart.
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 workload-identity-bindingIt then prints the commands to run next. The first changes into the new folder:
cd workload-identity-bindingBuild
aggrega build --release release.yaml --auto-pullThe catalog resolves from two sources named in .aggrega-config.yaml: the
example’s own ./catalog (the local/compute/identity-app Component and its
helm/identity-app synth Recipe) and the hub registry (the
core/gcp-workload-identity Feature and its FeatureRecipe). --auto-pull writes
the lockfile a fresh clone lacks during the build.
Three manifests land under dist/helm/helm/.
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 `workload-identity-binding` folder yet, call the `scaffold` tool once with `example` set to `workload-identity-binding` and no `dir`: it writes the example into a new `workload-identity-binding` folder. Then call the `build` tool with `workspace_root` set to `workload-identity-binding`, `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 `workload-identity-binding/dist/`.The Component declares the need; the Release fills it
The app needs an identity to run under, so its Component declares one, as a
required identity slot:
featuresSchema: identity: required: true selector: "feature.aggrega.ai/kind!=secret" inject: []The Aggregate writes nothing for it. Which identity the app runs under, on which cloud, is the Operator’s choice for each target, so the Release fills the slot with the identity Feature and every field that Feature needs:
features: identity: type: core/gcp-workload-identity infra: service_account_name: app-workload-identity gcp_service_account: app-dev@example-project.iam.gserviceaccount.comA Release that leaves the slot unfilled halts, naming the slot. A Release for an
EKS cluster fills the same slot with core/aws-irsa and its role_arn instead,
and its Manifest maps that Feature to its FeatureRecipe. The selector keeps a
credential out of the slot: a secret-kind Feature filling it halts.
The attachment publishes
The Feature declares in its schema.provides that it publishes a name, and its
FeatureRecipe publishes it — from the same local the emitted chart names the
ServiceAccount with, which is the operator-set service_account_name when the
Release writes one:
# FeatureRecipe gcp-workload-identitylocals: sa_name: '{{ default (printf "%s-%s" .context.rendered_name (.attachment_name | replace "_" "-")) .infra.service_account_name }}'provides: name: "{{ .locals.sa_name }}"The Recipe consumes
The consuming Recipe reads the published name at
.features.<instance-name>.provides.<key>:
# helm/identity-app recipe workloadserviceAccount: "{{ .features.identity.provides.name }}"containers: main: variables: IDENTITY_SERVICE_ACCOUNT: {{ .features.identity.provides.name }}Both reads resolve to the ServiceAccount the attachment actually emitted:
[… omitted: the apiVersion]kind: ServiceAccountmetadata: name: app-workload-identity annotations: iam.gke.io/gcp-service-account: "app-dev@example-project.iam.gserviceaccount.com" [… omitted: the boundary and recipe annotations, and the labels, that every rendered document carries][… omitted: the Deployment's metadata, selector and pod template up to the containers] containers: - name: main [… omitted: the image and the port] env: [… omitted: the GREETING variable] - name: IDENTITY_SERVICE_ACCOUNT value: app-workload-identity serviceAccountName: app-workload-identityWhy read it rather than repeat it
The alternative is to write app-workload-identity a second time on the
consuming side. That works until someone changes the Operator’s
service_account_name and updates only one of the two places — at which point
the pod requests a ServiceAccount that does not exist, and nothing in the
compilation notices, because both spellings are valid strings.
Reading .features.identity.provides.name removes the second spelling. The same
shape applies to every attachment: a credential publishes its Secret’s locator at
.features.<slot>.provides.name, a sidecar publishes its port, an identity
publishes its name. The full field-by-field attachment shape is at
templates/template-context-contract.md.
Operator sizing
release.yaml fulfills the operator-sizing pillar per environment: the container
image tag comes from infra.image_tag (myapp:1.2), and the identity — its
Feature and that Feature’s fields — comes from the slot’s fill. The Developer’s
Aggregate carries neither.