Skip to content
Tutorials Center
My learning

Topics

Lesson 7 of 36 ยท Service Mesh Concepts

Ambient Mode: ztunnel and Waypoints

Learn Istio ambient mode, the sidecar-less data plane: per-node ztunnel for L4 security, optional waypoint proxies for L7, HBONE tunnels and how to enroll.

Sidecars work, but they have costs: every pod carries a proxy, upgrades need pod restarts, and a pod's lifecycle becomes tied to its proxy's. Ambient mode is Istio's second data plane design. It removes the per-pod sidecar and splits the proxy's work into two layers, so you pay for L7 features only where you need them.

Ambient mode runs only on a real cluster. Commands are shown read-only, and the Python snippets are stand-ins for the decision logic, not the real implementation.

Two layers instead of one sidecar

ztunnel One per node, secure L4.
Waypoint Optional Envoy for L7 policy.
HBONE mTLS tunnel between them.

Pods are not restarted to join the mesh.

1 / 2

The two layers

ztunnel ("zero-trust tunnel") is a small, Rust-based node agent run as a DaemonSet. It handles everything at layer 4: mutual TLS, workload identity, simple authorization (by identity, port, namespace), and TCP telemetry. Enabling it means traffic is encrypted and identified without any proxy in the pod.

A waypoint proxy is an ordinary Envoy, deployed per namespace or per service account, that adds layer 7 features: HTTP routing, retries, fault injection, header-based authorization, richer metrics. Only the traffic that needs these features goes through it.

Between them, ztunnels speak HBONE (HTTP-Based Overlay Network Environment): an HTTP/2 CONNECT tunnel carrying mTLS, usually on port 15008. The Istio CNI node agent redirects pod traffic to the local ztunnel, which is why ambient installs add CNI and ztunnel components.

flowchart LR
    subgraph N1["Node 1"]
      A["pod: web"] --> Z1["ztunnel"]
    end
    subgraph N2["Node 2"]
      Z2["ztunnel"] --> B["pod: catalog"]
    end
    Z1 -- "HBONE (mTLS)" --> Z2
    Z1 -. "L7 needed" .-> W["waypoint (Envoy)"]
    W --> Z2

Without a waypoint the path is ztunnel to ztunnel; a waypoint is inserted only when L7 policy applies.

Enrolling workloads

Ambient is opt-in per namespace with a label, and no pod restart is required:

Terminal
istioctl install --set profile=ambient -y
kubectl label namespace shop istio.io/dataplane-mode=ambient

Pods in shop are now in the mesh: they get identity and mTLS. To add L7 features, create a waypoint and tell the namespace to use it:

Terminal
istioctl waypoint apply -n shop --enroll-namespace

A waypoint is a Kubernetes Gateway API Gateway with the class istio-waypoint. L7 resources such as HTTPRoute then attach to services in that namespace.

Sidecar versus ambient

Aspect Sidecar Ambient
Proxy location In every pod Node agent (L4) plus optional waypoint (L7)
Join the mesh Label, then restart pods Label only
Resource use Proxy memory/CPU per pod Shared per node, plus waypoints
L7 features Always available Only through a waypoint
Upgrades Restart workloads Roll the node agents
Maturity Longest history Newer, now generally available, with fewer legacy-feature gaps

You can run both in one mesh: some namespaces on sidecars, others in ambient. Choose per workload.

Modelling the choice

This stand-in decides which path a request takes in an ambient mesh and counts proxy hops. It models the idea only.

Python Stand-in: the ambient request path

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Python Stand-in: proxy count, sidecars versus ambient

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

The count is not the whole story: a waypoint proxy is bigger than one sidecar, and an overloaded waypoint affects many services, so you still size it deliberately.

Limits to remember

  • L7 features (header routing, fault injection) need a waypoint; without one, VirtualService-style rules for those do not apply to the traffic.
  • ztunnel authorization can only use L4 attributes: source identity, namespace, port. Method or path rules require a waypoint.
  • Check the Istio documentation for your version for the current list of unsupported features before migrating.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What does ztunnel provide?

    ztunnel is the node-level agent for secure overlay, handling L4 only.
  2. 2. When is a waypoint proxy needed?

    Waypoints are optional Envoy proxies added only where L7 policy applies.
  3. 3. How do you enroll a namespace in ambient mode?

    The ambient label requires no pod restarts.
  4. 4. What is HBONE?

    HBONE tunnels traffic with mutual TLS, typically on port 15008.

Summary

  • Ambient mode replaces per-pod sidecars with a node-level ztunnel (L4) and optional waypoints (L7).
  • Enrol with istio.io/dataplane-mode=ambient; no restart needed.
  • Traffic is tunneled between components with HBONE (mTLS over HTTP/2).
  • L7 policy needs a waypoint; L4 policy works without one.
  • Sidecar and ambient namespaces can coexist.

Next: Envoy and the xDS APIs