Cilium points SPIRE mutual authentication users to ztunnel before a likely v1.21 removal
Cilium committers deprecated SPIRE-based Mutual Authentication as of v1.20 and will most likely remove it in v1.21, per the project's deprecation issue. Anyone who adopted it has to plan a move to ztunnel, the feature that replaces it.
The Engineer · Build desk
Mutual Auth adopters: deprecated in v1.20, likely removed in v1.21. Cluster Mesh: must be disabled to enable ztunnel. New ztunnel installs: no encryption until a namespace is labeled. Enrolled namespaces: calls to non-enrolled ones break. L4 policies: fail except on port 15008.
- Who has to decide decision Mutual Auth adopters Deprecated as of Cilium v1.20; committers will remove it in a later version, most likely v1.21, claim 2
- What it limits constraint Cluster Mesh clusters Cluster Mesh must be disabled before enabling ztunnel; enabling both throws a validation error, claim 10
- What it limits constraint New ztunnel installs Nothing is encrypted until namespaces are opted in with the label io.cilium/mtls-enabled=true, claim 11
- Who's exposed exposure Enrolled namespaces A call from enrolled payments to non-enrolled orders breaks; it does not silently degrade to unencrypted, claim 14
- What it limits constraint Cilium L4 network policies Won't work, as traffic is encrypted before it leaves the pod, except those targeting HBONE port 15008, claim 15
| Who | How | Kind | Claim |
|---|---|---|---|
| Mutual Auth adopters | Deprecated as of Cilium v1.20; committers will remove it in a later version, most likely v1.21 | decision | 2 |
| Cluster Mesh clusters | Cluster Mesh must be disabled before enabling ztunnel; enabling both throws a validation error | constraint | 10 |
| New ztunnel installs | Nothing is encrypted until namespaces are opted in with the label io.cilium/mtls-enabled=true | constraint | 11 |
| Enrolled namespaces | A call from enrolled payments to non-enrolled orders breaks; it does not silently degrade to unencrypted | exposure | 14 |
| Cilium L4 network policies | Won't work, as traffic is encrypted before it leaves the pod, except those targeting HBONE port 15008 | constraint | 15 |
What happened
- The agent-side removal PR for the old Mutual Authentication feature is already merged.
- The replacement, ztunnel Transparent Encryption, is under active development and does not need a SPIRE server.
- After ztunnel is installed, nothing is encrypted until a namespace is labeled io.cilium/mtls-enabled=true.
- Cilium's docs support traffic only when both the source and destination endpoints are enrolled in ztunnel.
Why it matters
- Who has to decide decision Enrollment order becomes a dependency question. The write-up says an enrolled payments namespace calling a not-yet-enrolled orders namespace fails outright instead of falling back to plaintext, so callers have to be mapped first.
- What it limits constraint Clusters running Cluster Mesh cannot adopt ztunnel until they disable it. The docs say the two are incompatible, and enabling both throws a validation error.
- Who's exposed exposure Enrolling a namespace can change which network policies take effect. The docs say L4 policies stop working except those targeting the ztunnel HBONE port, 15008, because traffic is encrypted before it leaves the pod.
- What it costs cost The destination is also Beta. ztunnel is under active development, but it carries the same maturity label as the feature it replaces.
A Cilium committer opened the deprecation issue, and the dev.to write-up quotes it: "Given the lack of progress on Mutual Auth, and the presence and at least equal stability of the new feature, as of Cilium v1.20, Cilium committers are marking the Mutual Auth feature as deprecated, and will remove the feature in a later version, most likely v1.21." [2] Removal would likely come one minor release after deprecation. [16]
What adopters are leaving shipped in 2023 as a Beta. It needs a SPIRE server deployed alongside Cilium, switched on with `authentication.mutual.spire.enabled=true`. [3]
The destination works differently. Cilium's docs describe ztunnel as "a purpose-built per-node proxy that provides transparent Layer 4 mTLS encryption and authentication for pod-to-pod communication." [6] Identity comes from two key pairs you generate yourself with the OpenSSL script in the docs. The bootstrap pair secures the connection between ztunnel and Cilium's certificate server. The CA pair is the root for the ephemeral, in-memory client certificates ztunnel issues on request. [8] Four files go into one secret, `cilium-ztunnel-secrets`, in `kube-system`. [7] The install then turns it on: `cilium install 1.20.2 --set encryption.enabled=true --set encryption.type=ztunnel`. [9]
Once a namespace is labeled, ztunnel enrolls every existing pod in it, except the ztunnel pods, and installs iptables rules in each pod's network namespace to redirect traffic to the local ztunnel proxy. Pods created later are enrolled automatically. Removing the label disenrolls them: `kubectl label namespace <namespace-name> io.cilium/mtls-enabled-`. [12]
We think the slow part of this migration is mapping the cross-namespace callers in the cluster, not generating the keys.
The write-up breaks off mid-sentence in its network-policy section, and it does not describe an automated conversion from existing Mutual Authentication settings. Teams on the old feature should read the Cilium ztunnel docs and the deprecation issue directly before scheduling the work.
What to watch
- Whether the v1.21 release notes confirm removal of Mutual Authentication, or push it to a later version as the deprecation issue allows.
- Whether ztunnel leaves Beta and gains Cluster Mesh support, since the current incompatibility blocks those clusters from migrating.
- Whether Cilium's docs add a step-by-step path from existing Mutual Authentication settings to ztunnel.
Clarity's read
What the record supports and how the coverage leans. The claims behind it follow.
Reality
- Evidence62
- Adoption
- Not scored
- Hype gap+8
- Incentives
- Not scored
- Confidence58
Claim ledger
Ranked by verification strength, evidence, and original report placement.
- [1]
Cilium's older SPIRE-based Mutual Authentication feature is officially deprecated, with removal targeted for v1.21.
- [2]
Per the deprecation issue opened by a Cilium committer: "Given the lack of progress on Mutual Auth, and the presence and at least equal stability of the new feature, as of Cilium v1.20, Cilium committers are marking the Mutual Auth feature as deprecated, and will remove the feature in a later version, most likely v1.21."
- [3]
Cilium shipped the SPIRE-based Mutual Authentication feature in 2023 as a Beta; it requires a SPIRE server deployed alongside Cilium, enabled with authentication.mutual.spire.enabled=true, to issue and verify identity certificates.
- [4]
The replacement, ztunnel Transparent Encryption, is actively developed and does not require running a SPIRE server.
- [5]
ztunnel Transparent Encryption is also a Beta feature.
- [6]
Cilium's ztunnel documentation describes ztunnel as "a purpose-built per-node proxy that provides transparent Layer 4 mTLS encryption and authentication for pod-to-pod communication."
- [7]
The docs' script creates a Kubernetes secret named cilium-ztunnel-secrets in kube-system from four files: bootstrap-private.key, bootstrap-root.crt, ca-private.key and ca-root.crt.
- [8]
The bootstrap key pair secures the connection between ztunnel and Cilium's certificate server; the CA key pair is the root for the ephemeral, in-memory client certificates ztunnel issues on request.
- [9]
ztunnel is enabled at install time with: cilium install 1.20.2 --set encryption.enabled=true --set encryption.type=ztunnel.
- [10]
Cluster Mesh must be disabled before enabling ztunnel; the docs say ztunnel "is currently not compatible with Cluster Mesh," and enabling both together throws a validation error.
- [11]
Once ztunnel is running, nothing is encrypted until namespaces are opted in with the label io.cilium/mtls-enabled=true.
- [12]
Labeling a namespace enrolls every existing pod in it (ztunnel pods excepted), installs iptables rules in each pod's network namespace to redirect traffic to the local ztunnel proxy, and enrolls every future pod automatically; removing the label (io.cilium/mtls-enabled-) disenrolls.
- [13]
The docs state: "Traffic between workloads is only supported when both the source and destination endpoints are enrolled in ztunnel. Communication between an enrolled workload and a non-enrolled workload is not supported."
- [14]
If payments is enrolled but orders is not, a call from payments to orders breaks; it does not silently degrade to unencrypted. The author advises mapping service-to-service dependencies before labeling the first namespace.
- [15]
The docs state: "ztunnel interferes with Cilium network policy as traffic is encrypted before it leaves the pod, meaning L4 policies won't work except for directly targeting the ztunnel HBONE port (15008)."
- [16]
Deprecation (v1.20) and likely removal (v1.21) are one minor release apart.
- [17]
The agent-side removal PR for Mutual Authentication is already merged.
Get this ledger inside ChatGPT. Ask about any of our stories and the answer brings its figure, each claim’s verdict and the sources. Free, no account.
Sources
1 independent publisher whose own reporting we read for this story.
- dev.toCilium mTLS ztunnel: Sidecar-Free Encryption Explained
1 article · October 15, 2026
Topics and entities
Follow any of these and your For You feed starts watching them — no settings page required.
Topics
- Mutual TLSFollow
- Software deprecationsFollow
- Kubernetes NetworkingFollow