SPIFFE ID templates

Defakto 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.

Available Template Variables

Attributes from both agent attestation and workload attestation are available in path templates. Each attestation method produces its own set of attributes — see the individual method pages for the attributes available:

• Agent Attestation Methods
• Workload Attestation Methods

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.