OpenShift Service Mesh (Ambient Mode)¶

Red Hat OpenShift Service Mesh Documentation

Out of POC baseline

Service Mesh is not part of the default POC checklist. Install it only if mesh (mTLS, traffic splitting) is explicitly in scope for this engagement.

OpenShift Service Mesh 3.x provides Istio ambient mode — a sidecar-less architecture that uses node-level Layer 4 (L4) proxies (ZTunnel) and optional Layer 7 (L7) waypoint proxies. This reduces resource overhead and operational complexity compared to traditional sidecar injection.

Prerequisites¶

OpenShift Container Platform
Cluster administrator privileges
OVN-Kubernetes CNI configured for local gateway mode (see below)

Install istioctl¶

Use the Red Hat istioctl that matches your installed OpenShift Service Mesh version — not the upstream binary from istio.io.

In the web console, open the ? menu → Command Line Tools
Download istioctl, extract it, and place it on your PATH:

tar -xzf istioctl-linux-amd64.tar.gz
sudo mv istioctl /usr/local/bin/
istioctl version --remote=false

Verify:

istioctl version

Configure OVN-Kubernetes for Local Gateway Mode¶

Ambient mode requires OVN-Kubernetes to use local gateway mode. This must be done before installing the mesh.

Edit the Cluster Network Operator configuration:

oc edit network.operator.openshift.io cluster

Set routingViaHost to true in the gatewayConfig:

spec:
  defaultNetwork:
    ovnKubernetesConfig:
      gatewayConfig:
        routingViaHost: true

Warning

Changing the gateway mode will cause a rolling restart of the OVN-Kubernetes pods across all nodes. Plan for a brief disruption window.

Wait for the network operator to reconcile:
```
oc get co network -w
```
Wait for AVAILABLE=True and PROGRESSING=False.

Install the Operator via WebUI¶

Go to Ecosystem -> Software Catalog -> filter for "OpenShift Service Mesh" -> click the "Red Hat OpenShift Service Mesh" tile (version 3.x)
Click Install
Select the stable channel
Leave all other defaults and click Install
Wait for the Operator to install

Install the Operator via YAML¶

apiVersion: operators.coreos.com/v1alpha1
kind: Subscription
metadata:
  name: servicemeshoperator3
  namespace: openshift-operators
spec:
  channel: stable
  installPlanApproval: Automatic
  name: servicemeshoperator3
  source: redhat-operators
  sourceNamespace: openshift-marketplace

oc apply -f servicemesh-operator.yaml

Wait for the operator:

oc get csv -n openshift-operators | grep servicemesh

The PHASE should show Succeeded.

Deploy Istio Ambient Mode¶

Install the Istio Control Plane¶

Create the namespace:
```
oc create namespace istio-system
```

Create the Istio resource:

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

oc apply -f istio.yaml

Wait for the control plane to be ready:

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

Install the Istio CNI¶

Create the namespace:
```
oc create namespace istio-cni
```

Create the IstioCNI resource:

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

oc apply -f istio-cni.yaml

Wait for the CNI pods to be ready:

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

Install the ZTunnel Proxy¶

Create the namespace:
```
oc create namespace ztunnel
```

Note

The namespace name must match the trustedZtunnelNamespace value in the Istio resource.

Create the ZTunnel resource:

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

oc apply -f ztunnel.yaml

Wait for the ZTunnel pods to be ready:

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

Verify¶

oc get istio
oc get istiocni
oc get ztunnel
oc get pods -n istio-system
oc get pods -n istio-cni
oc get pods -n ztunnel

All resources should show Ready and all pods should be Running.

Enroll a Namespace in the Mesh¶

To add a namespace to the ambient mesh, label it:

oc label namespace <class 'jinja2.utils.Namespace'> istio.io/dataplane-mode=ambient

All pods in that namespace will automatically have their traffic routed through the ZTunnel proxy with mTLS — no sidecar injection needed.

Add a Waypoint Proxy (Optional L7 Features)¶

If you need Layer 7 features (HTTP routing, retries, traffic splitting) for a specific service account or namespace:

istioctl waypoint apply -n <class 'jinja2.utils.Namespace'>

Or create it declaratively:

apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: waypoint
  namespace: <class 'jinja2.utils.Namespace'>
  labels:
    istio.io/waypoint-for: service
spec:
  gatewayClassName: istio-waypoint
  listeners:
    - name: mesh
      port: 15008
      protocol: HBONE

oc apply -f waypoint.yaml