Red Hat Summit Red Hat SummitSupportConsoleDevelopersStart a trialContact

Chapter 4. Istio ambient mode

Istio ambient mode introduces an architecture for Red Hat OpenShift Service Mesh without sidecar injection. This mode is designed to simplify operations and reduce resource usage. Instead of injecting a sidecar proxy into each application pod, ambient mode uses a shared node-level proxy for Layer 4 (L4) functionality and an optional, dedicated proxy for Layer 7 (L7) features.

Important

Istio ambient mode is a Technology Preview feature only. Technology Preview features are not supported with Red Hat production service level agreements (SLAs) and might not be functionally complete. Red Hat does not recommend using them in production. These features provide early access to upcoming product features, enabling customers to test functionality and provide feedback during the development process.

For more information about the support scope of Red Hat Technology Preview features, see Technology Preview Features Support Scope.

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
      Copy to Clipboard Toggle word wrap

    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
      Copy to Clipboard Toggle word wrap

      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
      Copy to Clipboard Toggle word wrap

    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
      Copy to Clipboard Toggle word wrap

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

    1. Create the istio-cni namespace by running the following command: 

      $ oc create namespace istio-cni
      Copy to Clipboard Toggle word wrap

    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
      Copy to Clipboard Toggle word wrap

      Set the profile field to ambient.

    3. Apply the IstioCNI CR by running the following command: 

      $ oc apply -f istio-cni.yaml
      Copy to Clipboard Toggle word wrap

    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
      Copy to Clipboard Toggle word wrap

  3. Install the Ztunnel proxy:

    1. Create the ztunnel namespace for Ztunnel proxy by running the following command: 

      $ oc create namespace ztunnel
      Copy to Clipboard Toggle word wrap

      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
      Copy to Clipboard Toggle word wrap

    3. Apply the Ztunnel CR by running the following command: 

      $ oc apply -f ztunnel.yaml
      Copy to Clipboard Toggle word wrap

    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
      Copy to Clipboard Toggle word wrap

Next steps

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
    Copy to Clipboard Toggle word wrap

  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
    Copy to Clipboard Toggle word wrap

  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
    Copy to Clipboard Toggle word wrap

  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
      Copy to Clipboard Toggle word wrap

    2. Apply the YAML file to Istio control plane resource by running the following command: 

      $ oc apply -f istio-discovery-selectors.yaml
      Copy to Clipboard Toggle word wrap

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
    Copy to Clipboard Toggle word wrap

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

    $ oc label namespace bookinfo istio-discovery=enabled
    Copy to Clipboard Toggle word wrap

  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
    Copy to Clipboard Toggle word wrap

  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
    Copy to Clipboard Toggle word wrap

  5. Verify that the bookinfo pods are running by entering the following command: 

    $ oc -n bookinfo get pods
    Copy to Clipboard Toggle word wrap

    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
    Copy to Clipboard Toggle word wrap

  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>"
    Copy to Clipboard Toggle word wrap

  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
      Copy to Clipboard Toggle word wrap
    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
    Copy to Clipboard Toggle word wrap

    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
    Copy to Clipboard Toggle word wrap

Back to top
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

© 2025 Red Hat