For the complete documentation index, see llms.txt. Markdown versions of all docs pages are available by appending .md to any docs URL.

Revoke workload certificates in the ambient mesh using a Certificate Revocation List (CRL).

Use Certificate Revocation Lists (CRL) to revoke workload certificates in the ambient mesh. When enabled, ztunnel checks the CRL on every new inbound and outbound connection, rejects connections from peers with revoked certificates, and immediately terminates existing connections that use a revoked certificate.

Before you begin

Configure a plugged-in CA for istiod by using the credentials in the cacerts secret in the istio-system namespace. For example, you can use OpenSSL, Vault, AWS Private CA, or other tools to provide the CA certificate and key. CRL enforcement requires the CA to be plugged in through istiod’s cacerts secret. The default Istio self-signed CA does not support CRL distribution.

Enable CRL enforcement

1. Generate a CRL from your CA in PEM format. The steps to generate a CRL depend on your CA implementation.

2. Add the CRL to your existing cacerts secret in the istio-system namespace as a ca-crl.pem entry.

   kubectl patch secret cacerts -n istio-system \
     --type merge \
     -p "{\"data\":{\"ca-crl.pem\":\"$(cat ca-crl.pem | base64 | tr -d '\n')\"}}"

3. Enable CRL propagation in istiod. Istiod reads the ca-crl.pem entry from the cacerts secret and propagates it as a ConfigMap to every namespace in the mesh.

   helm upgrade istiod oci://us-docker.pkg.dev/soloio-img/istio-helm/istiod \
     --version 1.31.0-solo \
     --namespace istio-system \
     --reuse-values \
     --set pilot.env.PILOT_ENABLE_CA_CRL=true

4. Enable CRL enforcement in the ztunnel. Ztunnel mounts the ConfigMap that istiod created as a volume and loads the CRL. New inbound and outbound connections to peers with revoked certificates are rejected. When the CRL is reloaded, ztunnel also immediately terminates any existing connections that use a revoked certificate.

   helm upgrade ztunnel oci://us-docker.pkg.dev/soloio-img/istio-helm/ztunnel \
     --version 1.31.0-solo \
     --namespace istio-system \
     --reuse-values \
     --set peerCaCrl.enabled=true

5. Multicluster only: If your mesh includes an east-west gateway, enable CRL enforcement on the peering chart as well. Without this, connections that traverse the east-west gateway do not enforce the CRL.

   helm upgrade peering-eastwest oci://us-docker.pkg.dev/soloio-img/istio-helm/peering \
     --version 1.31.0-solo \
     --namespace istio-eastwest \
     --reuse-values \
     --set eastwest.peerCaCrl.enabled=true

Update the CRL

To update the CRL, patch the cacerts secret with the new PEM file. No ztunnel restart is required.

kubectl patch secret cacerts -n istio-system \
  --type merge \
  -p "{\"data\":{\"ca-crl.pem\":\"$(cat ca-crl-updated.pem | base64 | tr -d '\n')\"}}"

Istiod detects the change and updates the ConfigMap in each namespace. Ztunnel reloads the updated CRL automatically within the kubelet’s volume sync interval, typically 60–90 seconds.

Clear the CRL

To remove all revocations, patch the cacerts secret with an empty string for ca-crl.pem.

kubectl patch secret cacerts -n istio-system \
  --type merge \
  -p '{"data":{"ca-crl.pem":""}}'

Istiod detects the change and clears the istio-ca-crl ConfigMap in each namespace, and ztunnel stops enforcing revocations within the kubelet’s volume sync interval, typically 60–90 seconds.

Considerations

• Connection termination: When the CRL is loaded or updated, ztunnel immediately terminates any existing connections whose certificates appear on the revocation list. This termination is abrupt by design, because a revoked certificate is treated as a security event, not a normal close condition.
• CRL update propagation delay: CRL updates propagate to ztunnel within the kubelet’s volume sync interval, typically 60–90 seconds. During this window, ztunnel continues to enforce the previous CRL.
• Plugged-in CA required: CRL enforcement requires a custom intermediate CA configured via the cacerts secret. The default Istio self-signed CA does not generate or distribute CRLs.
• CRL required for each CA in the chain: The ca-crl.pem file must include a CRL signed by each CA in the certificate chain. If any issuer’s CRL is missing, istiod rejects the entire update and leaves the previously propagated CRL unchanged. This validation exists because Envoy sidecars enforce CRL coverage strictly: if a CRL exists for some issuers but not all, Envoy performs fail-closed behavior and rejects all connections for the affected workloads.
• Ztunnel fail-open behavior: Ztunnel CRL enforcement is fail-open. If no CRL exists for an issuer in a presented certificate chain, and no existing CRL revokes any other issuer or leaf certificate in the chain, ztunnel allows the connection. This behavior is the opposite of Envoy sidecar fail-closed behavior.
• Chain depth revocation: Ztunnel evaluates CRLs at each level of the certificate chain. Both leaf certificates and intermediate CA certificates can be revoked.
• Solo distribution of Istio: CRL enforcement via the peerCaCrl Helm value is available in the Solo distribution of Istio. The underlying ztunnel CRL enforcement code was contributed upstream to the Istio open source project.