Ztunnel¶

ztunnel is Istio ambient mesh’s node-local L4 proxy. Big Bang deploys it as a DaemonSet in istio-system; a ready pod is therefore needed on each eligible Linux node that hosts ambient-enrolled workloads. For ambient architecture, workload enrollment, traffic policy, and operational procedures, use the Istio ambient documentation.

Big Bang integration¶

This package is a thin wrapper around the upstream ztunnel chart for Istio 1.31.1. It selects the Iron Bank ztunnel image and enables the upstream ztunnel NetworkPolicy. The full upstream configuration surface is available through the upstream passthrough key; see the upstream values for its supported options.

The umbrella chart owns ztunnel enablement, source selection, release ordering, and values-secret precedence. It creates the ztunnel release when ambient mode is effective: either istio.ambient.enabled: true or ztunnel.enabled: true. Ambient mode also causes the umbrella to enable Istio CNI and Gateway API. The ztunnel release waits for Istiod and Istio CNI, plus enabled policy-package dependencies. Configure these relationships in the umbrella chart rather than in this package chart.

Configuration¶

Set Big Bang’s package enablement at the umbrella level, then place upstream chart settings under values.upstream:

ztunnel:
  enabled: true
  values:
    upstream:
      # Upstream ztunnel chart settings
      logLevel: info

Alternatively, enable ambient mode with istio.ambient.enabled: true; the umbrella enables ztunnel and supplies its ambient defaults. Avoid treating an explicit ztunnel enablement as an isolated workload: it activates the umbrella ambient-mode behavior.

Networking, health, and metrics¶

Big Bang enables the upstream ztunnel NetworkPolicy by default. The rendered policy selects app: ztunnel, permits ingress for readiness (15021), metrics (15020), admin (15000), HBONE (15008), interception endpoints, and DNS capture, and allows all egress. Review any additional cluster NetworkPolicies and CNI restrictions against the rendered policy before tightening network access.

The upstream DaemonSet labels its ztunnel container istio-proxy, exposes 15020 as ztunnel-stats, and adds the Prometheus scrape annotations for that port. In Big Bang monitoring deployments, discovery is supplied by the existing Istio Envoy PodMonitor (monitoring-monitoring-istio-envoy), rather than by a ztunnel-specific monitor. Confirm that selector and the rendered ztunnel pod labels when changing monitoring configuration. The readiness probe uses /healthz/ready on port 15021.

Operations and security¶

Ztunnel is a privileged node-level component. Its upstream DaemonSet requires network and namespace capabilities plus host integration to perform ambient traffic interception. Validate node coverage, readiness, CNI compatibility, and ambient traffic in a disposable environment after changing its configuration or the related Istio packages. Package helm lint chart checks the wrapper only; it does not verify ambient traffic or node coverage.

For package development, the repository test values enable ztunnel, Istio CNI, and Gateway API together. Cross-repository ambient changes need matching Istiod, Istio CNI, Gateway API, and umbrella validation.