Secret Access Setup

Tool availability: the typed create_secret_<type> / update_secret_<type> tools span profiles — opaque, tls, docker, ecr, dictionary are core; aws, azure-connector, nats-account, userpass need full; azure-sdk, gcp, keypair need mk8s. If a type's tool isn't advertised, reconnect with ?toolsets=full (or mk8s) or use the cpln CLI. The grant/read tools (workload_reveal_secret, reveal_secret) and all reads/deletes work on every profile.

Secret access is the #1 thing users get wrong: a workload reads a secret only when three things are all in place. Miss any one and the value is silently absent at runtime — or the deployment pauses on an unresolved reference.

The mandatory chain

reveal, not view — view exposes only metadata. This is the single most common mistake.

Pull secrets are different — no identity/policy

To pull images from a private registry, don't build the chain. Add the registry secret to the GVC's pullSecretLinks and every workload in that GVC can pull. Pull secrets are registry credentials — docker, ecr, or gcp types.

kind: gvc
spec:
  pullSecretLinks:
    - //secret/my-registry

Workflow

1 — Create or identify the secret

Each of the 12 types has a typed create_secret_<type> tool exposing only that type's fields (no generic data blob): opaque, dictionary, userpass, aws, gcp, azure-sdk, azure-connector, docker, ecr, tls, keypair, nats-account. Reuse an existing secret with list_resources (kind="secret"). CLI fallback: cpln secret create-<type>.

2 — Grant the workload access

Preferred — one call. workload_reveal_secret (gvc, workloadName, secretName) creates the identity if missing (default {gvc}-{workloadName}), links it to the workload, and creates/updates a reveal policy (default {gvc}-{workloadName}-secrets-policy). If the workload already has an identity it reuses it. It does not inject the reference — step 3 still applies.

Ordering matters. The workload must already exist. For a new workload that references a secret: create_workload first (its deployment pauses on the unresolved reference), then workload_reveal_secret resumes it. Never grant before the workload exists.

Manual alternative (granular control): create_identity → update_workload to set spec.identityLink → create_policy (targetKind secret, a reveal binding naming the identity). Policy shape lives in access-control.

Identities are GVC-scoped: one per workload, shareable across workloads in the same GVC, never across GVCs.

3 — Inject the reference

update_workload (read current state with get_resource first) to add cpln://secret/NAME — the whole secret — or cpln://secret/NAME.KEY for one property:

Inject as an env var or a volume mount ({ uri: "cpln://secret/NAME", path: "/secrets/x" }). Mounts are read-only (except Azure Files), max 15 per container, and these knative-reserved paths are rejected: /dev, /dev/log, /tmp, /var, /var/log.

4 — Verify and redeploy

• get_resource (kind="workload") → spec.identityLink is set and the env/volume reference reads cpln://secret/….
• get_resource (kind="policy") → the binding grants reveal to that identity.
• Break-glass plaintext check: reveal_secret (needs reveal).
• Updating a workload spec redeploys automatically; via CLI use cpln apply --ready to block until healthy. A rotated secret value needs a redeploy — running replicas keep the old value until then.

Quick reference — MCP tools

Common mistakes

• No identity — a workload with no identityLink reads no secrets.
• `view` instead of `reveal` — metadata only, no value.
• Bad reference — must be cpln://secret/NAME, not the bare name.
• Granting before the workload exists — workload_reveal_secret requires it.
• Sharing an identity across GVCs — they are GVC-scoped.
• Over-engineering pull secrets — registries need only pullSecretLinks, no identity/policy.
• Skipping the redeploy after rotation — running replicas keep the old value.

Related skills

Documentation

• Secret Reference