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.

  1. 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/jwks

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

  2. Let an unauthenticated reader see the discovery documents

    orcakey.sh fetches /.well-known/openid-configuration and 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:unauthenticated

    and anonymous-auth=true added to the kube-apiserver-arg list above. Upstream Kubernetes ships with anonymous auth on; k3s turns it off, and with it off the fetch gets 401 no 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-configuration
  3. Put 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+insecure because the hop to 127.0.0.1 is 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.

  1. Find your issuer

    kubectl get --raw /.well-known/openid-configuration | jq -r .issuer
  2. Register 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 subject system:serviceaccount:orcakey-operator:orcakey-connector. There is no wildcard. Four clusters is four registrations.

    A registration grants nothing by itself.

  3. 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 no OrcaKeySecret syncs nothing.

  4. 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.sh

    Since 1.0.1 the chart always mounts the projected token, so there is nothing to switch on. Two values shape it:

    ValueDefault
    identity.audienceorcakey.shMust match the registration. Never the API server's own, or the ambient token every pod mounts would be accepted.
    identity.expirationSeconds3600How often the kubelet rotates the file. The operator re-reads it on every exchange.

    The subject comes from the release: install it as orcakey-connector in orcakey-operator, as above, or register the subject your release actually runs as.

  5. 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: default

    identity.environmentId names the environment, because no token carries it. Set identity or tokenSecret, 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-only collections field; 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

ReasonWhat it means
NamespaceNotAllowedThe resource sets identity outside orcakey-operator.
MisconfiguredNo identity token is mounted at /var/run/secrets/orcakey.sh/identity/token, or no API is configured.
Unauthorisedorcakey.sh refused the exchange: no registration matches this issuer, audience and service account, or the issuer's keys could not be fetched.
ForbiddenThe cluster is registered, but the environment is not assigned to it.
NotFoundorcakey.sh does not know identity.environmentId.
Unreachableorcakey.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.