Chapter 5. Coexistence of ambient and sidecar modes

Procedure

1. Update the existing Istio CR to set profile: ambient and to configure the trusted ztunnel namespace, as shown in the following example. Save the configuration to a file named istio_ambient.yaml.

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

   Important

   You must set spec.profile to ambient and set spec.values.pilot.trustedZtunnelNamespace to ztunnel. This is the namespace in which you install the ZTunnel resource.

2. Apply the updated Istio CR by running the following command:

   $ oc apply -f istio_ambient.yaml

3. Update the IstioCNI resource to enable the ambient profile, as shown in the following example. Save the configuration to a file named istiocni_ambient.yaml.

   apiVersion: sailoperator.io/v1
   kind: IstioCNI
   metadata:
     name: default
   spec:
     profile: ambient

4. Apply the updated IstioCNI resource by running the following command:

   $ oc apply -f istiocni_ambient.yaml

5. Confirm that the IstioCNI resource is ready by running the following command:

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

6. Create the ztunnel namespace by running the following command:

   $ oc create namespace ztunnel

7. Create a file named ztunnel.yaml that has the ZTunnel resource. For example:

   apiVersion: sailoperator.io/v1
   kind: ZTunnel
   metadata:
     name: default
   spec:
     namespace: ztunnel
     targetRef:
       kind: Istio
       name: default

   Note

   The spec.targetRef field associates the ZTunnel instance with an Istio control plane. When you set this field, the system automatically copies values relevant to ZTunnel, such as global, meshConfig, and revision, from the referenced Istio or IstioRevision resource. Values that you set in the ZTunnel spec.values field override inherited values.

8. Apply the ZTunnel CR by running the following command:

   $ oc apply -f ztunnel.yaml

9. Confirm that the ZTunnel resource is ready by running the following command:

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

10. Confirm that the Istio control plane is ready by running the following command:

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

11. Restart existing sidecar pods in each namespace that has sidecar workloads. Run the following command for each namespace:

    $ oc rollout restart deployment -n <sidecar_namespace>

    The restart re-injects the pods with ISTIO_META_ENABLE_HBONE set to true. Without this setting, the sidecar proxies cannot communicate with workloads in the ambient data plane. If you have a large number of sidecar pods, consider restarting them in small batches or one at a time to avoid disruption.

12. Create a namespace for your ambient workloads by running the following command:

    $ oc create namespace <ambient_namespace>

13. Label the namespace to enable ambient mode by running the following command:

    $ oc label namespace <ambient_namespace> istio.io/dataplane-mode=ambient

14. Deploy your application workloads to <ambient_namespace>.

    The mesh uses the ztunnel proxy to intercept traffic for pods in this namespace. You do not need to change your workload manifests.

Verification

1. Verify that your ambient workloads run without a sidecar proxy:

   $ oc get pods -n <ambient_namespace>

   Example output:

   NAME                        READY   STATUS    RESTARTS   AGE
   my-app-6d8f94b7c9-xk2pj    1/1     Running   0          45s

   Pods in an ambient namespace show 1/1 containers in the READY column. This output confirms that the mesh did not inject a sidecar proxy into the pod.

2. Verify that ztunnel registered your ambient workloads and configured HBONE. Run the following command:

   $ istioctl ztunnel-config workloads --namespace ztunnel --workload-namespace <ambient_namespace>

   The output lists the mesh workloads:

   NAMESPACE          POD NAME                                IP          NODE                  WAYPOINT PROTOCOL
   example            example-gateway-istio-59dd7c96db-q9k6v 10.244.1.11 ambient-worker        None     TCP
   example            example-app-cf74bb974-5sqkp            10.244.1.5  ambient-worker        None     HBONE

   Confirm that the PROTOCOL column displays HBONE for your new ambient pods. This protocol value indicates that ztunnel configured HBONE.