Merge pull request #69982 from jab-rh/OSDOCS-6863

OSDOCS-6863: IPsec N/S GA

Author: jab-rh

modules/nw-modifying-operator-install-config.adoc

@@ -68,7 +68,8 @@ metadata:
 spec:
   defaultNetwork:
     ovnKubernetesConfig:
-      ipsecConfig: {}
+      ipsecConfig:
+        mode: Full
 ----
 --
 

modules/nw-operator-cr.adoc

@@ -248,10 +248,10 @@ endif::operator[]
 |`object`
 |
 ifndef::operator[]
-Specify an empty object to enable IPsec encryption.
+Specify a configuration object for customizing the IPsec configuration.
 endif::operator[]
 ifdef::operator[]
-If the field is present, IPsec is enabled for the cluster.
+An object describing the IPsec mode for the cluster.
 endif::operator[]
 
 |`policyAuditConfig`
@@ -335,6 +335,31 @@ If you set this field to `true`, you do not receive the performance benefits of
 
 |====
 
+[id="nw-operator-cr-ipsec_{context}"]
+.`ipsecConfig` object
+[cols=".^2,.^2,.^6a",options="header"]
+|====
+|Field|Type|Description
+
+|`mode`
+|`string`
+a|Specifies the behavior of the IPsec implementation. Must be one of the following values:
+
+--
+- `Disabled`: IPsec is not enabled on cluster nodes.
+- `External`: IPsec is enabled for network traffic with external hosts.
+- `Full`: IPsec is enabled for pod traffic and network traffic with external hosts.
+--
+
+|====
+
+
+ifdef::operator[]
+[NOTE]
+====
+You can only change the configuration for your cluster network plugin during cluster installation, except for the `gatewayConfig` field that can be changed at runtime as a postinstallation activity.
+====
+endif::operator[]
 
 .Example OVN-Kubernetes configuration with IPSec enabled
 [source,yaml]
@@ -344,7 +369,8 @@ defaultNetwork:
   ovnKubernetesConfig:
     mtu: 1400
     genevePort: 6081
-    ipsecConfig: {}
+      ipsecConfig:
+        mode: Full
 ----
 [IMPORTANT]
 ====

modules/nw-ovn-ipsec-certificates.adoc

@@ -1,6 +1,6 @@
 // Module included in the following assemblies:
 //
-// * networking/ovn_kubernetes_network_provider/about-ipsec-ovn.adoc
+// * networking/ovn_kubernetes_network_provider/configuring-ipsec-ovn.adoc
 
 :_mod-docs-content-type: CONCEPT
 [id="nw-ovn-ipsec-certificates_{context}"]

modules/nw-ovn-ipsec-disable.adoc

@@ -6,12 +6,7 @@
 [id="nw-ovn-ipsec-disable_{context}"]
 = Disabling IPsec encryption
 
-As a cluster administrator, you can disable IPsec encryption only if you enabled IPsec after cluster installation.
-
-[NOTE]
-====
-If you enabled IPsec when you installed your cluster, you cannot disable IPsec with this procedure.
-====
+As a cluster administrator, you can disable IPsec encryption.
 
 .Prerequisites
 
@@ -24,8 +19,14 @@ If you enabled IPsec when you installed your cluster, you cannot disable IPsec w
 +
 [source,terminal]
 ----
-$ oc patch networks.operator.openshift.io/cluster --type=json \
-  -p='[{"op":"remove", "path":"/spec/defaultNetwork/ovnKubernetesConfig/ipsecConfig"}]'
+$ oc patch networks.operator.openshift.io cluster --type=merge \
+-p '{
+  "spec":{
+    "defaultNetwork":{
+      "ovnKubernetesConfig":{
+        "ipsecConfig":{
+          "mode":"Disabled"
+        }}}}}'
 ----
 
 . Optional: You can increase the size of your cluster MTU by `46` bytes because there is no longer any overhead from the IPsec ESP header in IP packets.

modules/nw-ovn-ipsec-enable.adoc

@@ -4,9 +4,16 @@
 
 :_mod-docs-content-type: PROCEDURE
 [id="nw-ovn-ipsec-enable_{context}"]
-= Enabling pod-to-pod IPsec encryption
+= Enabling IPsec encryption
 
-As a cluster administrator, you can enable pod-to-pod IPsec encryption after cluster installation.
+As a cluster administrator, you can enable pod-to-pod IPsec encryption and IPsec encryption between the cluster and external IPsec endpoints.
+
+You can configure IPsec in either of the following modes:
+
+- `Full`: Encryption for pod-to-pod and external traffic
+- `External`: Encryption for external traffic
+
+If you need to configure encryption for external traffic in addition to pod-to-pod traffic, you must also complete the "Configuring IPsec encryption for external traffic" procedure.
 
 .Prerequisites
 
@@ -16,10 +23,24 @@ As a cluster administrator, you can enable pod-to-pod IPsec encryption after clu
 
 .Procedure
 
-* To enable IPsec encryption, enter the following command:
+. To enable IPsec encryption, enter the following command:
 +
 [source,terminal]
 ----
 $ oc patch networks.operator.openshift.io cluster --type=merge \
--p '{"spec":{"defaultNetwork":{"ovnKubernetesConfig":{"ipsecConfig":{ }}}}}'
+-p '{
+  "spec":{
+    "defaultNetwork":{
+      "ovnKubernetesConfig":{
+        "ipsecConfig":{
+          "mode":<mode>
+        }}}}}'
 ----
++
+where:
++
+--
+`mode`:: Specify `External` to encrypt only traffic to external hosts or specify `Full` to encrypt pod to pod traffic and optionally traffic to external hosts. By default, IPsec is disabled.
+--
+
+. Optional: If you need to encrypt traffic to external hosts, complete the "Configuring IPsec encryption for external traffic" procedure.

modules/nw-ovn-ipsec-encryption.adoc

@@ -1,6 +1,6 @@
 // Module included in the following assemblies:
 //
-// * networking/ovn_kubernetes_network_provider/about-ipsec-ovn.adoc
+// * networking/ovn_kubernetes_network_provider/configuring-ipsec-ovn.adoc
 
 :_mod-docs-content-type: CONCEPT
 [id="nw-ovn-ipsec-encryption_{context}"]

modules/nw-ovn-ipsec-external.adoc

@@ -0,0 +1,33 @@
+// Module included in the following assemblies:
+//
+// * networking/ovn_kubernetes_network_provider/configuring-ipsec-ovn.adoc
+
+:_mod-docs-content-type: CONCEPT
+[id="nw-ovn-ipsec-external_{context}"]
+= IPsec encryption for external traffic
+
+{product-title} supports IPsec encryption for traffic to external hosts with TLS certificates that you must supply.
+
+[id="supported-platforms_{context}"]
+== Supported platforms
+
+This feature is supported on the following platforms:
+
+- Bare metal
+- {gcp-first}
+- {rh-openstack-first}
+- {vmw-full}
+
+[IMPORTANT]
+====
+If you have {op-system-base-full} worker nodes, these do not support IPsec encryption for external traffic.
+====
+
+If your cluster uses hosted control planes for Red Hat {product-title}, configuring IPsec for encrypting traffic to external hosts is not supported.
+
+[id="ipsec-external-limitations_{context}"]
+== Limitations
+
+Ensure that the following prohibitions are observed:
+
+* Certificate common names (CN) in the provided certificate bundle must not begin with the `ovs_` prefix, because this naming can conflict with pod-to-pod IPsec CN names in the Network Security Services (NSS) database of each node.

modules/nw-ovn-ipsec-north-south-disable.adoc

@@ -0,0 +1,50 @@
+// Module included in the following assemblies:
+//
+// * networking/ovn_kubernetes_network_provider/configuring-ipsec-ovn.adoc
+
+:_mod-docs-content-type: PROCEDURE
+[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.
+
+.Prerequisites
+
+* Install the {oc-first}.
+* You are logged in to the cluster as a user with `cluster-admin` privileges.
+* You enabled IPsec in either `Full` or `External` mode on your cluster.
+
+.Procedure
+
+. Create a file named `remove-ipsec-tunnel.yaml` with the following YAML:
++
+[source,yaml]
+----
+kind: NodeNetworkConfigurationPolicy
+apiVersion: nmstate.io/v1
+metadata:
+  name: <name>
+spec:
+  nodeSelector:
+    kubernetes.io/hostname: <node_name>
+  desiredState:
+    interfaces:
+    - name: <tunnel_name>
+      type: ipsec
+      state: absent
+----
++
+--
+where:
+
+`name`:: Specifies a name for the node network configuration policy.
+`node_name`:: Specifies the name of the node where the IPsec tunnel that you want to remove exists.
+`tunnel_name`:: Specifies the interface name for the existing IPsec tunnel.
+--
+
+. To remove the IPsec tunnel, enter the following command:
++
+[source,terminal]
+----
+$ oc apply -f remove-ipsec-tunnel.yaml
+----