Documentation/security/network/encryption-ztunnel.rst
.. only:: not (epub or latex or html)
WARNING: You are looking at unreleased Cilium documentation.
Please use the official rendered version released here:
https://docs.cilium.io
.. _encryption_ztunnel:
Ztunnel Transparent Encryption (Beta)
.. include:: ../../beta.rst
This guide explains how to configure Cilium to use ztunnel for transparent encryption and mutual TLS (mTLS) authentication between Cilium-managed endpoints. ztunnel is a purpose-built per-node proxy that provides transparent Layer 4 mTLS encryption and authentication for pod-to-pod communication.
When ztunnel is enabled in Cilium, the agent running on each cluster node establishes a control plane connection with the local ztunnel proxy. Cilium enrolls pods into the mesh on a per-namespace basis, allowing fine-grained control over which workloads participate in mTLS encryption. Enrolled pods have their traffic transparently redirected to the ztunnel proxy using iptables rules configured in their network namespace, where the traffic is encrypted and authenticated using mutual TLS before being sent to the destination.
Cilium's ztunnel integration requires a set of private keys and accompanying to certificates be present via Kubernetes secrets. This follows the same pattern as IPsec key injections.
These keys can be generated with the following bash script prior to deploying Cilium.
.. literalinclude:: ../../../examples/kubernetes-ztunnel/generate-secrets.sh :language: bash
The 'bootstrap' keys are used to secure the connection between ztunnel and Cilium's xDS and certificate server implementation.
The 'ca' keys are used as the root certificate for creating in-memory and ephemeral client certificates on ztunnel's request.
Before you install Cilium with ztunnel enabled, ensure that:
.. tabs::
.. group-tab:: Cilium CLI
If you are deploying Cilium with the Cilium CLI, pass the following
options:
.. parsed-literal::
cilium install |CHART_VERSION| \\
--set encryption.enabled=true \\
--set encryption.type=ztunnel
.. group-tab:: Helm
If you are deploying Cilium with Helm by following
:ref:`k8s_install_helm`, pass the following options:
.. parsed-literal::
helm install cilium |CHART_RELEASE| \\
--namespace kube-system \\
--set encryption.enabled=true \\
--set encryption.type=ztunnel
After enabling ztunnel in Cilium, you need to explicitly enroll namespaces to enable mTLS encryption for their workloads. This is done by applying a label to the namespace:
.. code-block:: shell-session
kubectl label namespace <namespace-name> io.cilium/mtls-enabled=true
To verify that a namespace is enrolled:
.. code-block:: shell-session
kubectl get namespace <namespace-name> --show-labels
When a namespace is enrolled:
To disenroll a namespace:
.. code-block:: shell-session
kubectl label namespace <namespace-name> io.cilium/mtls-enabled-
This will:
#. Disenroll all pods in the namespace from ztunnel #. Remove the iptables rules from each pod's network namespace #. Notify ztunnel to stop processing traffic for those workloads
#. Check that ztunnel has been enabled:
.. code-block:: shell-session
kubectl -n kube-system describe cm cilium-config | grep enable-ztunnel -A2
You should see output indicating that ztunnel encryption is enabled.
#. Check which namespaces are enrolled:
.. code-block:: shell-session
kubectl get namespaces -l io.cilium/mtls-enabled=true
This shows all namespaces labeled for ztunnel enrollment.
To verify that these namespaces are actually enrolled in the StateDB table:
.. code-block:: shell-session
kubectl exec -n kube-system ds/cilium -- cilium-dbg statedb dump | jq '.["mtls-enrolled-namespaces"]'
The results of this query should show which namespaces have been successfully processed by the enrollment reconciler.
#. Run a bash shell in one of the Cilium pods hosting a mtls-enrolled pod with
kubectl -n kube-system exec -ti pod/<cillium-pod-hosting-mtls-pod> -- bash
and execute the following commands:
Install tcpdump
.. code-block:: shell-session
$ apt-get update
$ apt-get -y install tcpdump
Check that traffic is encrypted. In the example below, this can be verified
by the fact that packets will have a destination port of 15008 (HBONE).
In the example below, eth0 is the interface used for pod-to-pod
communication. Replace this interface with e.g. cilium_vxlan if
tunneling is enabled.
.. code-block:: shell-session
tcpdump -i eth0 port 15008
tcpdump: verbose output suppressed, use -v or -vv for full protocol decode
listening on eth0, link-type EN10MB (Ethernet), snapshot length 262144 bytes
13:00:06.982499 IP 10.244.1.95.15008 > 10.244.2.3.33446: ...
13:00:06.982536 IP 10.244.2.3.33446 > 10.244.1.95.15008: ...
13:00:06.982675 IP 10.244.2.3.33446 > 10.244.1.95.15008: ...
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.
The ztunnel integration currently only supports enrollment via namespace labels. Pod-level enrollment is not supported.
Only TCP traffic is currently supported for mTLS encryption. UDP and other protocols are not redirected to ztunnel.
The integration requires iptables support in the kernel and cannot be used with environments that do not support iptables (such as some minimal container runtimes).
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).
Cluster Mesh is not currently supported when ztunnel is enabled. Attempting to enable both will result in a validation error.
Pods without a network namespace path (such as host-networked pods) cannot be enrolled in ztunnel and will be skipped during enrollment.