openshift · stevsmit · May 27, 2026 · May 27, 2026
diff --git a/modules/nw-ovn-ipsec-certificates.adoc b/modules/nw-ovn-ipsec-certificates.adoc
@@ -6,6 +6,7 @@
 [id="nw-ovn-ipsec-certificates_{context}"]
 = Security certificate generation and rotation
 
+[role="_abstract"]
 The Cluster Network Operator (CNO) generates a self-signed X.509 certificate authority (CA) that is used by IPsec for encryption. Certificate signing requests (CSRs) from each node are automatically fulfilled by the CNO.
 
 The CA is valid for 10 years. The individual node certificates are valid for 5 years and are automatically rotated after 4 1/2 years elapse.
diff --git a/modules/nw-ovn-ipsec-disable.adoc b/modules/nw-ovn-ipsec-disable.adoc
@@ -6,7 +6,8 @@
 [id="nw-ovn-ipsec-disable_{context}"]
 = Disabling IPsec encryption
 
-As a cluster administrator, you can disable IPsec encryption.
+[role="_abstract"]
+To disable IPsec encryption in {product-title}, you can patch the cluster `Network` custom resource and set `ipsecConfig` mode to `Disabled`.
 
 .Prerequisites
 

diff --git a/modules/nw-ovn-ipsec-enable.adoc b/modules/nw-ovn-ipsec-enable.adoc
@@ -6,9 +6,8 @@
 [id="nw-ovn-ipsec-enable_{context}"]
 = Enabling IPsec encryption
 
-As a cluster administrator you can enable pod-to-pod IPsec encryption between the cluster and external IPsec endpoints.
-
-You can configure IPsec in either of the following modes:
+[role="_abstract"]
+To enable pod-to-pod and external IPsec encryption in {product-title}, you can patch the cluster `Network` custom resource and set `ipsecConfig` mode to `Full` or `External`.
 
 - `Full`: Encryption for pod-to-pod and external traffic
 - `External`: Encryption for external traffic
@@ -42,11 +41,13 @@ $ oc patch networks.operator.openshift.io cluster --type=merge -p \
     "defaultNetwork":{
       "ovnKubernetesConfig":{
         "ipsecConfig":{
-          "mode":"<mode"> <1>
+          "mode":"<mode>"
         }}}}}'
 ----
 +
-<1> Specify `External` to encrypt traffic to external hosts or specify `Full` to encrypt pod-to-pod traffic and, optionally, traffic to external hosts. By default, IPsec is disabled.
+where:
+
+`spec.defaultNetwork.ovnKubernetesConfig.ipsecConfig.mode`:: Specifies `External` to encrypt traffic to external hosts or `Full` to encrypt pod-to-pod traffic and, optionally, traffic to external hosts. By default, IPsec is disabled.
 +
 .Example configuration that has IPsec enabled in `Full` mode and `encapsulation` set to `Always`
 [source,terminal]
@@ -95,11 +96,13 @@ As a cluster administrator, you can verify that you enabled IPsec between pods o
 +
 [source,terminal]
 ----
-$ oc -n openshift-ovn-kubernetes rsh ovnkube-node-<XXXXX> ovn-nbctl --no-leader-only get nb_global . ipsec <1>
+$ oc -n openshift-ovn-kubernetes rsh ovnkube-node-<XXXXX> ovn-nbctl --no-leader-only get nb_global . ipsec
 ----
 +
 --
-where: `<XXXXX>` specifies the random sequence of letters for a pod from an earlier step.
+where:
+
+`<XXXXX>`:: Specifies the random sequence of letters for a pod from an earlier step.
 --
 +
 Successful output from the command shows the status as `true`.
diff --git a/modules/nw-ovn-ipsec-encryption.adoc b/modules/nw-ovn-ipsec-encryption.adoc
@@ -6,6 +6,7 @@
 [id="nw-ovn-ipsec-encryption_{context}"]
 = Encryption protocol and IPsec mode
 
-The encrypt cipher used is `AES-GCM-16-256`. The integrity check value (ICV) is `16` bytes. The key length is `256` bits.
+[role="_abstract"]
+Pod-to-pod IPsec in {product-title} uses `AES-GCM-16-256` in transport mode with a 256-bit key and a 16-byte integrity check value. _Transport mode_ encrypts end-to-end communication by adding an Encapsulated Security Payload (ESP) header to the IP header of the original packet and encrypts the packet data. 
 
-The IPsec mode used is _Transport mode_, a mode that encrypts end-to-end communication by adding an Encapsulated Security Payload (ESP) header to the IP header of the original packet and encrypts the packet data. {product-title} does not currently use or support IPsec _Tunnel mode_ for pod-to-pod communication.
+{product-title} does not currently use or support IPsec _Tunnel mode_ for pod-to-pod communication.
diff --git a/modules/nw-ovn-ipsec-external.adoc b/modules/nw-ovn-ipsec-external.adoc
@@ -6,6 +6,7 @@
 [id="nw-ovn-ipsec-external_{context}"]
 = IPsec encryption for external traffic
 
+[role="_abstract"]
 {product-title} supports the use of IPsec to encrypt traffic destined for external hosts, ensuring confidentiality and integrity of data in transit. This feature relies on X.509 certificates that you must supply.
 
 [id="supported-platforms_{context}"]

diff --git a/modules/nw-ovn-ipsec-north-south-disable.adoc b/modules/nw-ovn-ipsec-north-south-disable.adoc
@@ -6,7 +6,8 @@
 [id="nw-ovn-ipsec-north-south-disable_{context}"]
 = Disabling IPsec encryption for an external IPsec endpoint
 
-As a cluster administrator, you can remove an existing IPsec tunnel to an external host.
+[role="_abstract"]
+To stop encrypting traffic to an external host in {product-title}, you can remove the IPsec tunnel configuration from your cluster nodes.
 
 .Prerequisites
 

diff --git a/modules/nw-ovn-ipsec-north-south-enable.adoc b/modules/nw-ovn-ipsec-north-south-enable.adoc
@@ -7,7 +7,7 @@
 = Configuring IPsec encryption for external traffic
 
 [role="_abstract"]
-As a cluster administrator, to encrypt external traffic with IPsec you must configure IPsec for your network infrastructure, including providing PKCS#12 certificates. Because this procedure uses Butane to create machine configs, you must have the `butane` tool installed.
+To configure IPsec encryption for traffic between {product-title} and external hosts, you can create Butane machine configs with PKCS#12 certificates and apply them to cluster nodes.
 
 [NOTE]
 ====
@@ -17,7 +17,7 @@ After you apply the machine config, the Machine Config Operator (MCO) reboots af
 .Prerequisites
 
 * Install the {oc-first}.
-* You have installed the `butane` tool on your local computer.
+* You have installed the `butane` tool on your local computer. For more information, see "Installing Butane".
 * You have installed the NMState Operator on the cluster.
 * You logged in to the cluster as a user with `cluster-admin` privileges.
 * You have an existing PKCS#12 certificate for the IPsec endpoint and a CA cert in Privacy Enhanced Mail (PEM) format.

diff --git a/modules/nw-ovn-ipsec-prerequisites.adoc b/modules/nw-ovn-ipsec-prerequisites.adoc
@@ -0,0 +1,18 @@
+// Module included in the following assemblies:
+//
+// * networking/openshift_network_security/configuring-ipsec-ovn.adoc
+
+:_mod-docs-content-type: CONCEPT
+[id="nw-ovn-ipsec-prerequisites_{context}"]
+= Prerequisites for IPsec encryption for external traffic
+
+[role="_abstract"]
+The following prerequisites are required to add certificates into the host NSS database and to configure IPsec to communicate with external hosts.
+
+* Set `routingViaHost=true` in the `ovnKubernetesConfig.gatewayConfig` specification of the OVN-Kubernetes network plugin.
+* Install the NMState Operator. This Operator is required for specifying the IPsec configuration. For more information, see "Kubernetes NMState Operator".
++
+[NOTE]
+====
+The NMState Operator is supported on {gcp-first} only for configuring IPsec.
+====
diff --git a/modules/nw-ovn-ipsec-traffic.adoc b/modules/nw-ovn-ipsec-traffic.adoc
@@ -6,13 +6,15 @@
 [id="nw-ovn-ipsec-traffic_{context}"]
 = Types of network traffic flows encrypted by pod-to-pod IPsec
 
-With IPsec enabled, only the following network traffic flows between pods are encrypted:
+[role="_abstract"]
+When pod-to-pod IPsec is enabled in {product-title}, OVN-Kubernetes encrypts only selected traffic flows between pods on different nodes and from host-network pods. Other flows, such as traffic on the same node, remain unencrypted.
+
+The following network traffic flows between pods are encrypted when pod-to-pod IPsec is enabled:
 
 * Traffic between pods on different nodes on the cluster network
 * Traffic from a pod on the host network to a pod on the cluster network
 
-The following traffic flows are not encrypted:
-
+The following traffic flows are not encrypted when pod-to-pod IPsec is enabled:
 * Traffic between pods on the same node on the cluster network
 * Traffic between pods on the host network
 * Traffic from a pod on the cluster network to a pod on the host network

diff --git a/modules/nw-own-ipsec-modes.adoc b/modules/nw-own-ipsec-modes.adoc
@@ -6,7 +6,10 @@
 [id="nw-ovn-ipsec-modes_{context}"]
 = Modes of operation
 
-When using IPsec on your {product-title} cluster, you can choose from the following operating modes:
+[role="_abstract"]
+You can configure IPsec on {product-title} clusters in `Disabled`, `External`, or `Full` pod-to-pod and external encryption modes. Each mode determines which traffic OVN-Kubernetes encrypts by default.
+
+The following table describes the different modes of operation:
 
 .IPsec modes of operation
 [cols="2,6,2",options="header"]

diff --git a/modules/nw-own-ipsec-required-ports.adoc b/modules/nw-own-ipsec-required-ports.adoc
@@ -6,7 +6,8 @@
 [id="network-connectivity-requirements-ipsec_{context}"]
 = Network connectivity requirements when IPsec is enabled
 
-You must configure the network connectivity between machines to allow {product-title} cluster components to communicate. Each machine must be able to resolve the hostnames of all other machines in the cluster.
+[role="_abstract"]
+When IPsec is enabled in {product-title}, you must configure the network connectivity between machines to allow cluster components to communicate. Each machine must be able to resolve the hostnames of all other machines in the cluster.
 
 .Ports used for all-machine to all-machine communications
 [cols="2a,2a,5a",options="header"]

diff --git a/modules/pod-to-pod-ipsec.adoc b/modules/pod-to-pod-ipsec.adoc
@@ -0,0 +1,10 @@
+// Module included in the following assemblies:
+//
+// * networking/openshift_network_security/configuring-ipsec-ovn.adoc
+
+:_mod-docs-content-type: CONCEPT
+[id="pod-to-pod-ipsec_{context}"]
+= IPsec encryption for pod-to-pod traffic
+
+[role="_abstract"]
+For IPsec encryption of pod-to-pod traffic, the following sections describe which specific pod-to-pod traffic is encrypted, what kind of encryption protocol is used, and how X.509 certificates are handled. These sections do not apply to IPsec encryption between the cluster and external hosts, which you must configure manually for your specific external network infrastructure.
diff --git a/networking/network_security/configuring-ipsec-ovn.adoc b/networking/network_security/configuring-ipsec-ovn.adoc
@@ -6,6 +6,7 @@ include::_attributes/common-attributes.adoc[]
 
 toc::[]
 
+[role="_abstract"]
 By enabling IPsec, you can encrypt both internal pod-to-pod cluster traffic between nodes and external traffic between pods and IPsec endpoints external to your cluster. All pod-to-pod network traffic between nodes on the OVN-Kubernetes cluster network is encrypted with IPsec in _Transport mode_.
 
 IPsec is disabled by default. You can enable IPsec either during or after installing the cluster. For information about cluster installation, see xref:../../installing/overview/index.adoc#ocp-installation-overview[{product-title} installation overview].
@@ -38,31 +39,18 @@ The following list outlines key tasks in the IPsec documentation:
 // Modes of operation
 include::modules/nw-own-ipsec-modes.adoc[leveloffset=+1]
 
-// Uses xrefs, so must be located here
-[id="prerequisites_{context}"]
-== Prerequisites
+// Prerequisites
+include::modules/nw-ovn-ipsec-prerequisites.adoc[leveloffset=+1]
 
-For IPsec support for encrypting traffic to external hosts, ensure that you meet the following prerequisites:
-
-* Set `routingViaHost=true` in the `ovnKubernetesConfig.gatewayConfig` specification of the OVN-Kubernetes network plugin.
-* Install the NMState Operator. This Operator is required for specifying the IPsec configuration. For more information, see xref:../../networking/networking_operators/k8s-nmstate-about-the-k8s-nmstate-operator.adoc#k8s-nmstate-about-the-k8s-nmstate-operator[Kubernetes NMState Operator].
-+
---
-[NOTE]
-====
-The NMState Operator is supported on {gcp-first} only for configuring IPsec.
-====
---
-* The Butane tool (`butane`) is installed. To install Butane, see xref:../../installing/install_config/installing-customizing.adoc#installation-special-config-butane-install_installing-customizing[Installing Butane].
+[role="_additional-resources"]
+[id="additional-resources_k8s-nmstate-about-the-k8s-nmstate-operator_{context}"]
+== Additional resources
 
-These prerequisites are required to add certificates into the host NSS database and to configure IPsec to communicate with external hosts.
+* xref:../../networking/networking_operators/k8s-nmstate-about-the-k8s-nmstate-operator.adoc#k8s-nmstate-about-the-k8s-nmstate-operator[Kubernetes NMState Operator]
 
 include::modules/nw-own-ipsec-required-ports.adoc[leveloffset=+1]
 
-[id="pod-to-pod-ipsec_{context}"]
-== IPsec encryption for pod-to-pod traffic
-
-For IPsec encryption of pod-to-pod traffic, the following sections describe which specific pod-to-pod traffic is encrypted, what kind of encryption protocol is used, and how X.509 certificates are handled. These sections do not apply to IPsec encryption between the cluster and external hosts, which you must configure manually for your specific external network infrastructure.
+include::modules/pod-to-pod-ipsec.adoc[leveloffset=+1]
 
 // Types of network traffic flows encrypted by pod-to-pod IPsec
 include::modules/nw-ovn-ipsec-traffic.adoc[leveloffset=+2]
@@ -83,11 +71,13 @@ include::modules/nw-ovn-ipsec-enable.adoc[leveloffset=+1]
 include::modules/nw-ovn-ipsec-north-south-enable.adoc[leveloffset=+1]
 
 [role="_additional-resources"]
-[id="additional-resources_{context}"]
+[id="additional-resources_nw-ovn-ipsec_{context}"]
 == Additional resources
 
 * link:https://nmstate.io/devel/yaml_api.html#ipsec-encryption[IPsec Encryption]
 
+* xref:../../installing/install_config/installing-customizing.adoc#installation-special-config-butane-install_installing-customizing[Installing Butane]
+
 // Disabling IPsec encryption for an external IPsec endpoint
 include::modules/nw-ovn-ipsec-north-south-disable.adoc[leveloffset=+1]