Refresh cluster network configuration

The configuration for this is unwieldy. As additional fields are
added, this becomes increasingly difficult to maintain. And the
installation procedure is needlessly confusing. So this introduces:

- An updated procedure for creating a manifest
- A table-based presentation of the CNO object
- Ancillary materials as might be necessary

Author: jboxman

installing/installing_aws/installing-aws-network-customizations.adoc

@@ -54,6 +54,8 @@ include::modules/ssh-agent-using.adoc[leveloffset=+1]
 
 include::modules/installation-obtaining-installer.adoc[leveloffset=+1]
 
+include::modules/nw-network-config.adoc[leveloffset=+1]
+
 include::modules/installation-initializing.adoc[leveloffset=+1]
 
 include::modules/installation-configuration-parameters.adoc[leveloffset=+2]
@@ -66,6 +68,7 @@ include::modules/installation-aws-config-yaml.adoc[leveloffset=+2]
 // include::modules/installation-configure-proxy.adoc[leveloffset=+2]
 
 // Network Operator specific configuration
+include::modules/nw-operator-cr.adoc[leveloffset=+1]
 include::modules/nw-modifying-operator-install-config.adoc[leveloffset=+1]
 
 [NOTE]
@@ -75,8 +78,6 @@ For more information on using a Network Load Balancer (NLB) on AWS, see xref:../
 
 include::modules/nw-aws-nlb-new-cluster.adoc[leveloffset=+1]
 
-include::modules/nw-operator-cr.adoc[leveloffset=+1]
-
 include::modules/configuring-hybrid-ovnkubernetes.adoc[leveloffset=+1]
 
 [NOTE]

installing/installing_azure/installing-azure-network-customizations.adoc

@@ -47,6 +47,7 @@ include::modules/installation-azure-config-yaml.adoc[leveloffset=+2]
 // include::modules/installation-configure-proxy.adoc[leveloffset=+2]
 
 // Network Operator specific configuration
+include::modules/nw-network-config.adoc[leveloffset=+1]
 include::modules/nw-modifying-operator-install-config.adoc[leveloffset=+1]
 include::modules/nw-operator-cr.adoc[leveloffset=+1]
 include::modules/configuring-hybrid-ovnkubernetes.adoc[leveloffset=+1]

installing/installing_bare_metal/installing-bare-metal-network-customizations.adoc

@@ -50,7 +50,7 @@ include::modules/installation-bare-metal-config-yaml.adoc[leveloffset=+2]
 include::modules/nw-install-config-parameters.adoc[leveloffset=+2]
 
 // Network Operator specific configuration
-
+include::modules/nw-network-config.adoc[leveloffset=+1]
 include::modules/nw-modifying-operator-install-config.adoc[leveloffset=+1]
 include::modules/nw-operator-cr.adoc[leveloffset=+1]
 

installing/installing_gcp/installing-gcp-network-customizations.adoc

@@ -54,6 +54,7 @@ include::modules/installation-gcp-config-yaml.adoc[leveloffset=+2]
 // include::modules/installation-configure-proxy.adoc[leveloffset=+2]
 
 // Network Operator specific configuration
+include::modules/nw-network-config.adoc[leveloffset=+1]
 include::modules/nw-modifying-operator-install-config.adoc[leveloffset=+1]
 include::modules/nw-operator-cr.adoc[leveloffset=+1]
 

installing/installing_vmc/installing-vmc-network-customizations.adoc

@@ -47,6 +47,7 @@ include::modules/nw-install-config-parameters.adoc[leveloffset=+2]
 include::modules/installation-installer-provisioned-vsphere-config-yaml.adoc[leveloffset=+2]
 
 // begin network customization
+include::modules/nw-network-config.adoc[leveloffset=+1]
 include::modules/nw-modifying-operator-install-config.adoc[leveloffset=+1]
 include::modules/nw-operator-cr.adoc[leveloffset=+1]
 // end network customization

installing/installing_vsphere/installing-vsphere-installer-provisioned-network-customizations.adoc

@@ -49,6 +49,7 @@ include::modules/nw-install-config-parameters.adoc[leveloffset=+2]
 include::modules/installation-installer-provisioned-vsphere-config-yaml.adoc[leveloffset=+2]
 
 // begin network customization
+include::modules/nw-network-config.adoc[leveloffset=+1]
 include::modules/nw-modifying-operator-install-config.adoc[leveloffset=+1]
 include::modules/nw-operator-cr.adoc[leveloffset=+1]
 // end network customization

installing/installing_vsphere/installing-vsphere-network-customizations.adoc

@@ -55,7 +55,7 @@ include::modules/installation-vsphere-config-yaml.adoc[leveloffset=+2]
 include::modules/nw-install-config-parameters.adoc[leveloffset=+2]
 
 // Network Operator specific configuration
-
+include::modules/nw-network-config.adoc[leveloffset=+1]
 include::modules/nw-modifying-operator-install-config.adoc[leveloffset=+1]
 include::modules/nw-operator-cr.adoc[leveloffset=+1]
 

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

@@ -22,15 +22,10 @@ ifeval::["{context}" == "installing-vmc-network-customizations-user-infra"]
 endif::[]
 
 [id="modifying-nwoperator-config-startup_{context}"]
-= Modifying advanced network configuration parameters
+= Specifying advanced network configuration
 
-You can modify the advanced network configuration parameters only before you
-install the cluster. Advanced configuration customization lets you integrate
-your cluster into your existing network environment by specifying an MTU or
-VXLAN port, by allowing customization of
-link:https://kubernetes.io/docs/reference/command-line-tools-reference/kube-proxy/[kube-proxy]
-settings, and by specifying a different `mode` for the `openshiftSDNConfig`
-parameter.
+You can use advanced configuration customization to integrate your cluster into your existing network environment by specifying additional configuration for your cluster network provider.
+You can specify advanced network configuration only before you install the cluster.
 
 [IMPORTANT]
 ====
@@ -50,64 +45,64 @@ endif::ignition-config[]
 +
 [source,terminal]
 ----
-$ ./openshift-install create manifests --dir=<installation_directory> <1>
+$ ./openshift-install create manifests --dir=<installation_directory>
 ----
-<1> For `<installation_directory>`, specify the name of the directory that
-contains the `install-config.yaml` file for your cluster.
++
+--
+where:
+
+`<installation_directory>`:: Specifies the name of the directory that contains the `install-config.yaml` file for your cluster.
+--
 
-. Create a file that is named `cluster-network-03-config.yml` in the
-`<installation_directory>/manifests/` directory:
+. Create a stub manifest file for the advanced network configuration that is named `cluster-network-03-config.yml` in the `<installation_directory>/manifests/` directory:
 +
 [source,terminal]
 ----
-$ touch <installation_directory>/manifests/cluster-network-03-config.yml <1>
+$ cat <<EOF > <installation_directory>/manifests/cluster-network-03-config.yml
+apiVersion: operator.openshift.io/v1
+kind: Network
+metadata:
+  name: cluster
+spec:
+EOF
 ----
-<1> For `<installation_directory>`, specify the directory name that contains the
-`manifests/` directory for your cluster.
 +
-After creating the file, several network configuration files are in the
-`manifests/` directory, as shown:
-+
-[source,terminal]
-----
-$ ls <installation_directory>/manifests/cluster-network-*
-----
+--
+where:
+
+`<installation_directory>`:: Specifies the directory name that contains the
+`manifests/` directory for your cluster.
+--
+
+. Open the `cluster-network-03-config.yml` file in an editor and specify the advanced network configuration for your cluster, such as in the following examples:
 +
-.Example output
-[source,terminal]
+--
+.Specify a different VXLAN port for the OpenShift SDN network provider
+[source,yaml]
 ----
-cluster-network-01-crd.yml
-cluster-network-02-config.yml
-cluster-network-03-config.yml
+apiVersion: operator.openshift.io/v1
+kind: Network
+metadata:
+  name: cluster
+spec:
+  defaultNetwork:
+    openshiftSDNConfig:
+      vxlanPort: 4800
 ----
 
-. Open the `cluster-network-03-config.yml` file in an editor and enter a custom resource (CR) that
-describes the Operator configuration you want:
-+
+.Enable IPsec for the OVN-Kubernetes network provider
 [source,yaml]
 ----
 apiVersion: operator.openshift.io/v1
 kind: Network
 metadata:
   name: cluster
-spec: <1>
-  clusterNetwork:
-  - cidr: 10.128.0.0/14
-    hostPrefix: 23
-  serviceNetwork:
-  - 172.30.0.0/16
+spec:
   defaultNetwork:
-    type: OpenShiftSDN
-    openshiftSDNConfig:
-      mode: NetworkPolicy
-      mtu: 1450
-      vxlanPort: 4789
+    ovnKubernetesConfig:
+      ipsecConfig: {}
 ----
-<1> The parameters for the `spec` parameter are only an example. Specify your
-configuration for the Cluster Network Operator in the CR.
-+
-The CNO provides default values for the parameters in the CR, so you must
-specify only the parameters that you want to change.
+--
 
 . Save the `cluster-network-03-config.yml` file and quit the text editor.
 . Optional: Back up the `manifests/cluster-network-03-config.yml` file. The

modules/nw-network-config.adoc

@@ -0,0 +1,30 @@
+// TODO -  possibly delete this file
+// Or does it add actual value?
+
+// Module included in the following assemblies:
+//
+// * networking/cluster-network-operator.adoc
+// * installing/installing_aws/installing-aws-network-customizations.adoc
+// * installing/installing_azure/installing-azure-network-customizations.adoc
+// * installing/installing_bare_metal/installing-bare-metal-network-customizations.adoc
+// * installing/installing_vsphere/installing-vsphere-network-customizations.adoc
+// * installing/installing_vsphere/installing-vsphere-installer-provisioned-network-customizations.adoc
+// * installing/installing_gcp/installing-gcp-network-customizations.adoc
+
+[id="nw-network-config_{context}"]
+= Network configuration phases
+
+When specifying a cluster configuration prior to installation, there are several phases in the installation procedures when you can modify the network configuration:
+
+Phase 1:: After entering the `openshift-install create install-config` command. In the `install-config.yaml` file, you can customize the following network-related fields:
++
+* `networking.networkType`
+* `networking.clusterNetwork`
+* `networking.serviceNetwork`
+* `networking.machineNetwork`
++
+For more information on these fields, refer to "Installation configuration parameters".
+
+Phase 2:: After entering the `openshift-install create manifests` command. If you must specify advanced network configuration, during this phase you can define a customized Cluster Network Operator manifest with only the fields you want to modify.
+
+You cannot override the values specified in phase 1 in the `install-config.yaml` file during phase 2. However, you can further customize the cluster network provider during phase 2.