Skip to main content

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​

Set a custom path template for a cluster using the SVIDIssuancePolicy managed configuration:

section: SVIDIssuancePolicy
schema: v1
spec:
  policy:
    pathTemplate: "/{{cluster.name}}/ns/{{kubernetes.pod.namespace}}/n/{{kubernetes.pod.name}}"

Apply it with spirlctl:

spirlctl config set cluster --id <cluster-id> svid-issuance-policy.yaml

Or with Terraform:

resource "spirl_cluster_config" "example" {
  cluster_id = spirl_cluster.my_cluster.id
  sections = {
    SVIDIssuancePolicy = <<-YAML
      section: SVIDIssuancePolicy
      schema: v1
      spec:
        policy:
          pathTemplate: "/{{cluster.name}}/ns/{{kubernetes.pod.namespace}}/n/{{kubernetes.pod.name}}"
    YAML
  }
}

The new path template replaces the default and is used to generate SPIFFE IDs for all workloads in the cluster.

When an SVIDIssuancePolicy is configured, the SPIFFE ID path template still falls back to the cluster version's default template if the policy doesn't set one. This makes it safe to write a policy that adjusts only TTLs without restating the path template.

To apply different path templates to specific workloads within the same cluster, use per-workload overrides.

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:

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.

Legacy configuration​

You can also set a custom path template using the spirlctl CLI when adding a cluster:

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

This method is supported, but when both methods are used, SVIDIssuancePolicy takes precedence.