openshift · gwynnemonahan · Aug 27, 2026 · Aug 26, 2026
diff --git a/about/ossm-planning.adoc b/about/ossm-planning.adoc
@@ -16,8 +16,6 @@ include::modules/ossm-choose-data-plane-mode.adoc[leveloffset=+1]
 
 include::modules/ossm-about-sidecar-proxies.adoc[leveloffset=+2]
 
-include::modules/ossm-about-istio-ambient-mode.adoc[leveloffset=+2]
-
 include::modules/ossm-mesh-security-planning.adoc[leveloffset=+1]
 
 include::modules/ossm-about-mtls-planning.adoc[leveloffset=+2]

diff --git a/gateways/ossm-getting-traffic-into-a-mesh.adoc b/gateways/ossm-getting-traffic-into-a-mesh.adoc
@@ -1,10 +1,10 @@
 :_mod-docs-content-type: ASSEMBLY
 [id="ossm-getting-traffic-into-a-mesh"]
-= Getting traffic into a mesh
+= Route ingress traffic and expose mesh services
 include::_attributes/common-attributes.adoc[]
-:context: ossm-getting-traffic-into-a-mesh 
+:context: ossm-getting-traffic-into-a-mesh
 
-toc::[] 
+toc::[]
 
 [role="_abstract"]
 
@@ -28,8 +28,6 @@ include::modules/ossm-exposing-a-service-by-using-the-kubernetes-gateway-api-in-
 [id="additional-resources_{context}"]
 == Additional resources
 
-* xref:../gateways/ossm-about-gateways.adoc#ossm-about-gateway-injection_ossm-about-gateways[About gateway injection]
-
 * link:https://istio.io/latest/docs/reference/config/networking/gateway/#Gateway[Istio Gateway resource API reference (Istio documentation)]
 
 * link:https://istio.io/latest/docs/reference/config/networking/virtual-service/#VirtualService[VirtualService API reference (Istio documentation)]

diff --git a/install/ossm-SPIRE.adoc b/install/ossm-SPIRE.adoc
@@ -7,7 +7,8 @@ include::_attributes/common-attributes.adoc[]
 toc::[]
 
 [role="_abstract"]
-The SPIFFE Runtime Environment (SPIRE), supported by the OpenShift Zero Trust Workload Identity Manager, provides cryptographic identity management for your service mesh. SPIRE validates platform and runtime attributes to securely authenticate workloads across hybrid infrastructure.
+
+The SPIFFE Runtime Environment (SPIRE), supported by the OpenShift Zero Trust Workload Identity Manager, provides attested workload identity for your service mesh.
 
 include::snippets/technology-preview-SPIRE.adoc[]
 

diff --git a/install/ossm-cert-manager.adoc b/install/ossm-cert-manager.adoc
@@ -1,14 +1,14 @@
 :_mod-docs-content-type: ASSEMBLY
 [id="ossm-cert-manager"]
-= OpenShift Service Mesh and cert-manager
+= Configure automated certificate lifecycle management
 include::_attributes/common-attributes.adoc[]
 :context: ossm-cert-manager
 
 toc::[]
 
 [role="_abstract"]
 
-The cert-manager tool provides a unified API to manage X.509 certificates for applications in a {k8s} environment. You can use cert-manager to integrate with public or private key infrastructures (PKI) and automate certificate renewal.
+To centralize certificate lifecycle management for your mesh, replace the built-in {istio} certificate authority (CA) with the {cert-manager-operator}. This integration lets you connect {SMProductShortName} to your organization's preferred CA provider and automate certificate issuing, renewal, and rotation.
 
 include::modules/ossm-about-cert-manager.adoc[leveloffset=+1]
 
@@ -19,12 +19,3 @@ include::modules/ossm-verifying-cert-manager.adoc[leveloffset=+2]
 include::modules/ossm-verifying-cert-manager-ambient.adoc[leveloffset=+2]
 
 include::modules/ossm-uninstalling-cert-manager.adoc[leveloffset=+2]
-
-
-[role="_additional-resources"]
-[id="additional-resources_{context}"]
-== Additional resources
-
-* link:https://docs.redhat.com/en/documentation/openshift_container_platform/latest/html/security_and_compliance/cert-manager-operator-for-red-hat-openshift#cert-manager-operator-install[Installing the {cert-manager-operator}]
-
-* link:https://docs.redhat.com/en/documentation/openshift_container_platform/latest/html/security_and_compliance/cert-manager-operator-for-red-hat-openshift#cert-manager-operator-integrating-istio[Integrating the {cert-manager-operator} with Istio-CSR]
diff --git a/install/ossm-enabling-mtls.adoc b/install/ossm-enabling-mtls.adoc
@@ -1,14 +1,14 @@
 :_mod-docs-content-type: ASSEMBLY
 [id="ossm-enabling-mtls"]
-= Enabling mutual Transport Layer Security
+= Encrypt communication for mesh traffic
 include::_attributes/common-attributes.adoc[]
 :context: ossm-enabling-mtls
 
 toc::[]
 
 [role="_abstract"]
 
-You can use {SMProductName}  for your application to customize the communication security between the complex array of microservices. Mutual Transport Layer Security (mTLS) is a protocol that enables two parties to authenticate each other.
+You can use {SMProductName} for your application to customize the communication security between the complex array of microservices. Mutual Transport Layer Security (mTLS) is a protocol that enables two parties to authenticate each other.
 
 include::modules/ossm-about-mtls.adoc[leveloffset=+1]
 

diff --git a/install/ossm-supported-platforms-configurations.adoc b/install/ossm-supported-platforms-configurations.adoc
@@ -10,6 +10,18 @@ toc::[]
 
 Before you install {SMProductName}, verify that your environment meets the platform, configuration, and network requirements.
 
+Confirming compatibility early prevents installation failures and ensures that all {SMProductShortName} components operate as expected in your cluster.
+
+Verify the following areas before installing {SMProductShortName}:
+
+Supported platforms:: Your {ocp-product-title} version and managed platform type are compatible with {SMProductShortName}.
+
+Supported configurations:: Your cluster architecture and deployment topology meet {SMProductShortName} requirements.
+
+Supported network configurations:: Your cluster's Container Network Interface (CNI) plugin is validated for {SMProductShortName}.
+
+Supported Kiali configurations:: Your web browser and authentication strategy are compatible with the Kiali console.
+
 include::modules/ossm-supported-platforms.adoc[leveloffset=+1]
 
 include::modules/ossm-supported-configurations-sm.adoc[leveloffset=+1]

diff --git a/modules/ossm-about-cert-manager.adoc b/modules/ossm-about-cert-manager.adoc
@@ -4,15 +4,14 @@
 
 :_mod-docs-content-type: CONCEPT
 [id="ossm-cert-manager-integration-istio_{context}"]
-= About the cert-manager Operator istio-csr agent
+= The cert-manager Operator
 
 [role="_abstract"]
 
-The {cert-manager-operator} enhances certificate management for securing workloads and control plane components in {SMProductName} and {istio}. It supports issuing, delivering, and renewing certificates used for mutual Transport Layer Security (mTLS) through cert-manager issuers.
+The {cert-manager-operator} manages the `istio-csr` agent, which handles certificate signing requests from mesh proxies. You must install the Operator and deploy the agent before you create your `{istio}` resource. For Operator installation instructions, see the {ocp-product-title} documentation.
 
-By integrating {istio} with the `istio-csr` agent, which the cert-manager Operator manages, you enable {istio} to request and manage the certificates directly. The integration simplifies security configuration and centralizes certificate management within the cluster.
+[role="_additional-resources"]
+[id="additional-resources_{context}"]
+== Additional resources
 
-[NOTE]
-====
-You must install the {cert-manager-operator} before you create and install your `{istio}` resource.
-====
+* link:https://docs.redhat.com/en/documentation/openshift_container_platform/latest/html/security_and_compliance/cert-manager-operator-for-red-hat-openshift#cert-manager-operator-install[Installing the {cert-manager-operator}]
diff --git a/modules/ossm-about-configuring-a-gateway-to-accept-ingress-traffic.adoc b/modules/ossm-about-configuring-a-gateway-to-accept-ingress-traffic.adoc
@@ -19,4 +19,9 @@ Ingress routing with {k8s} Gateway API::
 
 The {k8s} Gateway API provides a standardized approach for configuring ingress traffic routing using native {k8s} resources. With this approach, you use `Gateway` and `HTTPRoute` (or `GRPCRoute`) resources to configure how traffic enters the mesh and routes to services.
 
-While {istio} `Gateway` and `VirtualService` resources support certain ingress use cases in ambient mode, the recommended approach is to use the {k8s} Gateway API, which provides full support and integration with ambient. You can also use the Gateway API with sidecar-based deployments.
+While {istio} `Gateway` and `VirtualService` resources support certain ingress use cases in ambient mode, the recommended approach is to use the {k8s} Gateway API, which provides full support and integration with ambient. You can also use the Gateway API with sidecar-based deployments.
+
+[NOTE]
+====
+After configuring ingress routing with one of these approaches, you must expose the gateway to external traffic using either a LoadBalancer service or an {ocp-short-name} route.
+====
diff --git a/modules/ossm-about-console-plugin.adoc b/modules/ossm-about-console-plugin.adoc
@@ -4,11 +4,11 @@
 
 :_mod-docs-content-type: CONCEPT
 [id="ossm-about-console-plugin_{context}"]
-= About {sm-plugin-full}
+= OpenShift Service Mesh Console plugin
 
 [role="_abstract"]
 
-The {SMPlugin} is an extension to {ocp-product-title} web console that provides visibility into your {SMProductShortName}.
+The {SMPlugin} is an extension to the {ocp-product-title} web console that surfaces Kiali observability features directly in the console.
 
 [WARNING]
 ====

diff --git a/modules/ossm-about-control-plane-update-strategies.adoc b/modules/ossm-about-control-plane-update-strategies.adoc
@@ -8,21 +8,26 @@
 
 [role="_abstract"]
 
-The `spec.updateStrategy` field in the `Istio` resource determines how the Operator updates the Istio control plane when a new version becomes available. You set this field when you create the `Istio` resource during installation.
+The `spec.updateStrategy` field in the `Istio` resource determines how the Operator updates the Istio control plane when a new version becomes available.
+You set this field when you create the `Istio` resource during installation.
 
 InPlace::
-The Operator updates the existing control plane in place. There is only one control plane revision at a time.
+The Operator updates the existing control plane in place.
+There is only one control plane revision at a time.
+You trigger the update by setting the `spec.version` field in the `Istio` resource, or you can use a `vX.Y-latest` version alias so the Operator applies new patch versions automatically as they become available.
+This is the simpler approach, but workloads might experience brief interruption during the transition.
+
+RevisionBased::
+The Operator deploys a new control plane alongside the existing one.
+You trigger the new revision by setting the `spec.version` field, but the process does not end there.
+You must then migrate workloads gradually from the old revision to the new one, validate that they are working correctly, and remove the old revision.
+This approach is more complex but allows canary-style validation before committing.
+The Operator bundles multiple Istio versions specifically to support this dual-revision workflow.
 
-You trigger the update by setting the `spec.version` field in the `Istio` resource, or you can use a `vX.Y-latest` version alias so the Operator applies new patch versions automatically as they become available. This is the simpler approach, but workloads might experience brief interruption during the transition.
-
-`RevisionBased`::
-The Operator deploys a new control plane alongside the existing one. You trigger the new revision by setting the `spec.version` field, but the process does not end there. You must then migrate workloads gradually from the old revision to the new one, validate that they are working correctly, and remove the old revision.
-
-This approach is more complex but allows canary-style validation before committing. The Operator bundles multiple Istio versions specifically to support this dual-revision workflow.
-
-[id="how-channels-and-strategies-work-together_{context}"]
 == How channels and strategies work together
 
-The channel and approval strategy control *when* a new Istio version becomes available to the Operator. The update strategy controls *how* the Operator transitions the control plane to that version.
+The channel and approval strategy control *when* a new Istio version becomes available to the Operator.
+The update strategy controls *how* the Operator transitions the control plane to that version.
 
-For example, you might use a versioned channel with manual approval to control exactly when new patches arrive, and then use the `InPlace` strategy to apply them quickly. Or you might use the stable channel with automatic approval to stay current, and then use the `RevisionBased` strategy to migrate workloads gradually after each update.
+For example, you might use a versioned channel with manual approval to control exactly when new patches arrive, and then use the `InPlace` strategy to apply them quickly.
+Or you might use the stable channel with automatic approval to stay current, and then use the `RevisionBased` strategy to migrate workloads gradually after each update.
diff --git a/modules/ossm-about-deploying-istio-using-service-mesh-operator.adoc b/modules/ossm-about-deploying-istio-using-service-mesh-operator.adoc
@@ -4,10 +4,8 @@
 
 :_mod-docs-content-type: CONCEPT
 [id="ossm-about-deploying-istio-using-service-mesh-operator_{context}"]
-= The {SMProductName} Operator
+= About deploying {istio} using the {SMProductName} Operator
 
 [role="_abstract"]
 
-The {SMProductName} Operator installs the custom resource definitions (CRDs) you need to deploy and configure {istio} control planes. Once the Operator is installed, you create custom resources such as `Istio` and `IstioCNI` to deploy the control plane, and the Operator manages their lifecycle. 
-
-The control plane runs as `istiod`, which handles service discovery, configuration distribution, and certificate management for the mesh.
+The {SMProductName} Operator installs the custom resource definitions (CRDs) you need to deploy and configure {istio} control planes. Once the Operator is installed, you create custom resources such as `Istio` and `IstioCNI` to deploy the control plane, and the Operator manages their lifecycle.
diff --git a/modules/ossm-about-deploying-multiple-control-planes.adoc b/modules/ossm-about-deploying-multiple-control-planes.adoc
@@ -4,7 +4,7 @@
 
 :_mod-docs-content-type: CONCEPT
 [id="ossm-about-deploying-multiple-control-planes_{context}"]
-= About deploying multiple control planes
+= Requirements for multiple control planes
 
 [role="_abstract"]
 

diff --git a/modules/ossm-about-discovery-selectors-istio-ambient-mode.adoc b/modules/ossm-about-discovery-selectors-istio-ambient-mode.adoc
@@ -4,12 +4,10 @@
 
 :_mod-docs-content-type: CONCEPT
 [id="ossm-about-discovery-selectors-istio-ambient-mode_{context}"]
-= About discovery selectors and Istio ambient mode
+= Discovery selectors in ambient mode
 
 [role="_abstract"]
 
 {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 multitenant clusters, limiting mesh participation to specific namespaces helps reduce configuration costs and supports many service meshes within the same cluster.
-
-For more information about discovery selectors, see "Scoping the Service Mesh with discovery selectors".
diff --git a/modules/ossm-about-discoveryselectors.adoc b/modules/ossm-about-discoveryselectors.adoc
@@ -4,7 +4,7 @@
 
 :_mod-docs-content-type: CONCEPT
 [id="ossm-about-discoveryselectors_{context}"]
-= About discovery selectors
+= How discovery selectors work
 
 [role="_abstract"]
 

diff --git a/modules/ossm-about-distributed-tracing-and-service-mesh.adoc b/modules/ossm-about-distributed-tracing-and-service-mesh.adoc
@@ -4,11 +4,11 @@
 
 :_mod-docs-content-type: CONCEPT
 [id="ossm-about-distributed-tracing-and-service-mesh_{context}"]
-= About {DTProductName} and {SMProductName}
+= Trace requests across services
 
 [role="_abstract"]
 
-Two parts integrate {DTProductName} with {SMProductName}: {TempoName} and {OTELName}.
+Integrate {DTProductName} with {SMProductName} by using {TempoName} for trace storage and {OTELName} for standardized telemetry data collection and processing.
 
 {TempoName}:: Provides {DTShortName} to monitor and troubleshoot transactions in complex distributed systems. Tempo derives its core functionality from the open source Grafana Tempo project.
 +

diff --git a/modules/ossm-about-external-control-plane-topology.adoc b/modules/ossm-about-external-control-plane-topology.adoc
@@ -4,8 +4,9 @@
 
 :_mod-docs-content-type: CONCEPT
 [id="ossm-about-external-control-plane-topology_{context}"]
-= About external control plane topology
+= Host the control plane externally for better security
 
 [role="_abstract"]
+An external control plane topology places the control plane on a dedicated cluster, separate from the clusters that run your application workloads. This isolation prevents a compromised application workload from reaching the control plane that manages certificates, policies, and mesh configuration.
 
-The external control plane topology improves security and offers the ability to host the Service Mesh as a service. In this configuration, one cluster hosts and manages the {istio} control plane, while other clusters host the applications.
+Platform teams can restrict access to the control plane cluster independently from the clusters where developers deploy applications. This separation also lets you host and manage the service mesh as a shared service across many application clusters.
diff --git a/modules/ossm-about-inplace-strategy.adoc b/modules/ossm-about-inplace-strategy.adoc
@@ -4,7 +4,7 @@
 
 :_mod-docs-content-type: CONCEPT
 [id="about-inplace-strategy_{context}"]
-= About InPlace strategy
+= InPlace update strategy
 
 [role="_abstract"]
 

diff --git a/modules/ossm-about-installing-console-plugin.adoc b/modules/ossm-about-installing-console-plugin.adoc
@@ -4,7 +4,7 @@
 
 :_mod-docs-content-type: CONCEPT
 [id="ossm-about-installing-console-plugin_{context}"]
-= About installing {sm-plugin-full}
+= Console plugin installation requirements
 
 [role="_abstract"]
 

diff --git a/modules/ossm-about-istio-cni-update-process.adoc b/modules/ossm-about-istio-cni-update-process.adoc
@@ -4,7 +4,7 @@
 
 :_mod-docs-content-type: CONCEPT
 [id="ossm-about-istio-cni-update-process_{context}"]
-= About the Istio CNI update process
+= How the Istio CNI update process works
 
 [role="_abstract"]
 

diff --git a/modules/ossm-about-istio-control-plane-update-strategies.adoc b/modules/ossm-about-istio-control-plane-update-strategies.adoc
@@ -4,7 +4,7 @@
 
 :_mod-docs-content-type: CONCEPT
 [id="ossm-about-istio-control-plane-update-strategies_{context}"]
-= About Istio control plane update strategies
+= Choose a rollout strategy: InPlace or RevisionBased
 
 [role="_abstract"]
 

diff --git a/modules/ossm-about-istio-deployment.adoc b/modules/ossm-about-istio-deployment.adoc
@@ -4,7 +4,7 @@
 
 :_mod-docs-content-type: CONCEPT
 [id="about-istio-deployment_{context}"]
-= Deploy a mesh in sidecar mode
+= Deploy in sidecar mode
 
 [role="_abstract"]
 

diff --git a/modules/ossm-about-istio-high-availability.adoc b/modules/ossm-about-istio-high-availability.adoc
@@ -4,13 +4,13 @@
 
 :_mod-docs-content-type: CONCEPT
 [id="ossm-about-istio-high-availability_{context}"]
-= About {istio} High Availability
+= {istio} High Availability (HA) mode
 
 [role="_abstract"]
 
-Running the {istio} control plane in High Availability (HA) mode prevents single points of failure, and ensures continuous mesh operation even if an `istiod` pod fails.
+Running the {istio} control plane in High Availability (HA) mode ensures continuous mesh operation even if an `istiod` pod fails.
 
-By using HA, if one `istiod` pod becomes unavailable, another one continues to manage and configure the {istio} data plane, preventing service outages or disruptions. HA provides scalability by distributing the control plane workload, enables graceful upgrades, supports disaster recovery operations, and protects against zone-wide mesh outages.
+In HA mode, if one `istiod` pod becomes unavailable, another one continues to manage and configure the {istio} data plane, preventing service outages or disruptions. HA provides scalability by distributing the control plane workload, enables graceful upgrades, supports disaster recovery operations, and protects against zone-wide mesh outages.
 
 There are two ways for a system administrator to configure HA for the {istio} deployment:
 

diff --git a/modules/ossm-about-istio-update-process.adoc b/modules/ossm-about-istio-update-process.adoc
@@ -4,7 +4,7 @@
 
 :_mod-docs-content-type: CONCEPT
 [id="ossm-about-istio-update-process_{context}"]
-= About Istio update process
+= Control plane update process
 
 [role="_abstract"]