Skip to content
AggregaAggrega
Select language: English

A policy that attaches Features nobody wrote: annotations injected at `annotation-transform`

A governance policy gives every component of a shop the platform’s monitoring and an AWS IAM role. It does so by adding annotations. The Manifest binds two annotation keys to two Features, and an annotation under a bound key expands into a Feature attachment. So the annotations the policy adds bring a Prometheus ServiceMonitor and a Kubernetes ServiceAccount to each component, and the Aggregate and the Release write neither.

The policy is attached at the annotation-transform role, once for each policy engine compiled into the CLI: Rego and CEL. The central proof is a control Release that writes the same annotations by hand. Built with no policy, it renders the same files, byte for byte, as the Release the policy annotates.

What it builds

instancecatalog Componentwhat it carries in release.yaml
apiexample/compute/servicenothing
workerexample/compute/servicenothing
gatewayexample/compute/serviceits own monitoring annotation, with a 10-second interval

All three are compiled to Kubernetes through Helm, into dist/shop/helm/. example/compute/service is a demonstration Component in the standard-library catalog. Every instance of it must carry a core/prometheus-exporter attachment, a requirement the Component states and the build checks.

The two annotation bindings

manifest.yaml gives two annotation keys a meaning:

features:
type:
core/prometheus-exporter: helm/prometheus-exporter:1.0.0
core/aws-irsa: helm/aws-irsa:1.0.0
annotations:
feature.aggrega.ai/monitoring:
feature: core/prometheus-exporter
maps:
infra:
- interval
- port
- path
aws-role:
feature: core/aws-irsa
maps:
infra:
- role_arn

A binding that routes several subkeys takes an object naming each of them as its value, so feature.aggrega.ai/monitoring takes {interval: …, port: …, path: …}. A binding that routes one subkey takes a string, so aws-role takes the role’s ARN. The attachment an annotation expands into is named after its key. core/aws-irsa names its ServiceAccount after the attachment, which is why that key carries no dot or slash.

Attaching the policy

.aggrega-config.yaml names the hub as its registry and no catalog directory, and no governance attachment. The policy is attached by the file a build names with --config: governance-rego.yaml for the Rego engine, governance-cel.yaml for the CEL engine. The Rego one reads:

plugins:
governance:
- uri: governance/rego:0.9.0
role: annotation-transform
with:
sources:
- policies/platform-defaults.rego

--config names the global configuration file for that run, in place of the one the machine would otherwise read, and this workspace’s .aggrega-config.yaml still layers on top of it.

0.9.0 is a version at which the hub publishes each engine’s Plugin entity, so the attachment resolves from the registry the workspace reads, or from the aggrega binary of that release, which carries it. The engine that runs is the one compiled into the aggrega binary running the build, whatever version the attachment names. The object the monitoring annotation takes needs an engine that injects an object of subkeys, and the engines of releases before 0.8.7 do not.

What an annotation-transform policy reads

A policy at annotation-transform reads two things:

  • input.targets lists every component it may annotate. Each target has a boundary_path, a component_name, and the annotations the Release writes on that component, each value as written.
  • input.binding_keys lists the annotation keys the Manifest binds.

aggrega build --release <release> --dry-run --policy-input <dir> writes the payload each role receives into <dir> and writes nothing else. After a build of release.yaml has filled its lockfile:

Terminal window
aggrega build --release release.yaml --config governance-rego.yaml --dry-run --policy-input payloads
jq -c '.binding_keys' payloads/annotation-transform.json
# ["feature.aggrega.ai/monitoring","aws-role"]
jq -c '.targets[]' payloads/annotation-transform.json
# {"boundary_path":"shop","component_name":"api","annotations":{}}
# {"boundary_path":"shop","component_name":"worker","annotations":{}}
# {"boundary_path":"shop","component_name":"gateway","annotations":{"feature.aggrega.ai/monitoring":{"interval":"10s","port":"metrics","path":"/metrics"}}}

A target’s annotations hold what the Release writes on the component itself. The boundary’s aggrega.ai/namespace is not among them.

The policy

policies/platform-defaults.rego collects one decision per annotation under annotations. Each decision names the target by the two fields it was read under, then the key and the value:

annotations contains {
"boundary_path": t.boundary_path,
"component_name": t.component_name,
"annotation_key": monitoring,
"annotation_value": {"interval": "30s", "port": "metrics", "path": "/metrics"},
} if {
monitoring in input.binding_keys
some t in input.targets
not monitoring in object.keys(t.annotations)
}
annotations contains {
"boundary_path": t.boundary_path,
"component_name": t.component_name,
"annotation_key": role,
"annotation_value": sprintf("arn:aws:iam::123456789012:role/shop-%v", [t.component_name]),
} if {
role in input.binding_keys
some t in input.targets
not role in object.keys(t.annotations)
}

Each rule fires only for a key in input.binding_keys, so the policy adds nothing a Manifest has not given a meaning to. Each rule also skips a target that already carries the key. A decision under a key the component already carries replaces the value the Release wrote. Without that test, gateway would lose its 10-second interval to the policy’s 30 seconds.

policies/platform-defaults.cel states the same two decisions as one expression, joining two lists with +. A map key is tested with in rather than object.keys, and the role’s ARN is joined with +, since the expression language has no sprintf. The role’s half of the expression reads:

+ input.targets
.filter(t, "aws-role" in input.binding_keys
&& !("aws-role" in t.annotations))
.map(t, {
"boundary_path": t.boundary_path,
"component_name": t.component_name,
"annotation_key": "aws-role",
"annotation_value": "arn:aws:iam::123456789012:role/shop-" + t.component_name,
}),

What the build renders

Terminal window
aggrega build --release release.yaml --config governance-rego.yaml --auto-pull

writes twelve files under dist/shop/helm/: a Deployment and a Service for each component, the ServiceMonitor its monitoring annotation expands into, and the ServiceAccount its aws-role annotation expands into. The spec of api’s ServiceMonitor, from the annotation the policy injected:

spec:
selector:
matchLabels:
app.kubernetes.io/name: api
endpoints:
- port: metrics
interval: 30s
path: /metrics

gateway’s carries interval: 10s, the value its Release entry writes. The ServiceAccount api runs under, from the injected aws-role:

apiVersion: v1
kind: ServiceAccount
metadata:
name: api-aws-role
namespace: shop
annotations:
eks.amazonaws.com/role-arn: "arn:aws:iam::123456789012:role/shop-api"
aggrega.ai/boundary-path: shop
aggrega.ai/recipe-uri: "aws-irsa:1.0.0"
[… omitted: the labels, which carry the version of the aggrega binary that built the file]

Injected or written by hand: the same files

release-by-hand.yaml is release.yaml with the annotations the policy injects written on each component by hand. Built with no policy attached,

Terminal window
aggrega build --release release-by-hand.yaml --auto-pull

it writes the same twelve files, byte for byte, as release.yaml with the policy attached on either engine. Nothing is excluded from that comparison: whether an annotation was injected is not recorded in any rendered file. check.sh compares the trees on every run.

The build reads an injected value exactly as it reads the same value written in the Release, so the value expands into the same attachment.

Where the injection is recorded

The build graph records it, and --ir-graph prints the graph. Every component that received an injected annotation carries aggrega.ai/injected-by, naming the plugin, among its Release annotations. After aggrega build --release release.yaml --config governance-rego.yaml --auto-pull --ir-graph, api reads:

"release_annotations": {
"aggrega.ai/namespace": "shop",
"aws-role": "arn:aws:iam::123456789012:role/shop-api",
"aggrega.ai/injected-by": "governance/rego"
},

The record is per component, not per key: gateway carries it too, for its aws-role. Each attachment the annotations expanded into has "origin": "annotation" in the graph, as it would for an annotation written by hand.

The Helm target renders no aggrega.ai/injected-by annotation, and it says so. In this build, each component that received an injection adds three warnings to the output. The first of api’s reads:

warning: node "api" (provider "helm"): target "helm" does not support annotation aggrega.ai/injected-by on synthesized input and ignored it

--no-unsupported-field-warnings silences that class of warning, and changes nothing the build writes.

The role adds annotations, and nothing else

A decision names one component, one annotation key and its value. Nothing in a decision adds a component, changes a label, or attaches a Feature directly. The policy reaches a Feature only through a key the Manifest binds, and the Manifest decides which Feature that is.

A decision cannot remove an annotation either. Its value is a string or an object of subkeys, and a null is refused, naming the injection, because null is how an author opts a component out of an annotation it would inherit.

A string where the binding routes three subkeys

governance-monitoring-as-string.yaml attaches policies/monitoring-as-string.rego, which injects the string "30s" under the monitoring key. That binding routes three subkeys, and a string names none of them, so

Terminal window
aggrega build --release release.yaml --config governance-monitoring-as-string.yaml --auto-pull

halts, exits 1 and writes no dist/. The policy injected the string on api and on worker, and each is refused. Each refusal names the plugin that injected the value and the role it is attached at, so the value is traced to the policy that decided it, rather than to a line of the Release nobody wrote:

[… omitted: a warning that the attachment is in the global configuration named with --config]
[OPS_ERROR E0367] .spec.boundaries.shop.components.api.annotations
a scalar annotation value does not route to exactly one path of its binding (Release shop-production, at .spec.boundaries.shop.components.api.annotations, "feature.aggrega.ai/monitoring", carrying the bare value "30s", whose binding routes "interval, port, path", whose value plugin "governance/rego" injected at governance role "annotation-transform")
---
[OPS_ERROR E0367] .spec.boundaries.shop.components.worker.annotations
a scalar annotation value does not route to exactly one path of its binding (Release shop-production, at .spec.boundaries.shop.components.worker.annotations, "feature.aggrega.ai/monitoring", carrying the bare value "30s", whose binding routes "interval, port, path", whose value plugin "governance/rego" injected at governance role "annotation-transform")

Without the policy

release.yaml built with no governance attachment,

Terminal window
aggrega build --release release.yaml --auto-pull

halts. Its Component requires a core/prometheus-exporter attachment, and nothing gives one to api or worker:

[DEVELOPER_ERROR E0162] aggregate.yaml at .spec.components.api
missing required feature: attach a Feature of the required type to the component ("core/prometheus-exporter", required by component type "example/compute/service", under the requirement label "monitoring")
---
[DEVELOPER_ERROR E0162] aggregate.yaml at .spec.components.worker
missing required feature: attach a Feature of the required type to the component ("core/prometheus-exporter", required by component type "example/compute/service", under the requirement label "monitoring")

gateway is not named, because its Release entry writes its own monitoring. With the policy attached, the same Release builds: an attachment that an injected annotation expands into meets the requirement, just as one written by hand does.

What the lockfile records

An annotation-transform attachment changes what the build renders, so the lockfile pins it. After the Rego build, release.lock carries the attachment under mutators:, with its plugin, its role, and the content and digest of its policy file:

mutators:
- plugin: governance/rego
role: annotation-transform
sources:
- content: |
[… omitted: the policy file, as written]
digest: sha256:9779faf366fc131b1a56ea68ccbae811173e3642943909f8d4ca63c00df8781b
path: platform-defaults.rego

It also pins the plugin under plugins::

plugins:
- uri: governance/rego
[… omitted: the artifact digest, which depends on the aggrega binary that built it, recorded twice]
referenced_from:
- governance/rego:0.9.0

The attachment names a version the hub publishes, so the pin resolves through the registry the workspace reads, or from the aggrega binary of that release.

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 policy-annotation-transform

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

Terminal window
cd policy-annotation-transform

Build

Terminal window
aggrega build --release release.yaml --config governance-rego.yaml --auto-pull
aggrega build --release release.yaml --config governance-cel.yaml --auto-pull
aggrega build --release release-by-hand.yaml --auto-pull

The standard-library catalog supplies every Component, Feature, Recipe and FeatureRecipe here, and both engines’ Plugin entities. They resolve from hub.aggrega.ai, the default registry .aggrega-config.yaml names. With a checkout of the catalog (where to get one) named with --catalog, nothing is fetched from a registry, so the builds run offline. --auto-pull fills each Release’s lockfile during the build. Lockfiles and the rendered output are generated, not shipped.

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 `policy-annotation-transform` folder yet, call the `scaffold` tool once with `example` set to `policy-annotation-transform` and no `dir`: it writes the example into a new `policy-annotation-transform` folder. Then call the `cli-build` tool, which runs `aggrega build` and takes its `--config` flag, with `workspace_root` set to `policy-annotation-transform`, `release` set to `release.yaml`, `auto_pull` set to true and `config` set to `governance-rego.yaml`; then call it again the same way with `config` set to `governance-cel.yaml`. Last, call the `build` tool with `workspace_root` set to `policy-annotation-transform`, `release` set to `release-by-hand.yaml`, `auto_pull` set to true and `write` set to true. Tell me which files each build wrote; they are under `policy-annotation-transform/dist/`.

Checking every build

This self-check runs in a checkout of the documentation repository, which holds the shared build helper it uses; a copy written by aggrega scaffold --example does not carry that helper.

Terminal window
./check.sh

check.sh makes five builds through the build-release helper and checks each outcome against the one this page describes:

  • release-by-hand.yaml with no policy is the reference. It must render the six files the annotations expand into.
  • release.yaml with no policy must halt with E0162 for api and worker, and for no other component.
  • release.yaml with the policy is built once on each engine. Each build must write the reference’s files byte for byte, pin the plugin in its lockfile, and record all three components as injected by that plugin.
  • release.yaml with the planted string must halt with the refusal above.

It prints one line per build, then the files the two bindings rendered, and exits 1 if any outcome differs, printing that build’s output:

POLICY RELEASE EXIT EXPECTED VERDICT
----------------------------------------------------------------------------------------------------
none release-by-hand.yaml 0 reference OK: the six attachments' files
none release.yaml 1 halt OK: E0162 for api and worker
rego release.yaml 0 pass OK: byte-identical to the build by hand; pinned; injected
cel release.yaml 0 pass OK: byte-identical to the build by hand; pinned; injected
string release.yaml 1 halt OK: refused, naming the plugin and its role
files the two annotation bindings rendered, release.yaml with governance-rego.yaml:
shop/helm/api--aws-role--api-serviceaccount-shop-api-aws-role.yaml
shop/helm/api--feature-zdaggrega-zdai-zsmonitoring--api-servicemonitor-shop-api-scrape.yaml
shop/helm/gateway--aws-role--gateway-serviceaccount-shop-gateway-aws-role.yaml
shop/helm/gateway--feature-zdaggrega-zdai-zsmonitoring--gateway-servicemonitor-shop-gateway-scrape.yaml
shop/helm/worker--aws-role--worker-serviceaccount-shop-worker-aws-role.yaml
shop/helm/worker--feature-zdaggrega-zdai-zsmonitoring--worker-servicemonitor-shop-worker-scrape.yaml
check: every build ended as expected.

Each build runs in its own copy of this workspace, made in a temporary directory, with the catalog path in its .aggrega-config.yaml made absolute so that it still resolves from there. Nothing in this directory is written. It uses the binary the build-release helper resolves, so AGGREGA_BIN chooses it, and arguments after -- reach every build. Its exit status is the whole verdict.

Where the compiler does not interpret

The compiler hands the policy the components and the bound keys. It adds the annotations the policy decides, and expands them through the Manifest’s bindings as it expands any annotation. It does not know that a service should be monitored, what a scrape interval is, or which IAM role a component should run under: those meanings belong to the policy and the Manifest. For the roles, the payloads and the decision keys, see the governance socket. For annotation expansion with no policy, see annotation-driven-monitoring.

Files

  • aggregate.yaml — the three services, with no annotation.
  • manifest.yaml — binds the component type and the two Features to their Helm Recipes, and the two annotation keys to the two Features.
  • release.yaml — the Release the policy annotates; only gateway writes an annotation.
  • release-by-hand.yaml — the control: every annotation written by hand.
  • .aggrega-config.yaml — the default registry; no governance attachment.
  • governance-rego.yaml, governance-cel.yaml — the policy attached at annotation-transform through each engine, each named with --config.
  • governance-monitoring-as-string.yaml — the planted mistake, named with --config.
  • policies/platform-defaults.rego, policies/platform-defaults.cel — the policy, once per engine.
  • policies/monitoring-as-string.rego — the planted mistake.
  • build-release.sh — builds one Release, echoing the equivalent aggrega build command.
  • check.sh — makes the five builds and checks each outcome.