Merge pull request #109880 from dfitzmau/OCPBUGS-81437

OCPBUGS-81437: Added br-ex doc to ABI assembly

Author: dfitzmau

_topic_maps/_topic_map.yml

@@ -419,6 +419,8 @@ Topics:
     File: preparing-an-agent-based-installed-cluster-for-mce
   - Name: Installation configuration parameters for the Agent-based Installer
     File: installation-config-parameters-agent
+  - Name: Postinstallation tasks
+    File: agent-based-installer-postinstallation
 - Name: Installing on a single node
   Dir: installing_sno
   Distros: openshift-enterprise,openshift-origin

installing/installing_bare_metal/bare-metal-postinstallation-configuration.adoc

@@ -36,7 +36,7 @@ include::modules/bare-metal-install-new-bmc-ca.adoc[leveloffset=+2]
 include::modules/nw-enabling-a-provisioning-network-after-installation.adoc[leveloffset=+1]
 
 // Creating a manifest object that includes a customized `br-ex` bridge
-include::modules/creating-manifest-file-customized-br-ex-bridge.adoc[leveloffset=+1]
+include::modules/creating-manifest-file-customized-br-ex-bridge-post.adoc[leveloffset=+1]
 
 [role="_additional-resources"]
 .Additional resources

installing/installing_with_agent_based_installer/agent-based-installer-postinstallation.adoc

@@ -0,0 +1,20 @@
+:_mod-docs-content-type: ASSEMBLY
+[id="agent-based-installer-postinstallation"]
+= Postinstallation tasks
+include::_attributes/common-attributes.adoc[]
+:context: agent-based-installer-postinstallation
+
+toc::[]
+
+[role="_abstract"]
+After using the Agent-based Installer to deploy your cluster, you can perform post-installation procedures such as customizing a `br-ex` bridge for nodes in your cluster. Customizing your cluster can help prepare the cluster for specific workloads and deployment requirements.
+
+include::modules/creating-manifest-file-customized-br-ex-bridge-post.adoc[leveloffset=+1]
+ 
+[role="_additional-resources"]
+.Additional resources
+
+* xref:../../networking/ovn_kubernetes_network_provider/converting-to-dual-stack.adoc#nw-dual-stack-convert_converting-to-dual-stack[Converting to a dual-stack cluster network]
+
+* xref:../../installing/installing_bare_metal/bare-metal-expanding-the-cluster.adoc#bare-metal-expanding-the-cluster[Expanding the cluster]
+

installing/installing_with_agent_based_installer/installing-with-agent-based-installer.adoc

@@ -47,8 +47,11 @@ include::modules/installing-ocp-agent-manifest-folder.adoc[leveloffset=+2]
 
 [role="_additional-resources"]
 .Additional resources
+
 * xref:../../machine_configuration/machine-configs-configure.adoc#machine-configs-configure[Using MachineConfig objects to configure nodes]
 
+include::modules/creating-manifest-file-customized-br-ex-bridge.adoc[leveloffset=+2]
+
 // Disk partitioning
 include::modules/installation-user-infra-machines-advanced-disk.adoc[leveloffset=+2]
 

modules/creating-manifest-file-customized-br-ex-bridge-post.adoc

@@ -0,0 +1,130 @@
+// Module included in the following assemblies:
+//
+// * installing/installing_bare_metal/bare-metal-postinstallation-configuration.adoc
+// * installing/installing_with_agent_based_installer/installing-with-agent-based-installer.adoc
+
+:_mod-docs-content-type: PROCEDURE
+[id="creating-manifest-file-customized-br-ex-bridge-post_{context}"]
+= Creating a manifest object that includes a customized br-ex bridge
+
+[role="_abstract"]
+Use the default OVS br-ex bridge configuration for standard environments. This configuration applies when you have a single network interface controller (NIC) and standard OVS settings. 
+
+By default, {product-title} automatically configures the Open vSwitch (OVS) `br-ex` bridge on bare-metal nodes. For advanced networking requirements, you can override this default behavior on bare-metal platforms. To do this, create an `NodeNetworkConfigurationPolicy` (NNCP) custom resource (CR) that includes an NMState configuration file.
+
+The Kubernetes NMState Operator uses the NMState configuration file to create a customized `br-ex` bridge network configuration. This configuration applies to each node in your cluster.
+
+[IMPORTANT]
+====
+After creating the `NodeNetworkConfigurationPolicy` CR, copy content from the installation NMState configuration file into the NNCP CR. An incomplete NNCP CR can result in loss of network connectivity, because the NNCP overrides all existing policies.
+====
+
+Consider using the customized `br-ex` bridge configuration for any of the following tasks:
+
+* You need to modify the `br-ex` bridge after you installed the cluster.
+* You need to modify the maximum transmission unit (MTU) for your cluster.
+* You need to update DNS values.
+* You need to modify attributes for a different bond interface, such as MIImon (Media Independent Interface Monitor), bonding mode, or Quality of Service (QoS).
+* You need to enable Link Layer Discovery Protocol (LLDP) to discover and troubleshoot switch connectivity.
+
+[WARNING]
+====
+The following list of interface names are reserved and you cannot use the names with NMstate configurations:
+
+* `br-ext`
+* `br-int`
+* `br-local`
+* `br-nexthop`
+* `br0`
+* `ext-vxlan`
+* `ext`
+* `genev_sys_*`
+* `int`
+* `k8s-*`
+* `ovn-k8s-*`
+* `patch-br-*`
+* `tun0`
+* `vxlan_sys_*`
+====
+
+.Prerequisites
+* You have installed the Kubernetes NMState Operator.
+* You have identified the specific nodes where you want to apply the policy.
+
+.Procedure
+
+* Create a `NodeNetworkConfigurationPolicy` (NNCP) CR and define a customized `br-ex` bridge network configuration. The `br-ex` NNCP CR must include the OVN-Kubernetes masquerade IP address and subnet of your network. The example NNCP CR includes default values in the `ipv4.address.ip` and `ipv6.address.ip` parameters. You can set the masquerade IP address in the `ipv4.address.ip`, `ipv6.address.ip`, or both parameters.
++
+[IMPORTANT]
+====
+As a post-installation task, you cannot change the primary IP address of the customized `br-ex` bridge. If you want to convert your single-stack cluster network to a dual-stack cluster network, you can add or change a secondary IPv6 address in the NNCP CR, but the existing primary IP address cannot be changed.
+====
++
+[source,yaml]
+----
+apiVersion: nmstate.io/v1
+kind: NodeNetworkConfigurationPolicy
+metadata:
+  name: worker-0-br-ex
+spec:
+  nodeSelector:
+    kubernetes.io/hostname: worker-0
+    desiredState:
+    interfaces:
+    - name: enp2s0
+      type: ethernet
+      state: up
+      ipv4:
+        enabled: false
+      ipv6:
+        enabled: false
+    - name: br-ex
+      type: ovs-bridge
+      state: up
+      ipv4:
+        enabled: false
+        dhcp: false
+      ipv6:
+        enabled: false
+        dhcp: false
+      bridge:
+        options:
+          mcast-snooping-enable: true
+        port:
+        - name: enp2s0
+        - name: br-ex
+    - name: br-ex
+      type: ovs-interface
+      state: up
+      copy-mac-from: enp2s0
+      ipv4:
+        enabled: true
+        dhcp: true
+        auto-route-metric: 48
+        address:
+        - ip: "169.254.0.2"
+          prefix-length: 17
+      ipv6:
+        enabled: true
+        dhcp: true
+        auto-route-metric: 48
+        address:
+        - ip: "fd69::2"
+        prefix-length: 112
+# ...
+----
++
+where:
++
+`metadata.name`:: Specifies the name of the policy.
+`interfaces.name`:: Specifies the name of the interface.
+`interfaces.type`:: Specifies the type of ethernet.
+`interfaces.state`:: Specifies the requested state for the interface after creation.
+`ipv4.enabled`:: Disables IPv4 and IPv6 in this example.
+`port.name`:: Specifies the node NIC to which the bridge is attached.
+`address.ip`:: Shows the default IPv4 and IPv6 IP addresses. Ensure that you set the masquerade IPv4 and IPv6 IP addresses of your network. 
+`auto-route-metric`:: Set the parameter to `48` to ensure the `br-ex` default route always has the highest precedence (lowest metric). This configuration prevents routing conflicts with any other interfaces automatically configured by the `NetworkManager` service.
+
+.Next steps
+
+* Scaling compute nodes to apply the manifest object that includes a customized `br-ex` bridge to each compute node that exists in your cluster. For more information, see "Expanding the cluster" in the _Additional resources_ section.