Red Hat Summit Red Hat SummitSupportConsoleDevelopersStart a trialContact

Chapter 4. Istio ambient mode

Istio ambient mode provides a sidecar-less architecture for Red Hat OpenShift Service Mesh that reduces operational complexity and resource overhead by using node-level Layer 4 (L4) proxies and optional Layer 7 proxies.

4.1. About Istio ambient mode
Copy link

To understand the Istio ambient mode architecture, see the following definitions:

ZTunnel proxy
A per-node proxy that manages secure, transparent Transmission Control Protocol (TCP) connections for all workloads on the node. It operates at Layer 4 (L4), offloading mutual Transport Layer Security (mTLS) and L4 policy enforcement from application pods.
Waypoint proxy
An optional proxy that runs per service account or namespace to provide advanced Layer 7 (L7) features such as traffic management, policy enforcement, and observability. You can apply L7 features selectively to avoid the overhead of sidecars for every service.
Istio CNI plugin
Redirects traffic to the Ztunnel proxy on each node, enabling transparent interception without requiring modifications to application pods.

Istio ambient mode offers the following benefits:

  • Simplified operations that remove the need to manage sidecar injection, reducing the complexity of mesh adoption and operations.
  • Reduced resource consumption with a per-node Ztunnel proxy that provides L4 service mesh features and an optional 
    waypoint
    proxy that reduces resource overhead per pod.

  • Incremental adoption that enables workloads to join the mesh with the L4 features like mutual Transport Layer Security (mTLS) and basic policies with optional 

    waypoint
    proxies added later to use L7 service mesh features, such as HTTP(L7) traffic management.

    Note

    The L7 features require deploying 

    waypoint
    proxies, which introduces minimal additional overhead for the selected services.

  • Enhanced security that provides a secure, zero-trust network foundation with mTLS by default for all meshed workloads.
Note

Ambient mode is a newer architecture and may involve different operational considerations than traditional sidecar models.

While well-defined discovery selectors allow a service mesh deployed in ambient mode alongside a mesh in sidecar mode, this scenario has not been thoroughly validated. To avoid potential conflicts, install Istio ambient mode only on clusters that do not have an existing Red Hat OpenShift Service Mesh installation. Ambient mode remains a Technology Preview feature.

Important

Istio ambient mode is not compatible with clusters that use Red Hat OpenShift Service Mesh 2.6 or earlier. You must not install or use them together.

4.1.1. Installing Istio ambient mode
Copy link

You can install Istio ambient mode on OpenShift Container Platform 4.19 or later and Red Hat OpenShift Service Mesh 3.1.0 or later with the required Gateway API custom resource definitions (CRDs).

Prerequisites

  • You have deployed a cluster on OpenShift Container Platform 4.19 or later.
  • You have installed the OpenShift Service Mesh Operator 3.1.0 or later in the OpenShift Container Platform cluster.
  • You are logged in to the OpenShift Container Platform cluster either through the web console as a user with the 
    cluster-admin
    role, or with the 
    oc login
    command, depending on the installation method.
  • You have configured the OVN-Kubernetes Container Network Interface (CNI) to use local gateway mode by setting the 
    routingViaHost
    field as 
    true
    in the 
    gatewayConfig
    specification for the Cluster Network Operator. For more information, see "Configuring gateway mode".

Procedure

  1. Install the Istio control plane:

    1. Create the 

      istio-system
      namespace by running the following command: 

      $ oc create namespace istio-system

    2. Create an 

      Istio
      resource named 
      istio.yaml
      similar to the following example:

      Example configuration

      apiVersion: sailoperator.io/v1
kind: Istio
metadata:
  name: default
spec:
  namespace: istio-system
  profile: ambient
  values:
    pilot:
      trustedZtunnelNamespace: ztunnel

      Important

      You must set the 

      profile
      field to 
      ambient
      , and configure the 
      .spec.values.pilot.trustedZtunnelNamespace
      value to match the namespace where the 
      ZTunnel
      resource will be installed.

    3. Apply the 

      Istio
      custom resource (CR) by running the following command: 

      $ oc apply -f istio.yaml

    4. Wait for the Istio control plane to contain the 

      Ready
      status condition by running the following command: 

      $ oc wait --for=condition=Ready istios/default --timeout=3m

  2. Install the Istio Container Network Interface (CNI):

    1. Create the 

      istio-cni
      namespace by running the following command: 

      $ oc create namespace istio-cni

    2. Create the 

      IstioCNI
      resource named 
      istio-cni.yaml
      similar to the following example:

      Example configuration

      apiVersion: sailoperator.io/v1
kind: IstioCNI
metadata:
  name: default
spec:
  namespace: istio-cni
  profile: ambient

      Set the 

      profile
      field to 
      ambient
      .

    3. Apply the 

      IstioCNI
      CR by running the following command: 

      $ oc apply -f istio-cni.yaml

    4. Wait for the 

      IstioCNI
      pods to contain the 
      Ready
      status condition by running the following command: 

      $ oc wait --for=condition=Ready istios/default --timeout=3m

  3. Install the Ztunnel proxy:

    1. Create the 

      ztunnel
      namespace for Ztunnel proxy by running the following command: 

      $ oc create namespace ztunnel

      The namespace name for 

      ztunnel
      project must match the 
      trustedZtunnelNamespace
      parameter in Istio configuration.

    2. Create the 

      Ztunnel
      resource named 
      ztunnel.yaml
      similar to the following example:

      Example configuration

      apiVersion: sailoperator.io/v1alpha1
kind: ZTunnel
metadata:
  name: default
spec:
  namespace: ztunnel
  profile: ambient

    3. Apply the 

      Ztunnel
      CR by running the following command: 

      $ oc apply -f ztunnel.yaml

    4. Wait for the 

      Ztunnel
      pods to contain the 
      Ready
      status condition by running the following command: 

      $ oc wait --for=condition=Ready ztunnel/default --timeout=3m

Istio ambient mode includes workloads when the control plane discovers each workload and the appropriate label enables traffic redirection through the Ztunnel proxy. By default, the control plane discovers workloads in all namespaces across the cluster. As a result, each proxy receives configuration for every namespace, including workloads that are not enrolled in the mesh. In shared or multi-tenant clusters, limiting mesh participation to specific namespaces helps reduce configuration overhead and supports multiple service meshes within the same cluster.

For more information on discovery selectors, see "Scoping the Service Mesh with discovery selectors".

To limit the scope of the OpenShift Service Mesh in Istio ambient mode, you can configure 

discoverySelectors
parameter in the 
meshConfig
section of the 
Istio
resource. The configuration controls which namespaces the control plane discovers based on label selectors.

Prerequisites

  • You have deployed a cluster on OpenShift Container Platform 4.19 or later.
  • You have created an 
    Istio
    control plane resource.
  • You have created an 
    IstioCNI
    resource.
  • You have created a 
    Ztunnel
    resource.

Procedure

  1. Add a label to the namespace containing the 

    Istio
    control plane resource, for example, the 
    istio-system
    namespace, by running the following command: 

    $ oc label namespace istio-system istio-discovery=enabled

  2. Add a label to the namespace containing the 

    IstioCNI
    resource, for example, the 
    istio-cni
    namespace, by running the following command: 

    $ oc label namespace istio-cni istio-discovery=enabled

  3. Add a label to the namespace containing the 

    Ztunnel
    resource, for example, the 
    ztunnel
    namespace, by running the following command: 

    $ oc label namespace ztunnel istio-discovery=enabled

  4. Modify the 

    Istio
    control plane resource to include a 
    discoverySelectors
    section with the same label:

    1. Create a YAML file with the name 

      istio-discovery-selectors.yaml
      similar to the following example:

      Example configuration

      apiVersion: sailoperator.io/v1
kind: Istio
metadata:
  name: default
spec:
  namespace: istio-system
  values:
    pilot:
      trustedZtunnelNamespace: ztunnel
    profile: ambient
    meshConfig:
      discoverySelectors:
      - matchLabels:
          istio-discovery: enabled

    2. Apply the YAML file to 

      Istio
      control plane resource by running the following command: 

      $ oc apply -f istio-discovery-selectors.yaml

You can deploy the 

bookinfo
sample application in Istio ambient mode without sidecar injection by using the 
ZTunnel
proxy. For more information on 
bookinfo
application, see "About the Bookinfo application".

Prerequisites

  • You have deployed a cluster on OpenShift Container Platform 4.15 or later, which includes the supported Kubernetes Gateway API custom resource definitions (CRDs) required for Istio ambient mode.
  • You are logged in to the OpenShift Container Platform cluster either through the web console as a user with the 
    cluster-admin
    role, or with the 
    oc login
    command, depending on the installation method.
  • You have installed the Red Hat OpenShift Service Mesh Operator, created the Istio resource, and the Operator has deployed Istio.
  • You have created an 
    IstioCNI
    resource, and the Operator has deployed the necessary 
    IstioCNI
    pods.
  • You have created a 
    Ztunnel
    resource, and the Operator has deployed the necessary 
    Ztunnel
    pods.

Procedure

  1. Create the 

    bookinfo
    namespace by running the following command: 

    $ oc create namespace bookinfo

  2. Add the 

    istio-discovery=enabled
    label to the 
    bookinfo
    namespace by running the following command: 

    $ oc label namespace bookinfo istio-discovery=enabled

  3. Apply the 

    bookinfo
    YAML file to deploy the 
    bookinfo
    application by running the following command: 

    $ oc apply -n bookinfo -f https://raw.githubusercontent.com/openshift-service-mesh/istio/release-1.26/samples/bookinfo/platform/kube/bookinfo.yaml

  4. Apply the 

    bookinfo-versions
    YAML file to deploy the 
    bookinfo
    application by running the following command: 

    $ oc apply -n bookinfo -f https://raw.githubusercontent.com/openshift-service-mesh/istio/release-1.26/samples/bookinfo/platform/kube/bookinfo-versions.yaml

  5. Verify that the 

    bookinfo
    pods are running by entering the following command: 

    $ oc -n bookinfo get pods

    Example output

    NAME                             READY   STATUS    RESTARTS   AGE
details-v1-54ffdd5947-8gk5h      1/1     Running   0          5m9s
productpage-v1-d49bb79b4-cb9sl   1/1     Running   0          5m3s
ratings-v1-856f65bcff-h6kkf      1/1     Running   0          5m7s
reviews-v1-848b8749df-wl5br      1/1     Running   0          5m6s
reviews-v2-5fdf9886c7-8xprg      1/1     Running   0          5m5s
reviews-v3-bb6b8ddc7-bvcm5       1/1     Running   0          5m5s

  6. Verify that the 

    bookinfo
    application is running by entering the following command: 

    $ oc exec "$(oc get pod -l app=ratings -n bookinfo \
  -o jsonpath='{.items[0].metadata.name}')" \
  -c ratings -n bookinfo \
  -- curl -sS productpage:9080/productpage | grep -o "<title>.*</title>"

  7. Add the bookinfo application to the Istio ambient mesh by labeling either the entire namespace or the individual pods:

    1. To include all workloads in the bookinfo namespace, apply the 

      istio.io/dataplane-mode=ambient
      label to the 
      bookinfo
      namespace, by running the following command: 

      $ oc label namespace bookinfo istio.io/dataplane-mode=ambient
    2. To include only specific workloads, apply the 
      istio.io/dataplane-mode=ambient
      label directly to individual pods. See the "Additional resources" section for more details on the labels used to add or exclude workloads in a mesh.
    Note

    Adding workloads to the ambient mesh does not require restarting or redeploying application pods. Unlike sidecar mode, the number of containers in each pod remains unchanged.

  8. Confirm that Ztunnel proxy has successfully opened listening sockets in the pod network namespace by running the following command: 

    $ istioctl ztunnel-config workloads --namespace ztunnel

    Example output

    NAMESPACE    POD NAME                       ADDRESS      NODE                        WAYPOINT PROTOCOL
bookinfo     details-v1-54ffdd5947-cflng    10.131.0.69  ip-10-0-47-239.ec2.internal None     HBONE
bookinfo     productpage-v1-d49bb79b4-8sgwx 10.128.2.80  ip-10-0-24-198.ec2.internal None     HBONE
bookinfo     ratings-v1-856f65bcff-c6ldn    10.131.0.70  ip-10-0-47-239.ec2.internal None     HBONE
bookinfo     reviews-v1-848b8749df-45hfd    10.131.0.72  ip-10-0-47-239.ec2.internal None     HBONE
bookinfo     reviews-v2-5fdf9886c7-mvwft    10.128.2.78  ip-10-0-24-198.ec2.internal None     HBONE
bookinfo     reviews-v3-bb6b8ddc7-fl8q2     10.128.2.79  ip-10-0-24-198.ec2.internal None     HBONE
istio-cni    istio-cni-node-7hwd2           10.0.61.108  ip-10-0-61-108.ec2.internal None     TCP
istio-cni    istio-cni-node-bfqmb           10.0.30.129  ip-10-0-30-129.ec2.internal None     TCP
istio-cni    istio-cni-node-cv8cw           10.0.75.71   ip-10-0-75-71.ec2.internal  None     TCP
istio-cni    istio-cni-node-hj9cz           10.0.47.239  ip-10-0-47-239.ec2.internal None     TCP
istio-cni    istio-cni-node-p8wrg           10.0.24.198  ip-10-0-24-198.ec2.internal None     TCP
istio-system istiod-6bd6b8664b-r74js        10.131.0.80  ip-10-0-47-239.ec2.internal None     TCP
ztunnel      ztunnel-2w5mj                  10.128.2.61  ip-10-0-24-198.ec2.internal None     TCP
ztunnel      ztunnel-6njq8                  10.129.0.131 ip-10-0-75-71.ec2.internal  None     TCP
ztunnel      ztunnel-96j7k                  10.130.0.146 ip-10-0-61-108.ec2.internal None     TCP
ztunnel      ztunnel-98mrk                  10.131.0.50  ip-10-0-47-239.ec2.internal None     TCP
ztunnel      ztunnel-jqcxn                  10.128.0.98  ip-10-0-30-129.ec2.internal None     TCP

Red Hat logoGithubredditYoutubeTwitter

Learn

Try, buy, & sell

Communities

About Red Hat Documentation

We help Red Hat users innovate and achieve their goals with our products and services with content they can trust. Explore our recent updates.

Making open source more inclusive

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. For more details, see the Red Hat Blog.

About Red Hat

We deliver hardened solutions that make it easier for enterprises to work across platforms and environments, from the core datacenter to the network edge.

Theme

© 2026 Red HatBack to top