Kubernetes Service Account Token

The Kubernetes Service Account Token method authenticates agents running in a Kubernetes cluster by verifying the agent's service account token. The agent sends its token to the Trust Domain Server; the server verifies it against the cluster's OIDC issuer.

This is the simplest agent attestation method for Kubernetes-hosted agents.

Attributes available for SVID issuance

The following attributes are collected for workloads running in Kubernetes-based platforms (e.g. k8s) and can be used in path templates, JWT custom claims, and X.509 Subject customization. Some attributes are restricted to specific surfaces — see the Notes column.

Kubernetes Attribute	Path Template Variable	Notes
Pod Image Count	kubernetes.pod.image_count	Number of containers in the pod. E.g. `1`
Pod Init Image Count	kubernetes.pod.init_image_count	Number of init containers in the pod. E.g. `0`
Pod Name	kubernetes.pod.name
Namespace	kubernetes.pod.namespace
Pod UID	kubernetes.pod.uid
Pod Node Name	kubernetes.pod.node.name
Pod Owner	kubernetes.pod.owner	Owner of the pod, formatted as `Type:Name`. E.g. `ReplicaSet:my-replicaset-5cfd45f6c9`. See note below.
Pod Owner UID	kubernetes.pod.owner_uid	UID of the pod's owner. E.g. `316ea285-b878-4d20-a9fe-2e1c79b0f083`. See note below.
Service Account	kubernetes.pod.service_account
Pod Container Image Name	kubernetes.pod.container.<container_name>.image.name	One entry per container in the pod. Not available in path templates.
Pod Container Image ID	kubernetes.pod.container.<container_name>.image.id	One entry per container in the pod. Not available in path templates.
Pod Init Container Image Name	kubernetes.pod.init_container.<container_name>.image.name	One entry per init container in the pod. Not available in path templates.
Pod Init Container Image ID	kubernetes.pod.init_container.<container_name>.image.id	One entry per init container in the pod. Not available in path templates.
Pod Label	kubernetes.pod.label[<label_key>]	One entry per label on the pod
Pod Annotation	kubernetes.pod.annotation[<annotation_key>]	One entry per allowlisted annotation on the pod
Container Name	kubernetes.container.name	Disabled by default. See below.
Container Image Name	kubernetes.container.image.name	Disabled by default. See below.
Container Image ID	kubernetes.container.image.id	Disabled by default. See below.

Pod owner attributes

kubernetes.pod.owner and kubernetes.pod.owner_uid are derived from the pod's OwnerReferences. If there are multiple entries, the last owner in OwnerReferences is used.

Label and annotation keys with special characters

Pod label and pod annotation keys containing forward slashes (/) or dashes (-) require Trust Domain Server version 0.28.0 or newer. On earlier versions, configuration using these keys will fail synchronization, and the server will remain on its previous configuration.

Annotation allowlist

Pod annotations are emitted only for keys matching an allowlisted prefix. Configure prefixes via kubernetes.includeAnnotationPrefixes in the WorkloadAttestation managed configuration section. For example, to expose the annotation example.com/my-annotation:

section: WorkloadAttestation
schema: v1
spec:
  kubernetes:
    includeAnnotationPrefixes:
      - "example.com/"

Enabling container attributes

Container attributes must be enabled by setting includeContainerAttributes: true in the relevant platform block (e.g. k8s, istio) of the spirl-system Helm values.

Workload container vs. pod container attributes

The kubernetes.container.* attributes describe the container running the attested workload. To access attributes of other containers in the same pod, use the kubernetes.pod.container.<container_name>.* attributes instead.

How to Deploy

Step 1 — Update cluster configuration

Create an AgentAttestation policy for the cluster, specifying the OIDC issuer URL for the Kubernetes cluster where agents will run. The issuer URL must be reachable from the Trust Domain Server.

section: AgentAttestation
schema: v1
spec:
  policies:
    - name: k8s_policy
      requiredAttestors:
        - type: k8s_token
          config:
            issuerURL: https://oidc.eks.us-east-1.amazonaws.com/id/ABCDEF123456

Apply it:

spirlctl config set cluster --id <cluster-id> attestation-policy.yaml

Configuration Reference

Field	Required	Description
`issuerURL`	Yes	OIDC issuer URL for the Kubernetes cluster. The Trust Domain Server fetches signing keys from this endpoint.

Step 2 — Configure the Agent

No additional agent configuration is needed. When k8s_token is listed as an attestation method, the agent automatically requests a service account token from Kubernetes and sends it to the server at login.

In Helm values:

agent:
  auth:
    clusterId: c-xxxxxx
    attestors:
      - type: k8s_token

Security Considerations

The OIDC issuer endpoint must be accessible from the Trust Domain Server's network. Ensure any firewall or network policy allows outbound HTTPS from the Trust Domain Server to the issuer URL.
Service account tokens expire. Kubernetes automatically rotates them; agents re-authenticate as needed.
Service account tokens alone do not constrain which node or namespace an agent runs in. For finer-grained control — for example, limiting agents to a specific namespace or service account — add a second attestation method (such as aws_iid) that enforces additional constraints.

Troubleshooting

failed to fetch signing key — The Trust Domain Server cannot reach the OIDC issuer URL. Verify network connectivity from the server to the configured issuerURL.

JWT verification failed — The token the agent presented was not verifiable. Check the error detail: common causes are an expired token, a mismatched issuer URL, or a token issued by a different cluster than the one configured.

Attributes available for SVID issuance​

How to Deploy​

Step 1 — Update cluster configuration​

Configuration Reference​

Step 2 — Configure the Agent​

Security Considerations​

Troubleshooting​