openshift · gwynnemonahan · Aug 31, 2026 · Aug 26, 2026
diff --git a/install/ossm-cert-manager.adoc b/install/ossm-cert-manager.adoc
@@ -1,6 +1,6 @@
 :_mod-docs-content-type: ASSEMBLY
 [id="ossm-cert-manager"]
-= Configure automated certificate lifecycle management
+= Automate certificate lifecycle management
 include::_attributes/common-attributes.adoc[]
 :context: ossm-cert-manager
 

diff --git a/install/ossm-enabling-mtls.adoc b/install/ossm-enabling-mtls.adoc
@@ -8,7 +8,11 @@ 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.
+Encrypting mesh communication requires configuring Transport Layer Security (TLS) in two distinct areas:
+
+* Mutual TLS (mTLS) encrypts and authenticates traffic between services inside the mesh. By default, the mesh automatically uses mTLS for service-to-service communication (Auto mTLS), but services accept both encrypted and plain text connections (PERMISSIVE mode). To enforce encryption and reject plain text traffic, you must enable STRICT mTLS mode.
+
+* TLS for gateways encrypts traffic entering and leaving the mesh at ingress and egress gateways. You must configure gateway TLS separately from mTLS because gateways operate at the mesh boundary, not between mesh services.
 
 include::modules/ossm-about-mtls.adoc[leveloffset=+1]
 
@@ -17,13 +21,3 @@ include::modules/ossm-enabling-strict-mtls-namespace.adoc[leveloffset=+1]
 include::modules/ossm-enabling-strict-mtls-whole-service-mesh.adoc[leveloffset=+1]
 
 include::modules/ossm-validating-encryptions-with-kiali.adoc[leveloffset=+1]
-
-[role="_additional-resources"]
-[id="additional-resources_{context}"]
-== Additional resources
-
-* link:https://istio.io/latest/docs/tasks/security/tls-configuration/workload-min-tls-version/[Istio workload minimum TLS version configuration (Istio documentation)]
-
-* link:https://istio.io/latest/docs/ops/configuration/traffic-management/tls-configuration/[Understanding TLS configuration (Istio documentation)]
-
-* link:https://istio.io/latest/docs/concepts/security/#permissive-mode[Permissive mode (Istio documentation)]
diff --git a/install/ossm-supported-platforms-configurations.adoc b/install/ossm-supported-platforms-configurations.adoc
@@ -1,6 +1,6 @@
 :_mod-docs-content-type: ASSEMBLY
 [id="ossm-supported-platforms-configurations"]
-= Check platform prerequisites
+= Evaluate platform compatibility
 include::_attributes/common-attributes.adoc[]
 :context: ossm-supported-platforms-configurations
 
@@ -10,50 +10,10 @@ 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]
 
 include::modules/ossm-supported-configurations-networks.adoc[leveloffset=+1]
 
 include::modules/ossm-supported-configurations-kiali.adoc[leveloffset=+1]
-
-[role="_additional-resources"]
-[id="additional-resources_{context}"]
-== Additional resources
-
-* link:https://access.redhat.com/support/policy/updates/openshift_operators[OpenShift Operator Life Cycles]
-
-* link:https://docs.redhat.com/en/documentation/openshift_container_platform/latest/html/installation_overview/ocp-installation-overview#installation-overview_ocp-installation-overview[About {product-title} installation]
-
-* link:https://docs.redhat.com/en/documentation/openshift_container_platform/latest/html/installing_on_aws/installing-methods-aws[Installing {product-title} on AWS]
-
-* link:https://docs.redhat.com/en/documentation/openshift_container_platform/latest/html/installing_on_aws/user-provisioned-infrastructure[Installing {product-title} on AWS with user-provisioned infrastructure]
-
-* link:https://docs.redhat.com/en/documentation/openshift_container_platform/latest/html/installing_on_bare_metal/preparing-to-install-on-bare-metal[Installing {product-title} on bare metal]
-
-* link:https://docs.redhat.com/en/documentation/openshift_container_platform/latest/html/installing_on_vmware_vsphere/preparing-to-install-on-vsphere[Installing {product-title} on vSphere]
-
-* link:https://docs.redhat.com/en/documentation/openshift_container_platform/latest/html/installing_on_ibm_z_and_ibm_linuxone/preparing-to-install-on-ibm-z[Installing {product-title} on {ibm-z-title}® and IBM® LinuxONE]
-
-* link:https://docs.redhat.com/en/documentation/openshift_container_platform/latest/html/installing_on_ibm_power/preparing-to-install-on-ibm-power[Installing {product-title} on {ibm-power-title}®]
-
-* link:https://docs.redhat.com/en/documentation/openshift_dedicated/latest/html/networking/ovn-kubernetes-network-plugin#about-ovn-kubernetes[About the OVN-Kubernetes network plugin]
-
-* link:https://access.redhat.com/articles/5436171[Certified OpenShift CNI plugins]
-
-* link:https://docs.redhat.com/en/documentation/openshift_container_platform/latest/html/installation_overview/installing-preparing#supported-installation-methods-for-different-platforms[Restricted network]
-
-* link:https://access.redhat.com/support/policy/updates/openshift_operators[Support Policy]
diff --git a/modules/ossm-about-SPIRE.adoc b/modules/ossm-about-SPIRE.adoc
@@ -0,0 +1,39 @@
+// Module included in the following assemblies:
+//
+// * install/ossm-SPIRE.adoc
+
+:_mod-docs-content-type: CONCEPT
+[id="ossm-about-SPIRE_{context}"]
+= SPIRE for workload identity management
+
+[role="_abstract"]
+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[]
+
+You can deploy SPIRE as a standalone solution or integrate it with cert-manager. When used together, cert-manager acts as the root Certificate Authority (CA), automatically issuing intermediate signing certificates to SPIRE, while SPIRE handles workload identity for mesh communication.
+
+[id="about-spire-and-spiffe_{context}"]
+== About SPIRE and SPIFFE
+
+SPIRE implements the Secure Production Identity Framework for Everyone (SPIFFE) open standards. It issues short-lived cryptographic credentials, called SPIFFE Verifiable Identity Documents (SVIDs), to workloads and service mesh components. The architecture uses a central server and node agents to integrate with the {SMProduct} data plane through a local UNIX domain socket API.
+
+Before issuing an SVID, SPIRE enforces rigorous verification. Node attestation verifies the underlying host platform, while workload attestation inspects runtime attributes such as pod namespaces and service accounts. This process ensures cryptographically verified identities and strong workload authentication before any communication across the mesh begins.
+
+[id="benefits-of-spire_{context}"]
+== Benefits of SPIRE
+
+SPIRE provides the following key benefits:
+
+* Zero-trust architecture: Every workload interaction requires cryptographic verification based on attested identity, with no implicit trust zones.
+
+* Cross-platform authentication: Uses SPIFFE identities for workload authentication across clouds, virtual machines, and bare-metal environments.
+
+* Network-independent security: Authentication does not depend on network boundaries, IP addresses, or firewall rules.
+
+* Automatic credential management: Automatically issues and rotates credentials for workloads, eliminating embedded passwords, API keys, and certificates.
+
+[IMPORTANT]
+====
+Currently, only single-cluster sidecar deployments of {SMProduct} integrate with SPIRE.
+====
diff --git a/modules/ossm-about-cert-manager.adoc b/modules/ossm-about-cert-manager.adoc
@@ -4,14 +4,8 @@
 
 :_mod-docs-content-type: CONCEPT
 [id="ossm-cert-manager-integration-istio_{context}"]
-= The cert-manager Operator
+= Cert-manager Operator overview
 
 [role="_abstract"]
 
 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.
-
-[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}]
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
@@ -8,7 +8,7 @@
 
 [role="_abstract"]
 
-{SMProductName} offers two approaches to configure ingress traffic routing to services in the mesh. The approach depends on the service mesh deployment mode and traffic management requirements.
+Routing ingress traffic to mesh services requires two steps: configuring routing rules and exposing the gateway proxy to external clients. {SMProductName} offers two approaches for configuring routing rules, depending on your deployment mode and traffic management requirements.
 
 Ingress routing with gateway injection and {istio} APIs::
 When you install a gateway by using gateway injection, you can configure it to receive ingress traffic by using the {istio} `Gateway` and `VirtualService` resources in combination.
@@ -23,5 +23,5 @@ While {istio} `Gateway` and `VirtualService` resources support certain ingress u
 
 [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.
+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. This gives external clients access to mesh services.
 ====
diff --git a/modules/ossm-about-exposing-services-to-traffic-outside-a-cluster.adoc b/modules/ossm-about-exposing-services-to-traffic-outside-a-cluster.adoc
@@ -4,7 +4,7 @@
 
 :_mod-docs-content-type: CONCEPT
 [id="ossm-about-exposing-services-to-traffic-outside-a-cluster_{context}"]
-= About exposing services to traffic outside a cluster
+= External access to mesh services
 
 [role="_abstract"]
 

diff --git a/modules/ossm-about-ingress-routing-ambient-mode.adoc b/modules/ossm-about-ingress-routing-ambient-mode.adoc
@@ -4,11 +4,11 @@
 
 :_mod-docs-content-type: CONCEPT
 [id="ossm-about-ingress-routing-ambient-mode_{context}"]
-= About ingress traffic routing approaches in ambient mode
+= Ambient mode ingress routing
 
 [role="_abstract"]
 
-When using the {istio} ambient mode, you can use the {k8s} Gateway API to configure ingress traffic routing.
+In the {istio} ambient mode, use the {k8s} Gateway API to configure ingress traffic routing.
 
 Waypoint proxies for Layer 7 routing::
 You can deploy a waypoint proxy in the namespace that has your service to apply Layer 7 (L7) routing policies, such as path-based routing or header matching. In ambient mode, waypoint proxies process L7 traffic and enforce `HTTPRoute` and `GRPCRoute` rules.

diff --git a/modules/ossm-about-mtls.adoc b/modules/ossm-about-mtls.adoc
@@ -4,16 +4,29 @@
 
 :_mod-docs-content-type: CONCEPT
 [id="ossm-about-mtls_{context}"]
-= Mutual TLS in {SMProductName}
+= Authenticate services with mutual TLS
 
 [role="_abstract"]
+Mutual TLS (mTLS) authentication operates differently depending on your mesh deployment mode.
 
-Review the following `{istio}` resources and concepts to configure mTLS settings properly:
+[id="ossm-about-mtls-sidecar_{context}"]
+== Mutual TLS in sidecar mode
 
-`PeerAuthentication`:: defines the type of mTLS traffic a sidecar accepts. `PERMISSIVE` mode allows both plain text and mTLS traffic. `STRICT` mode requires mTLS for all incoming traffic..
+In sidecar mode, mTLS settings operate between sidecar proxies without application code changes:
 
-`DestinationRule`:: configures the type of TLS traffic a sidecar sends. In `DISABLE` mode, the sidecar sends plain text. In `SIMPLE`, `MUTUAL`, and `ISTIO_MUTUAL` modes, the sidecar establishes a TLS connection.
+`PeerAuthentication`:: Controls incoming traffic rules. By default, `PERMISSIVE` mode accepts both plain text and mTLS traffic. `STRICT` mode rejects plain text and requires mTLS for all incoming requests.
 
-`Auto mTLS`:: ensures the mesh uses mTLS by default to encrypt all inter-mesh traffic, regardless of the `PeerAuthentication` mode configuration. The `enableAutoMtls` global mesh configuration field controls `Auto mTLS`, which {SMProduct} 2 and 3 enable by default. The mTLS setting operates entirely between sidecar proxies, requiring no changes to application or service code.
+`DestinationRule`:: Controls outgoing traffic rules. In `DISABLE` mode, the sidecar sends plain text. In `SIMPLE`, `MUTUAL`, and `ISTIO_MUTUAL` modes, the sidecar initiates a TLS connection.
 
-By default, `PeerAuthentication` uses `PERMISSIVE` mode, allowing sidecars in the {SMProductShortName} to accept both plain text and mTLS-encrypted traffic.
+`Auto mTLS`:: Enabled by default in {SMProduct} 2 and 3. Automatically uses mTLS for inter-mesh traffic whenever a destination pod has a sidecar proxy, falling back to plain text for non-mesh targets.
+
+[id="ossm-about-mtls-ambient_{context}"]
+== Mutual TLS in ambient mode
+
+In ambient mode, mTLS operates transparently at the infrastructure level by using `ztunnel` node agents and optional waypoint proxies:
+
+Automatic L4 encryption:: Traffic between workloads enrolled in ambient mode is automatically encrypted at Layer 4 using mTLS.
+
+`PeerAuthentication` enforcement:: By default, ambient mode uses `PERMISSIVE` mode, allowing ambient workloads to encrypt inter-mesh traffic while still accepting plain text from non-ambient sources. Applying a `PeerAuthentication` policy with `mode: STRICT` causes the `ztunnel` agent to enforce mTLS and reject plain text requests before they reach your application.
+
+Waypoint proxy scope:: Waypoint proxies handle Layer 7 (L7) application policies and routing. They receive connections that have already been authenticated by `ztunnel` at Layer 4.
diff --git a/modules/ossm-configure-attested-workload-identity.adoc b/modules/ossm-configure-attested-workload-identity.adoc
@@ -4,7 +4,7 @@
 
 :_mod-docs-content-type: CONCEPT
 [id="ossm-configure-attested-workload-identity_{context}"]
-= Configure attested workload identity
+= Verify workload identity with cryptographic proof
 
 [role="_abstract"]
 

diff --git a/modules/ossm-configure-authorization-policies.adoc b/modules/ossm-configure-authorization-policies.adoc
@@ -4,7 +4,7 @@
 
 :_mod-docs-content-type: CONCEPT
 [id="ossm-configure-authorization-policies_{context}"]
-= Configure service authorization policies
+= Control service access with authorization policies
 
 [role="_abstract"]
 

diff --git a/modules/ossm-customize-mesh-topology.adoc b/modules/ossm-customize-mesh-topology.adoc
@@ -0,0 +1,20 @@
+// Module included in the following assemblies:
+//
+// TBD
+
+:_mod-docs-content-type: CONCEPT
+[id="ossm-customize-mesh-topology_{context}"]
+= Customize your mesh topology
+
+[role="_abstract"]
+As your service mesh requirements evolve, you might need to adapt your deployment topology to support specific operational, security, or architectural goals. Customizing your mesh topology helps you align the mesh infrastructure with constraints such as geographic distribution, team boundaries, security posture, or availability requirements.
+
+The default single-cluster, single-control-plane topology works well for many deployments. However, certain scenarios might benefit from topology customization:
+
+Multi-cluster mesh:: When services need to communicate across clusters, extending your mesh across multiple clusters can provide cross-cluster service discovery, load balancing, and failover capabilities. This approach might suit scenarios where you need geographic distribution, fault isolation across clusters, or hybrid cloud architectures.
+
+Multiple independent meshes on one cluster:: When teams or applications share a cluster but require strict isolation, deploying multiple independent meshes with separate control planes can enforce boundaries between workloads. This approach might suit scenarios where you need tenant isolation, separate security policies, or independent lifecycle management for different application groups.
+
+External control plane:: When security requirements call for separating management infrastructure from application workloads, hosting the control plane on a separate cluster can reduce the attack surface on your application cluster. This approach might suit scenarios where you need to meet compliance requirements, minimize control plane resource contention with workloads, or centralize mesh management across multiple data plane clusters.
+
+Each topology customization introduces additional operational complexity and resource requirements. Consider your current and anticipated needs (such as failover requirements, team autonomy, security boundaries, and operational capacity) when evaluating whether to customize your topology.
diff --git a/modules/ossm-enable-pqc.adoc b/modules/ossm-enable-pqc.adoc
@@ -4,7 +4,7 @@
 
 :_mod-docs-content-type: CONCEPT
 [id="ossm-enable-pqc_{context}"]
-= Configure post-quantum cryptography (PQC)
+= Protect against quantum computing threats
 
 [role="_abstract"]
 

diff --git a/modules/ossm-enabling-strict-mtls-namespace.adoc b/modules/ossm-enabling-strict-mtls-namespace.adoc
@@ -5,7 +5,7 @@
 
 :_mod-docs-content-type: CONCEPT
 [id="ossm-enabling-strict-mtls-namespace_{context}"]
-= Enabling strict mTLS mode by using the namespace
+= Enable strict mTLS for a namespace in sidecar mode 
 
 [role="_abstract"]
 

diff --git a/modules/ossm-enabling-strict-mtls-whole-service-mesh.adoc b/modules/ossm-enabling-strict-mtls-whole-service-mesh.adoc
@@ -4,7 +4,7 @@
 
 :_mod-docs-content-type: CONCEPT
 [id="ossm-enabling-strict-mtls-whole-service-mesh_{context}"]
-= Enabling strict mTLS across the whole service mesh
+= Enable strict mTLS mesh-wide in sidecar mode
 
 [role="_abstract"]
 

diff --git a/modules/ossm-release-notes-consoles-and-dashboards.adoc b/modules/ossm-release-notes-consoles-and-dashboards.adoc
@@ -7,6 +7,7 @@
 = Consoles and dashboards
 
 [role="_abstract"]
+Console and dashboard tools provide visualization and management capabilities for monitoring and configuring your service mesh.
 
 [cols="1,1"]
 |===