Secrets and Identities

Reading a secret at runtime takes three steps. Missing any one fails silently at runtime — the API accepts the broken form, the workload starts, and the failure surfaces later as an application error. Control Plane’s own documentation calls a partial version of this its number one support issue.

1. The workload has an identity (spec.identityLink).
2. A policy grants that identity reveal on the secret, naming it as //gvc/GVC/identity/NAME.
3. The reference is field-qualified: cpln://secret/NAME.payload, not cpln://secret/NAME.

SecretAccess owns steps 1 and 2; secretRef() owns step 3.

Field qualifiers by type

Type	Field
opaque	.payload
dictionary	.KEY — one env var per key, or volume-mount as a directory
userpass	.username, .password
tls	.cert, .key
keypair	.publicKey, .privateKey
aws	.accessKey, .secretKey, .roleArn
gcp	unqualified — conventionally a volume-mounted JSON file

Identities

GVC-scoped and not shareable — declare one per GVC with the same spec. A workload has at most one. Do not assign one unless the workload needs secret access, credential-free cloud access, or private networking: an empty assignment complicates audit traces for no benefit.

Values in source

Never. CPL001 fires on recognisable credential shapes at author time, where the finding has a file and a line and the credential has not yet reached git history; CPL012 catches the rest from the model. Read the value from the environment at build time, or set it out of band with cpln secret edit and let chant manage only the secret’s existence and type.