Default SPIFFE ID templates

SPIRL generates SPIFFE IDs for new SPIFFE Verifiable Identity Documents (SVIDs) in a platform-dependent way. For example, the default path template for Kubernetes is:

/{{cluster.name}}/ns/{{kubernetes.pod.namespace}}/sa/{{kubernetes.pod.service_account}}

Assuming a trust domain of spirl.example.com, a cluster name of edge-global, a namespace of prod and a service account named nginx, this expands to the following SPIFFE ID:

spiffe://spirl.example.com/edge-global/ns/prod/sa/nginx

By default, the following path templates are used, depending on the platform:

# Default Kubernetes path template
/{{cluster.name}}/ns/{{kubernetes.pod.namespace}}/sa/{{kubernetes.pod.service_account}}

# Default Istio path template
/ns/{{kubernetes.pod.namespace}}/sa/{{kubernetes.pod.service_account}}

# Default Linux path template
/{{node_group.name}}/{{linux.user.name}}

# Default developer identity path template
/users/{{email.domain}}/{{email.username}}

Customizing the path template for a new cluster

The default path templates are based on SPIFFE best practices. However, these path templates can be customized for each cluster. It is safest to do so when adding the cluster to the trust domain:

spirlctl cluster add production --trust-domain spirl.example.com \
   --platform k8s \
   --path-template /{{cluster.name}}/ns/{{kubernetes.pod.namespace}}/n/{{kubernetes.pod.name}}

Passing in a new path template replaces the default, and the new path template will be used to generate SPIFFE IDs.

Kubernetes attributes

The following attributes are available to use in path templates, JWT custom claims, and X.509 Subject customization for workloads running in Kubernetes-based platforms (e.g. k8s).

Kubernetes Attribute	Path Template Variable	Notes
Container Name	kubernetes.container.name
Container Image ID	kubernetes.container.image.id
Container Image Name	kubernetes.container.image.name
Pod Annotation	kubernetes.pod.annotation.[annotation_key]	Supported as of spirl-server v0.28.0, but see note below. See Kubernetes documentation for allowed characters.
Pod Label	kubernetes.pod.label.[label_key]	Supported as of spirl-server v0.28.0, but see note below. See Kubernetes documentation for allowed characters.
Pod Name	kubernetes.pod.name
Namespace	kubernetes.pod.namespace
Pod Node Name	kubernetes.pod.node.name
Pod UID	kubernetes.pod.uid
Service Account	kubernetes.pod.service_account

Annotation and label attributes

Using pod annotations or pod label attributes with forward slashes '/' or dashes '-' is only supported on SPIRL Servers with a version of 0.28.0 or newer. Using this syntax on previous versions will result in the configuration synchronization failing and the servers remaining on their previous configuration.

Annotation prefixes must be explicitly allowlisted using k8s.includeAnnotations in order to use them in path templates and other fields requiring attestation. For example, to use the annotation example.com/my-annotation, the agent configuration would contain the following:

k8s:
 includeAnnotations:
  - "example.com/"

To use Linux attributes in path templates, see how to install the SPIRL Agent on Debian or Ubuntu.

Realm Template Variable

When a cluster is registered within a realm, the {{spirl.realm}} template variable is automatically prepended to the SPIFFE ID path when the default path templates are used. For example the default path template for kubernetes becomes:

/{{spirl.realm}}/{{cluster.name}}/ns/{{kubernetes.pod.namespace}}/sa/{{kubernetes.pod.service_account}}

When a custom path template is assigned to the cluster, the {{spirl.realm}} template variable must be added to the custom path template. Such as:

/{{spirl.realm}}/{{cluster.name}}/{{kubernetes.pod.name}}

This variable is only available for clusters assigned to a realm.

See the Realm Operations guide for more information on realm management.