Projecting an environment
Your first Secret: one token, one OrcaKeySecret, one Secret.
Projecting an environment takes two things in the cluster: a Secret holding
a service token, and an OrcaKeySecret that says where the environment should
land. Both live in orcakey-operator; the managed Secret lands in your
app's namespace. To skip the token, authenticate as the
cluster instead.
Mint a service token
Mint a read token for <your-environment> from Integrations → Kubernetes
or Service tokens. The token decides the environment: the resource below
does not name one.
Put the token in the cluster
kubectl -n orcakey-operator create secret generic orcakey-secrets-token \
--from-literal=serviceToken=PASTE_TOKEN_HEREThe operator does not renew the token. Before it expires, mint a new one and
replace the value in this Secret; the next resync picks it up, with nothing
to restart. See Service tokens.
Ask for the environment
apiVersion: secrets.orcakey.sh/v1beta1
kind: OrcaKeySecret
metadata:
name: orcakey-secrets
namespace: orcakey-operator
spec:
# <your-project> / <your-environment>
tokenSecret:
name: orcakey-secrets-token
managedSecret:
name: orcakey-secrets
namespace: defaultChange managedSecret.namespace to the namespace your app reads from, then
kubectl apply -f it. The Secret appears there within seconds, and the
environment's page in orcakey.sh shows it as a new column, holding every key
in <your-environment> and set to receive new ones — what a resource
with no scope has always received. Untick a key in that column and save, and
the next sync drops it from the Secret; nothing about this is set in YAML.
If you would rather choose the keys before the first fetch, use Add to Kubernetes on the environment page instead of writing the YAML by hand: it makes the column with no keys ticked and gives you the YAML to apply once you are ready.
The full set of fields:
| Field | Default | |
|---|---|---|
| tokenSecret.name | required, unless identity is set | The Secret holding the service token. |
| tokenSecret.namespace | this resource's namespace | |
| tokenSecret.key | serviceToken | The key within it. |
| identity.environmentId | — | Authenticate as the cluster instead of with a token. Only in orcakey-operator; set this or tokenSecret, not both. |
| managedSecret.name | required | What your pods mount. Created if it does not exist. |
| managedSecret.namespace | this resource's namespace | |
| managedSecret.type | Opaque | |
| resyncSeconds | 60 | Minimum 15. |
| collections | — | Kept for one release. While set, the column on the environment page is read-only and shows these names; remove the field to hand the Secret to the matrix with the same keys. New resources should leave it out. |
| host | the chart's orcakey.apiBaseUrl | HTTPS only. |
An OrcaKeySecret in orcakey-operator may name any namespace. One anywhere
else may name only its own; see
What it may do.
Use it
envFrom:
- secretRef:
name: orcakey-cayote-studio-productionThat is the whole integration. Your application reads environment variables and does not know orcakey.sh exists.
Check it worked
kubectl -n orcakey-operator get orcakeysecrets
kubectl -n default get secret orcakey-secretskubectl get orcakeysecrets shows the last sync, the key count, and the
Secret it writes. kubectl describe shows the Ready condition and its
reason.
When a value changes
Every resyncSeconds the operator compares key names and change times. When
something changed it overwrites the whole Secret with exactly the keys
ticked in its column — every key in the environment, until somebody
narrows it. When nothing changed it does nothing: no value is read, no audit
record is written, and the Secret is not touched.
A key unticked in the column, or removed in orcakey.sh, is removed from the
Secret. So is any key somebody added to the Secret by hand: the operator
owns all of it.
Deleting the resource
A Secret in the same namespace as its OrcaKeySecret carries an
ownerReference to it and is deleted with it. A Secret in another namespace
cannot carry one, so it is left in place; delete it yourself if you no longer
want it.
Removing the column on the environment page only works once its
OrcaKeySecret has stopped fetching: while it is still live, the next sync
would bring the column straight back, so the page asks you to delete the
resource first. The keys stay in the environment either way.