OSSM-9322 Istio ambient mode getting started docs

_topic_maps/_topic_map.yml

@@ -72,6 +72,8 @@ Topics:
   File: ossm-installing-openshift-service-mesh
 - Name: Sidecar injection
   File: ossm-sidecar-injection
+- Name: Istio ambient mode
+  File: ossm-istio-ambient-mode
 - Name: Red Hat OpenShift Service Mesh and cert-manager
   File: ossm-cert-manager
 - Name: Multi-Cluster topologies

install/ossm-istio-ambient-mode.adoc

@@ -0,0 +1,37 @@
+:_mod-docs-content-type: ASSEMBLY
+[id="ossm-istio-ambient-mode"]
+= Istio ambient mode
+include::_attributes/common-attributes.adoc[]
+:context: ossm-istio-ambient-mode
+
+toc::[]
+
+{istio} ambient mode introduces an architecture for {SMProductName} 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.
+
+include::snippets/technology-preview-istio-ambient-mode.adoc[]
+
+include::modules/ossm-about-istio-ambient-mode.adoc[leveloffset=+1]
+include::modules/ossm-installing-istio-ambient-mode.adoc[leveloffset=+2]
+
+.Next steps
+* xref:../install/ossm-istio-ambient-mode.adoc#ossm-scoping-sm-discovery-selectors-istio-ambient-mode_ossm-istio-ambient-mode[Scoping Service Mesh with discovery selectors in Istio ambient mode]
+* xref:../install/ossm-istio-ambient-mode.adoc#ossm-deploying-bookinfo-application-istio-ambient-mode_ossm-istio-ambient-mode[Deploying the Bookinfo application in Istio ambient mode]
+
+include::modules/ossm-about-discovery-selectors-istio-ambient-mode.adoc[leveloffset=+1]
+
+[role="_additional-resources"]
+.Additional resources
+* xref:../install/ossm-installing-openshift-service-mesh.adoc#ossm-scoping-service-mesh-with-discoveryselectors_ossm-creating-istiocni-resource[Scoping the Service Mesh with discovery selectors]
+
+include::modules/ossm-scoping-sm-discovery-selectors-istio-ambient-mode.adoc[leveloffset=+2]
+include::modules/ossm-deploying-bookinfo-application-istio-ambient-mode.adoc[leveloffset=+1]
+
+[role="_additional-resources"]
+.Additional resources
+* xref:../install/ossm-installing-openshift-service-mesh.adoc#ossm-about-bookinfo-application_ossm-discoveryselectors-scope-service-mesh[About the Bookinfo application]
+
+[role="_additional-resources"]
+[id="additional-resources_{context}"]
+== Additional resources
+* link:https://istio.io/latest/docs/ambient/architecture/[Ambient mode architecture (Istio documentation)]
+* link:https://istio.io/latest/docs/ambient/usage/add-workloads/[Adding workloads to a mesh in ambient mode (Istio documentation)]

modules/ossm-about-discovery-selectors-istio-ambient-mode.adoc

@@ -0,0 +1,11 @@
+// Module included in the following assemblies:
+
+// * service-mesh-docs-main/install/ossm-istio-ambient-mode.adoc
+
+:_mod-docs-content-type: CONCEPT
+[id="ossm-about-discovery-selectors-istio-ambient-mode_{context}"]
+= About discovery selectors and Istio ambient mode
+
+{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".

modules/ossm-about-istio-ambient-mode.adoc

@@ -0,0 +1,42 @@
+// Module included in the following assemblies:
+
+// * service-mesh-docs-main/install/ossm-istio-ambient-mode.adoc
+
+:_mod-docs-content-type: CONCEPT
+[id="ossm-about-istio-ambient-mode_{context}"]
+= About Istio ambient mode
+
+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 {SMProductName} installation. Ambient mode remains a Technology Preview feature.
+
+[IMPORTANT]
+====
+{istio} ambient mode is not compatible with clusters that use {SMProductName} 2.6 or earlier. You must not install or use them together.
+====

modules/ossm-deploying-bookinfo-application-istio-ambient-mode.adoc

@@ -0,0 +1,123 @@
+// Module included in the following assemblies:
+
+// * service-mesh-docs-main/install/ossm-istio-ambient-mode.adoc
+
+:_mod-docs-content-type: PROCEDURE
+[id="ossm-deploying-bookinfo-application-istio-ambient-mode_{context}"]
+= Deploying the Bookinfo application in Istio ambient mode
+
+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 {ocp-product-title} 4.15 or later, which includes the supported {k8s} Gateway API custom resource definitions (CRDs) required for {istio} ambient mode.
+* You are logged in to the {ocp-product-title} 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 {SMProductName} 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
+
+. Create the `bookinfo` namespace by running the following command:
++
+[source,terminal]
+----
+$ oc create namespace bookinfo
+----
+
+. Add the `istio-discovery=enabled` label to the `bookinfo` namespace by running the following command:
++
+[source,terminal]
+----
+$ oc label namespace bookinfo istio-discovery=enabled
+----
+
+. Apply the `bookinfo` YAML file to deploy the `bookinfo` application by running the following command:
++
+[source,terminal]
+----
+$ oc apply -n bookinfo -f https://raw.githubusercontent.com/openshift-service-mesh/istio/release-1.26/samples/bookinfo/platform/kube/bookinfo.yaml
+----
+
+. Apply the `bookinfo-versions` YAML file to deploy the `bookinfo` application by running the following command:
++
+[source,terminal]
+----
+$ oc apply -n bookinfo -f https://raw.githubusercontent.com/openshift-service-mesh/istio/release-1.26/samples/bookinfo/platform/kube/bookinfo-versions.yaml
+----
+
+. Verify that the `bookinfo` pods are running by entering the following command:
++
+[source,terminal]
+----
+$ oc -n bookinfo get pods
+----
++
+.Example output
+[source,terminal]
+----
+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
+----
+
+. Verify that the `bookinfo` application is running by entering the following command:
++
+[source,terminal]
+----
+$ 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>"
+----
+
+. Add the bookinfo application to the {istio} ambient mesh by labeling either the entire namespace or the individual pods:
+
+.. 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:
++
+[source,terminal]
+----
+$ oc label namespace bookinfo istio.io/dataplane-mode=ambient
+----
+
+.. 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.
+====
+
+. Confirm that Ztunnel proxy has successfully opened listening sockets in the pod network namespace by running the following command:
++
+[source,terminal]
+----
+$ istioctl ztunnel-config workloads --namespace ztunnel
+----
++
+.Example output
+[source,terminal]
+----
+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
+----

modules/ossm-installing-istio-ambient-mode.adoc

@@ -0,0 +1,140 @@
+// Module included in the following assemblies:
+
+// * service-mesh-docs-main/install/ossm-istio-ambient-mode.adoc
+
+:_mod-docs-content-type: PROCEDURE
+[id="ossm-installing-istio-ambient-mode_{context}"]
+= Installing Istio ambient mode
+
+You can install {istio} ambient mode on {ocp-product-title} 4.19 or later and {SMProductName} 3.1.0 or later with the required Gateway API custom resource definitions (CRDs).
+
+.Prerequisites
+
+* You have deployed a cluster on {ocp-product-title} 4.19 or later.
+* You have installed the {SMProduct} Operator 3.1.0 or later in the {ocp-product-title} cluster.
+* You are logged in to the {ocp-product-title} 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.
+
+.Procedure
+
+. Install the {istio} control plane:
+
+.. Create the `istio-system` namespace by running the following command:
++
+[source,terminal]
+----
+$ oc create namespace istio-system
+----
+
+.. Create an `{istio}` resource named `istio.yaml` similar to the following example:
++
+.Example configuration
+[source,yaml]
+----
+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.
+====
+
+.. Apply the `{istio}` custom resource (CR) by running the following command:
++
+[source,terminal]
+----
+$ oc apply -f istio.yaml
+----
+
+.. Wait for the {istio} control plane to contain the `Ready` status condition by running the following command:
++
+[source,terminal]
+----
+$ oc wait --for=condition=Ready istios/default --timeout=3m
+----
+
+. Install the {istio} Container Network Interface (CNI):
+
+.. Create the `istio-cni` namespace by running the following command:
++
+[source,terminal]
+----
+$ oc create namespace istio-cni
+----
+
+.. Create the `IstioCNI` resource named `istio-cni.yaml` similar to the following example:
++
+.Example configuration
+[source,yaml]
+----
+apiVersion: sailoperator.io/v1
+kind: IstioCNI
+metadata:
+  name: default
+spec:
+  namespace: istio-cni
+  profile: ambient
+----
++
+Set the `profile` field to `ambient`.
+
+.. Apply the `IstioCNI` CR by running the following command:
++
+[source,terminal]
+----
+$ oc apply -f istio-cni.yaml
+----
+
+.. Wait for the `IstioCNI` pods to contain the `Ready` status condition by running the following command:
++
+[source,terminal]
+----
+$ oc wait --for=condition=Ready istios/default --timeout=3m
+----
+
+. Install the Ztunnel proxy:
+
+.. Create the `ztunnel` namespace for Ztunnel proxy by running the following command:
++
+[source,terminal]
+----
+$ oc create namespace ztunnel
+----
++
+The namespace name for `ztunnel` project must match the `trustedZtunnelNamespace` parameter in {istio} configuration.
+
+.. Create the `Ztunnel` resource named `ztunnel.yaml` similar to the following example:
++
+.Example configuration
+[source,yaml]
+----
+apiVersion: sailoperator.io/v1alpha1
+kind: ZTunnel
+metadata:
+  name: default
+spec:
+  namespace: ztunnel
+  profile: ambient
+----
+
+.. Apply the `Ztunnel` CR by running the following command:
++
+[source,terminal]
+----
+$ oc apply -f ztunnel.yaml
+----
+
+.. Wait for the `Ztunnel` pods to contain the `Ready` status condition by running the following command:
++
+[source,terminal]
+----
+$ oc wait --for=condition=Ready ztunnel/default --timeout=3m
+----