Sharing a credential — per-consumer, shared, and both at once
Two CrewAI agents behind one OpenAI-compatible gateway. Each agent’s model
socket declares a credential slot, so the key an agent presents to the model
it reaches is attached on that connection. This workspace fills the slot three
ways without changing a single catalog entity: a key per connection, one Secret
every connection points at, and a shared default one connection overrides.
Two consumers is the point. The three forms are indistinguishable with a single consumer — the difference is which Secret each consumer ends up pointing at, and that question has no content until there is more than one consumer.
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 model-api-key-sharingIt then prints the commands to run next. The first changes into the new folder:
cd model-api-key-sharingBuild
Three releases, one per form. Build one per run:
aggrega build --release release-per-consumer.yaml --auto-pull # → dist/per-consumer/aggrega build --release release-shared.yaml --auto-pull # → dist/shared/aggrega build --release release-composed.yaml --auto-pull # → dist/composed/Each release writes to its own directory, so all three rendered trees coexist and can be diffed against each other.
A release needs its lockfile before it builds. On a fresh checkout, resolve one first — either as its own step or by letting the build fill it:
aggrega pull --release release-shared.yaml # resolve, then build normallyaggrega build --release release-shared.yaml --auto-pull # or resolve during the buildThe releases resolve their catalog entities from the configured catalog, so no
--catalog flag is needed.
All three build on the helm target, deliberately. The observable that separates
the three forms is the name of the Secret each agent’s container references,
and helm is where a credential is a named Kubernetes Secret that a container
references by name. Two Manifests bind the credential: manifest.yaml to
k8s-secret-from-parameter, which renders a Secret from the value the
attachment carries, for the per-consumer release; and
manifest-existing-secret.yaml to k8s-existing-secret, which renders nothing
and points each consumer at a Secret already in the namespace, for the shared
and composed releases.
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 `model-api-key-sharing` folder yet, call the `scaffold` tool once with `example` set to `model-api-key-sharing` and no `dir`: it writes the example into a new `model-api-key-sharing` folder. Then call the `build` tool once for each Release, in this order — `release-per-consumer.yaml`, `release-shared.yaml` and `release-composed.yaml` — each time with `workspace_root` set to `model-api-key-sharing`, `release` set to that file, `auto_pull` set to true and `write` set to true. Tell me which files each build wrote; they are under `model-api-key-sharing/dist/`.Per-consumer — each connection holds its own key
aggregate-per-consumer.yaml fills the slot on each agent’s connection, with a
different origin per agent:
researcher: type: core/ai-agent/crewai uses: model: gateway: target: gateway features: credential: type: core/referenced-secret values: key: OPENAI_API_KEY origin: researcher-key-change-meAn attachment on a connection becomes one of the agent’s own attachments, named
for the connection and the slot — here gateway.credential — so two Secrets are
emitted, one per agent, each carrying that agent’s own material:
[… omitted: the apiVersion and the Secret kind]metadata: name: researcher-gateway.credential [… omitted: the labels and annotations every rendered document carries]stringData: OPENAI_API_KEY: "researcher-key-change-me"
# dist/per-consumer/helm/writer--gateway-zdcredential--writer-secret-writer-gateway-credential.yaml[… omitted: the apiVersion and the Secret kind]metadata: name: writer-gateway.credential [… omitted: the labels and annotations every rendered document carries]stringData: OPENAI_API_KEY: "writer-key-change-me"and each Deployment references its own:
- name: OPENAI_API_KEY valueFrom: secretKeyRef: name: researcher-gateway.credential key: OPENAI_API_KEY
# dist/per-consumer/helm/writer-deployment.yaml- name: OPENAI_API_KEY valueFrom: secretKeyRef: name: writer-gateway.credential key: OPENAI_API_KEYRevoking one agent’s key leaves the other running.
Shared — one Secret, referenced from each connection
A credential on a connection is written on that connection: nothing attached elsewhere fills it. So several consumers share one credential by authoring: each connection’s credential reads the same value, and that value names one Secret.
aggregate-shared.yaml declares one parameter and reads it on both
connections:
parameters: team_model_key: type: string default: team-model-keycomponents: researcher: uses: model: gateway: target: gateway features: credential: type: core/referenced-secret values: key: OPENAI_API_KEY origin: "{{ .parameters.team_model_key }}" writer: { ... } # the same credential, reading the same parameterThe release binds the credential to k8s-existing-secret, which reads origin
as the name of a Secret that already exists in the namespace. It renders no
Secret at all — only the gateway’s Service and the two Deployments are written —
and both Deployments reference the one Secret the parameter names:
- name: OPENAI_API_KEY valueFrom: secretKeyRef: name: team-model-key key: OPENAI_API_KEY
# dist/shared/helm/writer-deployment.yaml- name: OPENAI_API_KEY valueFrom: secretKeyRef: name: team-model-key key: OPENAI_API_KEYThat is exactly one physical Secret, created outside the Release by whoever deploys it, and read by every consumer. The key’s material never passes through an authored file or a rendered artifact.
What the parameter carries follows the realization the Manifest binds. Under
k8s-existing-secret it is a Secret’s name. Bound instead to
k8s-secret-from-parameter, the same two connections reading one parameter
would carry the key itself, and the build would render one Secret per consumer,
each holding the same material: rendering runs per component, and that
realization names the Secret it renders after the consuming component and the
connection. The one parameter is what keeps the consumers from drifting apart;
which realization reads it decides whether they share a resource. A credential
generated in the cluster is shared the same way — one request and many
references; see Credential Model.
Composed — shared default, one connection overriding
aggregate-composed.yaml keeps the shared parameter as the default and lets one
connection name a Secret of its own:
researcher: uses: model: gateway: target: gateway features: credential: type: core/referenced-secret values: key: OPENAI_API_KEY origin: researcher-model-key # this connection's own Secretwriter: uses: model: gateway: target: gateway features: credential: type: core/referenced-secret values: key: OPENAI_API_KEY origin: "{{ .parameters.team_model_key }}" # the shared defaultThe override is what that one connection authors; nothing cascades onto it, and
writer keeps the shared Secret untouched:
- name: OPENAI_API_KEY valueFrom: secretKeyRef: name: researcher-model-key key: OPENAI_API_KEY
# dist/composed/helm/writer-deployment.yaml- name: OPENAI_API_KEY valueFrom: secretKeyRef: name: team-model-key key: OPENAI_API_KEYA connection’s credential is a whole attachment of its own, so an override
restates every field it needs — here the Feature type, key and origin — and
inherits none from the default.
What the slot buys
core/ai-agent/crewai declares the slot once, on its model socket, and the
three forms are all choices made in the Aggregate:
usesSchema: model: selector: "component.aggrega.ai/category in (ai-model, gateway), model.aggrega.ai/api" required: true inject: [env, file] featuresSchema: credential: selector: "feature.aggrega.ai/kind=secret" sensitive: true inject: [env]The slot is optional, so a fourth shape is attaching nothing at all: drop the
features: block from both connections and the rendered tree loses every
OPENAI_API_KEY env entry, leaving the two Deployments and the gateway Service.
Nothing is invented to fill the gap. The catalog entity is identical in every
case; the author decides.
That builds because the gateway here, core/ai-model/openai-compatible, carries
no component.aggrega.ai/hosting label. A connection reaching a target the
catalog labels managed — core/ai-model/openai, say — with no credential halts
the build on the agent’s own assertion, unless the connection says in its
values that the target takes none, unauthenticated: true.
The slot is also family-agnostic (feature.aggrega.ai/kind=secret admits either
credential family), which is what lets the same agent take a referenceable
Secret on helm and an inject-value credential on compose.
Credential delivery — secretKeyRef end-to-end
works that provider split, and its negative release shows what happens when a
non-referenceable credential is asked to satisfy a reference.
Determinism
All three releases build under --verify-determinism, which renders every node
twice and compares the emitted bytes:
aggrega build --release release-shared.yaml --auto-pull --verify-determinismRebuilding any of the three from a clean tree reproduces its rendered output byte-for-byte.