Skip to main content

X.509-SVID Customization

Defakto allows customization of X.509-SVID fields on a per-cluster basis, including TTL, certificate Subject, and Subject Alternative Names (SANs).

X.509-SVID TTL and Subject​

Set a custom X.509-SVID TTL and certificate Subject using the SVIDIssuancePolicy managed configuration:

section: SVIDIssuancePolicy
schema: v1
spec:
  policy:
    pathTemplate: "/{{cluster.name}}/ns/{{kubernetes.pod.namespace}}/sa/{{kubernetes.pod.service_account}}"
    x509:
      ttl: "24h"
      subject: "O=Acme Corp,OU=Engineering"

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}}/sa/{{kubernetes.pod.service_account}}"
          x509:
            ttl: "24h"
            subject: "O=Acme Corp,OU=Engineering"
    YAML
  }
}
FieldTypeNotes
x509.ttldurationX.509-SVID TTL (1h–168h). Defaults to the per-deployment value when not set.
x509.subjectstringRFC 4514 distinguished name. Becomes the certificate Subject.

When an SVIDIssuancePolicy sets these fields, they are authoritative — the per-deployment CLI defaults are no longer consulted as fallbacks. Hardcoded safety defaults still apply when both the policy and the customer's configuration leave a field unset (for example, a 24h fallback for TTL).

To apply different X.509 settings to specific workloads within the same cluster, use per-workload overrides.

X.509 Customization Templates​

info

SVIDIssuancePolicy does not currently express SAN entries (SAN.DNS, SAN.IP). To set those, use the legacy configuration method. When policy.x509.subject is set, it takes precedence over any subject defined in the X509CustomizationTemplate. SAN.DNS and SAN.IP entries from the customization template still apply on top.

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.

Example with Attributes​

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

CN=pod-{{kubernetes.pod.name}}

This example sets the Common Name to the pod name.

Legacy configuration​

Setting the Template for a New Cluster​

You can also control the customization template using the spirlctl CLI. When both are configured, SVIDIssuancePolicy takes precedence.

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"

Setting the Template 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 ""