Ztunnel📜

Overview📜

Ztunnel (zero-trust tunnel) is a purpose-built component for Istio’s ambient mesh mode. It provides a lightweight, shared proxy that handles Layer 4 (L4) traffic between workloads, enabling mutual TLS (mTLS) encryption and zero-trust security without requiring sidecar proxies.

Ztunnel runs as a DaemonSet on each node and transparently intercepts and encrypts traffic between pods, providing secure communication at the network layer. This approach offers a simpler deployment model compared to sidecar-based service mesh architectures.

flowchart LR
  subgraph Node1["Node 1"]
    Z1[Ztunnel]
    P1[Pod A]
    P2[Pod B]
    P1 --> Z1
    P2 --> Z1
  end

  subgraph Node2["Node 2"]
    Z2[Ztunnel]
    P3[Pod C]
    P4[Pod D]
    P3 --> Z2
    P4 --> Z2
  end

  Z1 <-->|"mTLS<br/>Encrypted"| Z2

Big Bang Touchpoints📜

Licensing📜

Ztunnel is part of the Istio project and is open source, licensed under the Apache License 2.0.

Installation📜

Ztunnel is deployed to the istio-system namespace. It can be enabled explicitly or is automatically enabled when istio.ambient.enabled: true is set in Big Bang values:

# Explicit enable
ztunnel:
  enabled: true

# Or via ambient mode (auto-enables ztunnel)
istio:
  ambient:
    enabled: true

Storage📜

Ztunnel does not require any persistent storage. It operates as an in-memory L4 proxy.

UI📜

Ztunnel does not have a dedicated UI. Observability is provided through:

Kiali: Visualize mesh traffic and ztunnel connectivity
Grafana: View ztunnel metrics via Prometheus
Kubectl: Inspect ztunnel pods and logs

Logging📜

Ztunnel logs are captured by the cluster’s logging collector (Alloy or Fluentbit) and shipped to your configured logging backend (Loki or Elasticsearch).

Monitoring📜

Ztunnel exposes metrics on port 15020 at both /metrics and /stats/prometheus endpoints. When using Big Bang’s monitoring stack, ztunnel metrics are automatically scraped by the existing istio-envoy PodMonitor because:

Ztunnel’s container is named istio-proxy
Ztunnel includes the required Prometheus annotations (prometheus.io/scrape: "true")

No additional configuration is required for metrics collection.

Key metrics exposed include:

Metric	Description
`istio_build`	Build info (component, version)
`istio_tcp_connections_opened_total`	TCP connections opened with source/destination labels
`istio_tcp_connections_closed_total`	TCP connections closed
`istio_tcp_received_bytes_total`	Bytes received per connection
`istio_tcp_sent_bytes_total`	Bytes sent per connection
`istio_xds_message_total`	XDS control plane messages

Metrics include rich labels for traffic analysis: source/destination workload, namespace, service, app, version, and connection_security_policy (showing mutual_tls when mTLS is active).

Health Checks📜

Standard Kubernetes readiness and liveness probes are configured for ztunnel pods.

High Availability📜

Ztunnel runs as a DaemonSet, ensuring one instance per node. This architecture provides inherent high availability as traffic can be routed through any available ztunnel instance.

Dependent Packages📜

Ztunnel requires the following packages:

istiod: The Istio control plane that configures ztunnel
istio-cni: Required for traffic interception in ambient mode

Optional but recommended:

Gateway API: Provides the CRDs for configuring traffic routing in ambient mode
Kiali: Visualization and management of the ambient mesh
Monitoring: Metrics collection and dashboards

Configuration📜

Values can be passed through to the ztunnel chart:

ztunnel:
  enabled: true
  values:
    # Upstream chart values go here
    upstream:
      env:
        COLOR: red

Ambient Mode📜

To enable full Istio ambient mode with ztunnel, configure Big Bang with:

istio:
  ambient:
    enabled: true

This will automatically enable and configure istio-cni, Gateway API, and ztunnel with the appropriate settings.