Skip to main content

X.509 SVID Customization

SPIRL allows customization of X.509 SVID fields on a per-cluster basis. Similar to cluster path templates, you can set an X.509 customization template that will be applied when an SVID is minted.

The customization template is a string that defines how certain fields of the X.509 certificate should be customized. Fields not specified in the template will receive their default values.

Template Format​

The template can customize Subject fields and Subject Alternative Names (SANs) of type DNS and IP. Here's an example that overrides the Common Name and Organization fields of the certificate Subject:

CN=CustomCN,O=BestCompany Inc.

You can customize any standard Subject field by referencing it directly in the template.

To customize DNS names and IP addresses in the SAN extension, use this notation:

SAN.DNS=dns1.example.com,SAN.DNS=dns2.example.com,SAN.IP=1.1.1.1

You can specify multiple DNS names or IP addresses - all instances will be included in the resulting SVID.

Special Characters​

The following characters must be escaped with a backslash when used in field values:

, ; # " + < > = \

Using Attributes​

You can use the same attributes in the customization template as those available for path templates. For more information, see the SPIFFE ID templates documentation.

Setting the Template​

For a New Cluster​

By default, clusters have an empty X.509 customization template. You can set a template when adding a cluster to the trust domain:

spirlctl cluster add production --trust-domain spirl.example.com \
    --platform k8s \
    --x509-customization-template "CN=CustomCN"

For an Existing Cluster​

To set or update the X.509 customization template for an existing cluster, use the change-x509-template subcommand:

spirlctl cluster config --trust-domain spirl.example.com \
    change-x509-template ClusterName "CN=CustomCN"

This creates a new cluster version with the specified customization template.

Removing the Template​

To remove the customization template from a cluster, set it to an empty string:

spirlctl cluster config --trust-domain spirl.example.com \
    change-x509-template ClusterName ""

Example with Attributes​

You can use attributes in the template similar to how they are used in path templates:

spirlctl cluster add production --trust-domain spirl.example.com \
    --platform k8s \
    --x509-customization-template "CN=pod-{{kubernetes.pod.name}}"

This example sets the Common Name to the pod name.