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_HERE

The 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: default

Change 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:

FieldDefault
tokenSecret.namerequired, unless identity is setThe Secret holding the service token.
tokenSecret.namespacethis resource's namespace
tokenSecret.keyserviceTokenThe 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.namerequiredWhat your pods mount. Created if it does not exist.
managedSecret.namespacethis resource's namespace
managedSecret.typeOpaque
resyncSeconds60Minimum 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.
hostthe chart's orcakey.apiBaseUrlHTTPS 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-production

That 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-secrets

kubectl 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.