Authenticating as the cluster
No orcakey.sh credential in your cluster at all.
Instead of a service token, an OrcaKeySecret can authenticate as the
cluster. The operator presents the token Kubernetes already mints for its
service account; orcakey.sh checks it against your cluster's published signing
keys and issues a credential for one environment that lasts ten minutes and is
held only in the operator's memory.
Nothing to store, nothing to rotate, nothing to find in a backup.
What your cluster must do
orcakey.sh reads <issuer>/.well-known/openid-configuration over https.
EKS, GKE and AKS publish one. A self-managed cluster whose issuer is
https://kubernetes.default.svc does not, and needs --service-account-issuer
pointed somewhere reachable — a decision about your cluster, not about
orcakey.sh.
If that is not something you want to do, use a service token instead.
Self-managed clusters, the whole recipe
On a managed cluster the issuer already works and you can skip to the steps below. On k3s (and most kubeadm clusters) three things stand between you and a working registration, and each one fails quietly on its own. Shown for k3s; the flags are plain kube-apiserver flags everywhere.
Give the issuer a reachable https name
In
/etc/rancher/k3s/config.yaml:kube-apiserver-arg: - service-account-issuer=https://k8s.example.com - service-account-issuer=https://kubernetes.default.svc.cluster.local - service-account-jwks-uri=https://k8s.example.com/openid/v1/jwksthen restart k3s. The first issuer is the one new tokens carry — and the one you register. Keeping the old issuer second means every token minted before the change still verifies, so running workloads do not notice.
Let an unauthenticated reader see the discovery documents
orcakey.sh fetches
/.well-known/openid-configurationand the JWKS with no credential at all. That needs two things, and k3s clusters need both:kubectl create clusterrolebinding oidc-discovery \ --clusterrole=system:service-account-issuer-discovery \ --group=system:unauthenticatedand
anonymous-auth=trueadded to thekube-apiserver-arglist above. Upstream Kubernetes ships with anonymous auth on; k3s turns it off, and with it off the fetch gets401no matter what RBAC says. Turning it back on grants anonymous callers only what RBAC grants them — with the binding above, the discovery documents and nothing else.The test that settles it — no kubeconfig anywhere near it:
curl https://k8s.example.com/.well-known/openid-configurationPut a real certificate in front
orcakey.sh will not accept your cluster CA — the fetch verifies against public roots, like every other https client. Any proxy that terminates TLS with a real certificate and forwards to the API server works. With Tailscale it is one line on the node:
tailscale serve --bg --https=443 https+insecure://127.0.0.1:6443(
https+insecurebecause the hop to127.0.0.1is verified by being local, not by its self-signed cert. HTTPS certificates must be enabled for your tailnet, and the name must resolve from wherever orcakey.sh runs.)Caddy, nginx with certbot, or a cloud load balancer with ACM do the same job. Whatever the front door, the name it serves is the name in
service-account-issuer— exactly, scheme and all.
Find your issuer
kubectl get --raw /.well-known/openid-configuration | jq -r .issuerRegister the cluster
Integrations → Kubernetes → Setup, choose Cluster identity, and paste the issuer. Owners only, and once per cluster.
The registration names three things and matches all of them exactly: that issuer, the audience
orcakey.sh, and the subjectsystem:serviceaccount:orcakey-operator:orcakey-connector. There is no wildcard. Four clusters is four registrations.A registration grants nothing by itself.
Assign the environment to the cluster
In the same place, or from the cluster's row under Projections, assign
<your-environment>to the cluster. An assignment is the permission and nothing more: one environment, made by an Owner, recorded in the audit log. The operator does not read assignments or create anything from them; a cluster with ten assignments and noOrcaKeySecretsyncs nothing.Install the operator
The image and the chart are private for now:
kubectl create namespace orcakey-operator --dry-run=client -o yaml | kubectl apply -f - kubectl -n orcakey-operator create secret docker-registry ghcr-pull \ --docker-server=ghcr.io \ --docker-username=YOUR_GITHUB_USERNAME \ --docker-password=YOUR_READ_PACKAGES_TOKEN \ --dry-run=client -o yaml | kubectl apply -f -helm registry login ghcr.io --username YOUR_GITHUB_USERNAME helm install orcakey-connector oci://ghcr.io/bluepawlabs/charts/orcakey-connector \ --version 1.1.0 \ --namespace orcakey-operator \ --set registry.existingSecret=ghcr-pull \ --set orcakey.apiBaseUrl=https://api.orcakey.shSince 1.0.1 the chart always mounts the projected token, so there is nothing to switch on. Two values shape it:
Value Default identity.audience orcakey.sh Must match the registration. Never the API server's own, or the ambient token every pod mounts would be accepted. identity.expirationSeconds 3600 How often the kubelet rotates the file. The operator re-reads it on every exchange. The subject comes from the release: install it as
orcakey-connectorinorcakey-operator, as above, or register the subject your release actually runs as.Ask for the environment
apiVersion: secrets.orcakey.sh/v1beta1 kind: OrcaKeySecret metadata: name: orcakey-secrets namespace: orcakey-operator spec: # <your-project> / <your-environment> identity: environmentId: <your-environment-id> managedSecret: name: orcakey-secrets namespace: defaultidentity.environmentIdnames the environment, because no token carries it. SetidentityortokenSecret, never both; the API server refuses a resource with both or neither. Every other field works as it does with a token, including the first-fetch column and the one-release-onlycollectionsfield; see Projecting an environment.
Only in the operator's namespace
An OrcaKeySecret may use identity only in orcakey-operator. The
cluster's identity is the operator's own credential, and it can read every
environment assigned to the cluster; letting any namespace borrow it would let
any team read all of them. Anywhere else the resource reports
NamespaceNotAllowed
and nothing is read. A team managing its own Secrets in its own namespace uses
a tokenSecret.
When it is refused
| Reason | What it means | |
|---|---|---|
NamespaceNotAllowed | The resource sets identity outside orcakey-operator. | |
Misconfigured | No identity token is mounted at /var/run/secrets/orcakey.sh/identity/token, or no API is configured. | |
Unauthorised | orcakey.sh refused the exchange: no registration matches this issuer, audience and service account, or the issuer's keys could not be fetched. | |
Forbidden | The cluster is registered, but the environment is not assigned to it. | |
NotFound | orcakey.sh does not know identity.environmentId. | |
Unreachable | orcakey.sh could not be reached, was rate-limiting, or answered with a server error. |
orcakey.sh tells an unauthenticated caller as little as it can about why, so
check all of them: the registration's issuer against the issuer command above,
identity.audience against the registration, the release name and namespace
against the subject, and the assignment.
What changes day to day
Nothing visible. The operator exchanges again two minutes before each credential expires, holds it in memory, and never writes it anywhere.
Every issuance is its own audit record, and the clusters view's "last seen" is derived from exactly these authenticated asks, never from anything a cluster says about itself.
Turning it off
Removing an assignment stops the next exchange for that environment, and the
next sync reports Forbidden. Removing the registration revokes every
credential it issued, on the next request, and the next sync reports
Unauthorised. Either way the Secrets already written
remain in the cluster: delete the OrcaKeySecret to remove one beside it.