Kubernetes workload authentication

A pod running in your Kubernetes cluster can fetch a vault secret at run time by presenting its own Kubernetes ServiceAccount token — the same token every pod already has mounted — rather than a static, hard-coded credential. Qorionix verifies that token directly against your cluster's own API, the same way any other Kubernetes-aware system would.

Registering a cluster from the console

An administrator registers a cluster once, from the Kubernetes clusters panel on Privileged → Clusters & agents. Before you start, store the ServiceAccount token your cluster's TokenReview call will authenticate with as an ordinary api_token vault credential — the form below picks it from the vault rather than accepting it pasted in a second time, so it gets the same access control and rotation history as any other secret.

1. 1

   Open the Kubernetes clusters panel and choose Register cluster

   On Privileged → Clusters & agents, the Kubernetes clusters panel lists every cluster already registered and has the Register cluster button.

2. 2

   Enter the Cluster ID, API server URL and CA bundle

   Cluster ID is the name a pod's own request will use to say which cluster it is calling from. The API server URL is your cluster's own Kubernetes API endpoint (for example https://10.0.4.1:6443). The CA bundle (PEM) is the certificate that signs that endpoint's TLS certificate, so Qorionix can trust the connection it opens back to your cluster to call TokenReview.

3. 3

   Set Expected audience, if your projected tokens use a custom one

   Leave this empty to accept a projected ServiceAccount token's default audience. Set it only if your pods request token projection with a custom audience.

4. 4

   Pick the Reviewer ServiceAccount token from the vault

   This is the vault credential you stored beforehand: a ServiceAccount token your cluster trusts to call its own TokenReview API on the cluster's behalf. Qorionix reads it through the vault at call time; it is never stored a second time outside it.

5. 5

   Register, then list or revoke as needed

   A registered cluster appears in the same panel with its cluster ID, API server URL and expected audience. Revoking it immediately stops every pod in that cluster from fetching a workload token.

All of this is admin-scoped and requires the pam:k8s_clusters write permission, whether you use the console screen or call the API underneath it directly.

The API behind the screen

The console panel calls these routes directly — useful if you are scripting cluster registration into a deployment pipeline rather than clicking through the form each time:

POST /api/v1/organizations/{orgID}/pam/k8s-clusters
{
  "cluster_id": "prod-eu",
  "api_server_url": "https://<your-cluster-api>",
  "ca_bundle_pem": "-----BEGIN CERTIFICATE-----...",
  "expected_audience": "https://<your-cluster-api>",
  "reviewer_token_credential_id": "<a vault credential id>",
  "description": "Production EU cluster"
}

GET    /api/v1/organizations/{orgID}/pam/k8s-clusters
DELETE /api/v1/organizations/{orgID}/pam/k8s-clusters/{clusterRowID}

Enrol the namespace and service account as an application identity

Registering a cluster only lets Qorionix verify a token against it. A pod's namespace/serviceaccount identity still has to be enrolled as an authorised caller the same way any application identity is (see the application-identity fetch surface used by Storing cloud credentials and related articles): enrol the string k8s:<namespace>/<serviceaccount> as an os_user_path auth method on the Application object the pod authenticates as, alongside its allowed safes and account patterns. This is the real remaining manual step — there is no console screen for it yet, and a registered cluster with no application identity enrolled against it will still refuse every fetch a pod attempts.

How a pod fetches a secret

1. The pod reads its own mounted ServiceAccount token and posts it to POST /api/v1/pam/k8sauth/token. This endpoint is deliberately outside your organisation's normal authenticated API — a pod has no Qorionix session, so its authentication is the token itself, verified live against your cluster's TokenReview API. Which organisation it belongs to is resolved from the cluster registration, never trusted from the request.
2. Qorionix authorises the resulting namespace/serviceaccount identity against the enrolled application identity, and — on success — mints a short-lived, narrowly scoped token capped under a 15-minute ceiling.
3. The pod calls the existing workload secret-fetch endpoint with that token, exactly as any other application identity would (Authorization: Workload <token>), and receives the credential's secret, governed by the same policy checks every workload fetch already goes through.

What to do next

1. Create a dedicated, minimally-privileged ServiceAccount in your cluster for the TokenReview call, store its token in the vault, and register the cluster against it from Privileged → Clusters & agents.
2. Enrol each pod identity that needs a secret as its own application identity, scoped to only the safe and account it actually needs — this step still has to be done by hand.
3. Revoke a cluster registration from the same panel the moment you decommission or rekey the cluster's reviewer ServiceAccount.