Kubernetes Service Account Identity

A workload running in the same Kubernetes cluster as MinIO AIStor can authenticate with the service account token Kubernetes already gives it. The pod needs no MinIO access key or secret key of its own.

AIStor grants that workload policies through the PolicyBinding custom resource, which names a service account and the policies it should receive.

How it works

  1. The pod presents its projected service account token to the AIStor Security Token Service, through either the AssumeRoleWithWebIdentity or the AssumeRoleWithClientGrants endpoint.

  2. AIStor recognizes a Kubernetes token by its subject, which Kubernetes sets to system:serviceaccount:NAMESPACE:NAME, and validates it using the configured token validation mode.

  3. AIStor reads the PolicyBinding resources in its own namespace and collects the policies from every binding whose spec.application names the calling namespace and service account.

  4. AIStor returns temporary credentials carrying those policies. A binding that names a policy the deployment does not have is ignored.

Token validation modes

Set the mode with MINIO_IDENTITY_KUBERNETES_TOKEN_VALIDATION.

Mode What AIStor does What it needs
oidc Verifies the token signature against the cluster’s OIDC discovery endpoint, caching the signing keys The cluster’s OIDC endpoint, on a signing key it has not seen
token_review Calls the Kubernetes TokenReview API for every request The Kubernetes API server, on every request
disabled Does not accept service account tokens at all Nothing

oidc is the default. It calls out to the cluster only when it meets a signing key it has not cached, where token_review places the Kubernetes API server in the path of every authentication.

AIStor also checks the token audience against MINIO_IDENTITY_KUBERNETES_TOKEN_AUDIENCE, which defaults to sts.min.io. Setting that variable to an empty string turns the audience check off.

This provider has no enable setting

AIStor turns Kubernetes service account identity on by itself when it detects that it is running inside a cluster and can reach both a token validator and the PolicyBinding API. There is no enable key to set.

To keep AIStor from accepting service account tokens, set MINIO_IDENTITY_KUBERNETES_TOKEN_VALIDATION to disabled.

Grant policies with a PolicyBinding

A PolicyBinding lives in the AIStor deployment’s namespace and names a service account elsewhere in the cluster:

apiVersion: sts.min.io/v1beta1
kind: PolicyBinding
metadata:
  name: analytics-reader
  namespace: aistor
spec:
  application:
    namespace: analytics
    serviceaccount: spark-driver
  policies:
    - readonly

This grants the spark-driver service account in the analytics namespace the readonly policy.

Create the bindings before the workload authenticates. A service account with no matching binding receives credentials with no policies, and can perform no operation.

Bindings are read at authentication time
AIStor lists the PolicyBinding resources in its namespace each time a service account exchanges its token for credentials, and does not cache the result. Individual S3 requests made with those credentials do not re-read the bindings. Keep the number of bindings in that namespace in proportion to your authentication rate.

Considerations

Only one Kubernetes configuration is supported per deployment.

AIStor reads bindings only from its own namespace, which it takes from the service account token mounted into its own pods. A PolicyBinding created in the workload’s namespace has no effect.

Policies still come from AIStor. A binding refers to policies by name, so create them with mc admin policy first.