Skip to main content
Every Kubernetes cluster signs tokens for its service accounts. With workload identity federation, a pod mounts one of those tokens, and the KERNEL SDK exchanges it for a KERNEL access token. You don’t create a Kubernetes Secret holding a KERNEL_API_KEY. This guide works for any cluster whose OIDC discovery document and signing keys are reachable from the public internet. Managed services such as EKS publish them for you. For a private cluster, see Private clusters.

Before you start

  • You’re an organization admin in KERNEL.
  • You can deploy pods and create service accounts in the cluster.
  • Your workload uses the TypeScript, Python, or Go SDK.

Find the cluster’s issuer

The issuer field is the URL to register, such as https://oidc.eks.us-east-1.amazonaws.com/id/EXAMPLED539D4633E53DE1B716D3041E. Each cluster has its own.

Configure KERNEL

1

Register the cluster as an issuer

In the dashboard, open Keys > Workload identity, click Connect workload, and select the Kubernetes tile.
  • Paste the issuer into Cluster issuer URL.
  • Check the box confirming the cluster’s discovery document and JWKS are reachable from the public internet.
  • Click Apply and continue.
Register one issuer per cluster.
2

Name the service account in a rule

Under Match conditions, enter the Namespace and the Kubernetes Service account your pods run as, such as ci and browser-runner. The rule accepts tokens whose subject is exactly system:serviceaccount:ci:browser-runner.Under Authorization, choose the Project, the Permissions, and the Token lifetime.
3

Pick a service account and enable

Choose or create a KERNEL service account, click Create rule, then turn on the issuer and the rule in the Test step. Copy the rule ID (wifr_...).

Configure your pod

Mount a projected service account token with the audience https://auth.onkernel.com, and point the SDK at it:
Don’t use the token Kubernetes mounts by default at /var/run/secrets/kubernetes.io/serviceaccount/token. Its audience is your cluster’s API server, so KERNEL refuses it. The projected volume above issues a separate token for KERNEL only.
Your code constructs the client with no arguments:

What the SDK does

The SDK reads the token file again for every exchange, so it picks up the token the kubelet rotates. It then exchanges the token at https://auth.onkernel.com/token. An empty or missing file is an error that names the path. To configure the file in code instead of KERNEL_IDENTITY_TOKEN_FILE:

What the token looks like

Three details to make note of:
  • The audience must be exactly one value. A token projected with more than one audience is refused.
  • A pod rereads the same token. The kubelet replaces a projected token only as it nears expiry, so between rotations every exchange presents the same one. A Kubernetes issuer allows that reuse by default.
  • Token lifetime is capped at one hour by default. KERNEL refuses a token whose lifetime, exp minus iat, is over the issuer’s maximum of 3,600 seconds. Keep expirationSeconds at 3600 or less, or raise Maximum token lifetime (hours) on the issuer.

Require single use

If every exchange fetches a new token, for example a job that runs kubectl create token each time, you can make the issuer single-use. On the Issuers tab, select Edit on the issuer and turn on Enforce single-use tokens (JTI replay protection). Don’t turn this on for pods that read a projected token file. The second exchange with the same file contents is refused.

Private clusters

KERNEL fetches signing keys only from public internet addresses. If your cluster’s discovery endpoint is private, upload its public keys instead:
  1. Export the keys:
  2. On the Issuers tab, click Register issuer.
  3. Enter the cluster’s issuer URL in Issuer URL (iss claim).
  4. Set JWKS source to Inline keys and paste the key set into Public keys.
  5. Turn off Enforce single-use tokens (JTI replay protection), because pods reread their token.
An issuer registered this way is a custom OIDC issuer. Its rules match on Subject pattern: enter system:serviceaccount:ci:browser-runner. Update the inline keys whenever the cluster rotates its signing keys. KERNEL can’t fetch new ones for you.

Next steps