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
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.
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 audiencehttps://auth.onkernel.com, and point the SDK at it:
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 athttps://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
- 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,
expminusiat, is over the issuer’s maximum of 3,600 seconds. KeepexpirationSecondsat3600or 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 runskubectl 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:-
Export the keys:
- On the Issuers tab, click Register issuer.
- Enter the cluster’s issuer URL in Issuer URL (iss claim).
- Set JWKS source to Inline keys and paste the key set into Public keys.
- Turn off Enforce single-use tokens (JTI replay protection), because pods reread their token.
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
- Reference: Kubernetes match fields
- Troubleshooting: what a refused exchange means
- Move a workload from an API key