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,20 @@
+:_content-type: ASSEMBLY
+[id="ossm-istio-ambient-mode"]
+= Istio ambient mode
+include::_attributes/common-attributes.adoc[]
+:context: ossm-istio-ambient-mode
+
+toc::[]
+
+include::snippets/technology-preview-istio-ambient-mode.adoc[]
+
+{istio} ambient mode introduces a sidecar-less architecture for {SMProductName}, 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::modules/ossm-about-istio-ambient-mode.adoc[leveloffset=+1]
+include::modules/ossm-installing-istio-ambient-mode.adoc[leveloffset=+1]
+
+
+[role="_additional-resources"]
+.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-istio-ambient-mode.adoc

@@ -0,0 +1,50 @@
+// 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 resources:
+
+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, 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 L7 features such as traffic management, policy enforcement, and observability. L7 features can be applied selectively, avoiding 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 opeartions* that removes the need to manage sidecar injection and lifecycle, reducing the complexity of mesh adoption and operations.
+
+* *Reduced resource consumption* by centralizing L4 feature in the Ztunnel proxy that reduces resource overhead per pod.
+
+* *Incremental adoption* that enables workloads to join the mesh with L4 features like mutual Transport Layer Security (mTLS) and basic policies and also, opt for L7 features selectively using `waypoint` proxies.
++
+[NOTE]
+====
+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 properly 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-installing-istio-ambient-mode.adoc

@@ -0,0 +1,137 @@
+// 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}"]
+= About Istio ambient mode
+
+You can install {istio} ambient mode on {ocp-product-title} by using the following procedure.
+
+.Prerequisites
+
+* You have deployed a cluster on {ocp-product-title} 4.19 or later.
+* You have installed {SMProduct} Operator 3.1.0 or later in the {ocp-product-title} cluster.
+* You are logged in to the {ocp-product-title} 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 the `{istio}` resource 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
+----
++
+The `profile` field should be set 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 similar to the following example:
++
+.Example configuration
+[source, yaml]
+----
+apiVersion: sailoperator.io/v1
+kind: IstioCNI
+metadata:
+  name: default
+spec:
+  namespace: istio-cni
+  profile: ambient
+----
++
+The `profile` field should be set 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 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
+----

snippets/technology-preview-istio-ambient-mode.adoc

@@ -0,0 +1,9 @@
+// snippet included in the following assmeblies:
+//
+// * service-mesh-docs-main/install/ossm-istio-ambient-mode.adoc
+
+[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 link:https://access.redhat.com/support/offerings/techpreview/[Technology Preview Features Support Scope].
+====