Add OpenShift SDN configuration content

- OSDOCS-177
2026-02-05 12:46:18 +01:00 · 2019-03-25 15:12:55 -04:00
parent 71fe679699
commit a5b436bbfb
9 changed files with 479 additions and 5 deletions
--- a/_topic_map.yml
+++ b/_topic_map.yml
@@ -77,6 +77,8 @@ Topics:
    File: installing-aws-default
  - Name: Installing a cluster on AWS with customizations
    File: installing-aws-customizations
+  - Name: Installing a cluster on AWS with network customizations
+    File: installing-aws-network-customizations
  - Name: Uninstalling a cluster on AWS
    File: uninstalling-cluster-aws
 - Name: Installing on bare metal
@@ -312,6 +314,7 @@ Topics:
  File: managing_multinetworking
 - Name: Using multicast
  File: using-multicast
+  Distros: openshift-origin, openshift-enterprise
 - Name: Understanding the DNS Operator in OpenShift Container Platform
  File: dns-operator
 - Name: Ingress
@@ -321,6 +324,9 @@ Topics:
    File: configuring-ingress-operator
  - Name: Ingress controller configuration
    File: ingress-controller-configuration
+- Name: Configuring the network
+  File: configuring-network-operator
+  Distros: openshift-enterprise,openshift-origin
 ---
 Name: Registry
 Dir: registry
--- a/installing/installing_aws/installing-aws-network-customizations.adoc
+++ b/installing/installing_aws/installing-aws-network-customizations.adoc
@@ -0,0 +1,49 @@
+[id="installing-aws-network-customizations"]
+= Installing a cluster on AWS with network customizations
+include::modules/common-attributes.adoc[]
+:context: installing-aws-network-customizations
+
+toc::[]
+
+In {product-title} version {product-version}, you can install a cluster on
+Amazon Web Services (AWS) with customized network configuration options. By
+customizing your network configuration, your cluster can coexist with existing
+IP address allocations in your environment and integrate with existing MTU and
+VXLAN configurations.
+
+Most network configuration parameters set at installation cannot be changed
+later.
+
+.Prerequisites
+
+* xref:../../installing/installing_aws/installing-aws-account.adoc[Configure an AWS account]
+to host the cluster.
+
+// TODO
+// Concept that describes networking
+
+include::modules/installation-overview.adoc[leveloffset=+1]
+
+include::modules/installation-clouds.adoc[leveloffset=+1]
+
+include::modules/installation-provide-credentials.adoc[leveloffset=+1]
+
+include::modules/installation-obtaining-installer.adoc[leveloffset=+1]
+
+include::modules/installation-initializing.adoc[leveloffset=+1]
+
+include::modules/installation-configuration-parameters.adoc[leveloffset=+2]
+
+include::modules/nw-install-config-parameters.adoc[leveloffset=+2]
+
+include::modules/installation-aws-config-yaml.adoc[leveloffset=+2]
+
+// Network Operator specific configuration
+include::modules/nw-modifying-operator-install-config.adoc[leveloffset=+1]
+include::modules/nw-operator-cr.adoc[leveloffset=+1]
+
+include::modules/installation-launching-installer.adoc[leveloffset=+1]
+
+include::modules/cli-install.adoc[leveloffset=+1]
+
+include::modules/cli-logging-in-kubeadmin.adoc[leveloffset=+1]
--- a/modules/installation-aws-config-yaml.adoc
+++ b/modules/installation-aws-config-yaml.adoc
@@ -2,6 +2,13 @@
 //
 // * installing/installing_aws/installing-aws-customizations.adoc

+ifeval::["{context}" == "installing-aws-network-customizations"]
+:with-networking:
+endif::[]
+ifeval::["{context}" != "installing-aws-network-customizations"]
+:without-networking:
+endif::[]
+
 [id="installation-aws-config-yaml-{context}"]
 = Sample customized `install-config.yaml` file for AWS

@@ -17,6 +24,7 @@ This sample YAML file is provided for reference only. You must obtain your

 [source,yaml]
 ----
+ifdef::without-networking[]
 apiVersion: v1beta3
 baseDomain: example.com <1>
 controlPlane: <2>
@@ -47,12 +55,13 @@ compute: <2>
 metadata:
  name: test-cluster <1>
 networking:
-  clusterNetworks:
+  clusterNetwork:
  - cidr: 10.128.0.0/14
-    hostSubnetLength: 9
+    hostPrefix: 23
  machineCIDR: 10.0.0.0/16
-  serviceCIDR: 172.30.0.0/16
-  type: OpenShiftSDN
+  serviceNetwork:
+  - 172.30.0.0/16
+  typeType: OpenShiftSDN
 platform:
  aws:
    region: us-west-2 <1>
@@ -61,6 +70,51 @@ platform:
      costCenter: 7536
 pullSecret: '{"auths": ...}' <1>
 sshKey: ssh-ed25519 AAAA... <3>
+endif::[]
+
+ifdef::with-networking[]
+apiVersion: v1beta3
+baseDomain: example.com <1>
+controlPlane: <2>
+- name: master
+  platform:
+    aws:
+      zones:
+      - us-west-2a
+      - us-west-2b
+      type: m5.xlarge
+  replicas: 3
+compute: <2>
+- name: worker
+  platform:
+    aws:
+      rootVolume:
+        iops: 4000
+        size: 500
+        type: io1 <4>
+      type: c5.9xlarge
+      zones:
+      - us-west-2c
+  replicas: 5
+metadata:
+  name: test-cluster <1>
+networking: <2>
+  clusterNetwork:
+  - cidr: 10.128.0.0/14
+    hostPrefix: 23
+  machineCIDR: 10.0.0.0/16
+  serviceNetwork:
+  - 172.30.0.0/16
+  typeType: OpenShiftSDN
+platform:
+  aws:
+    region: us-west-2 <1>
+    userTags:
+      adminContact: jdoe
+      costCenter: 7536
+pullSecret: '{"auths": ...}' <1>
+sshKey: ssh-ed25519 AAAA... <3>
+endif::[]
 ----
 <1> Required. The installation program prompts you for this value.
 <2> If you do not provide these parameters and values, the installation program
--- a/modules/installation-launching-installer.adoc
+++ b/modules/installation-launching-installer.adoc
@@ -28,7 +28,10 @@ You can run the installation program only once, during initial installation.
 $ ./openshift-install create cluster --dir=<directory> <1>
 ----
 ifeval::["{context}" == "install-customizations-cloud"]
-Specify the location of your customized `./install-config.yaml` file.
+<1> Specify the location of your customized `./install-config.yaml` file.
+endif::[]
+ifeval::["{context}" == "installing-aws-network-customizations"]
+<1> Specify the location of your customized `./install-config.yaml` file.
 endif::[]
 ifeval::["{context}" == "installing-aws-default"]
 <1> Specify the directory name to store the files that the installation program
--- a/modules/nw-install-config-parameters.adoc
+++ b/modules/nw-install-config-parameters.adoc
@@ -0,0 +1,52 @@
+// Module included in the following assemblies:
+//
+// * installing/installing_aws/installing-aws-network-customizations.adoc
+
+[id="network-customization-config-yaml-{context}"]
+= Network configuration parameters
+
+You can modify your cluster network configuration parameters in the
+`install-cluster.yaml` configuration file. The following table describes the
+parameters.
+
+[NOTE]
+====
+You cannot modify these parameters after installation.
+====
+
+.Required network parameters
+[cols=".^2,.^5,.^3a",options="header"]
+|====
+|Parameter|Description|Values
+
+|`networking.networkType`
+|The network plug-in to deploy. `OpenShiftSDN` is the only plug-in
+supported in {product-title} {product-version}.
+|`OpenShiftSDN`
+
+|`networking.clusterNetwork.cidr`
+|A block of IP addresses from which Pod IPs are allocated. The `OpenShiftSDN`
+network plug-in supports multiple cluster networks. The address blocks for
+multiple cluster networks must not overlap. Select address pools large enough to
+fit your anticipated workload.
+|An IP address allocation in CIDR format. The default value is `10.128.0.0/14`.
+
+|`networking.clusterNetwork.hostPrefix`
+|The subnet prefix length to assign to each individual node. For example, if
+`hostPrefix` is set to `23`, then each node is assigned a `/23` subnet out of
+the given `cidr`, allowing for 510 (2^(32 - 23) - 2) Pod IP addresses.
+|A subnet prefix. The default value is `23`.
+
+|`networking.serviceNetwork`
+|A block of IP addresses for services. `OpenShiftSDN` allows only one
+`serviceNetwork` block. The address block must not overlap with any other
+network block.
+|An IP address allocation in CIDR format. The default value is `172.30.0.0/16`.
+
+|`networking.machineCIDR`
+|A block of IP addresses used by the {product-title} installation program while
+installing the cluster. The address block must not overlap with any other
+network block.
+|An IP address allocation in CIDR format. The default value is `10.0.0.0/16`.
+
+|====
--- a/modules/nw-modify-config.adoc
+++ b/modules/nw-modify-config.adoc
@@ -0,0 +1,78 @@
+// Module included in the following assemblies:
+// * networking/configuring-network-operator.adoc
+
+[id="network-modifying-config-{context}"]
+= Modifying network configuration in a running cluster
+
+The Network Operator reconciles the state of the cluster against a desired
+configuration.
+
+// "You can also create new additionalNetworks"
+You can modify only `kubeProxy` configuration parameters in a running cluster.
+
+.Prerequisites
+
+* Install the OpenShift Command-line Interface (CLI), commonly known as `oc`.
+* Log in to a running cluster with the `cluster-admin` role.
+
+.Procedure
+
+. Use the following command to edit the `Network.operator.openshift.io` Custom
+Resource (CR):
+
+----
+$ oc edit network.operator.openshift.io cluster
+----
+
+The following example output shows a `Network.operator.openshift.io` CR that is
+configured with default values.
+
+[source,yaml]
+----
+# Please edit the object below. Lines beginning with a '#' will be ignored,
+# and an empty file will abort the edit. If an error occurs while saving this file will be
+# reopened with the relevant failures.
+#
+apiVersion: operator.openshift.io/v1
+kind: Network
+metadata:
+  name: cluster
+spec:
+  clusterNetwork:
+  - cidr: 10.128.0.0/14
+    hostPrefix: 23
+  defaultNetwork:
+    type: OpenShiftSDN
+  serviceNetwork:
+  - 172.30.0.0/16
+status: {}
+----
+
+. Add the following code to the `spec` field in the
+`Network.operator.openshift.io` CR:
+
+[source,yaml]
+----
+spec:
+  deployKubeProxy: false
+  kubeProxyConfig:
+   iptablesSyncPeriod: 30s
+   bindAddress: 0.0.0.0
+   proxyArguments:
+   - "iptables-min-sync-period": ["30s"]
+----
+
+. Save the file and exit the text editor.
+
+The syntax is validated by the `oc` command when you save the file and exit the
+editor. If your modifications contain a syntax error, the editor opens the file
+and displays an error message.
+
+. Run the following command to confirm that the Network Operator accepted the
+updated configuration:
+
+----
+$ oc get clusteroperator network
+NAME      VERSION     AVAILABLE   PROGRESSING   FAILING   SINCE
+network   4.0.0-0.9   True        False         False     1m
+----
--- a/modules/nw-modifying-operator-install-config.adoc
+++ b/modules/nw-modifying-operator-install-config.adoc
@@ -0,0 +1,81 @@
+// Module included in the following assemblies:
+//
+// * installing/installing_aws/installing-aws-network-customizations.adoc
+
+[id="modifying-nwoperator-config-startup-{context}"]
+= Modifying advanced network configuration parameters
+
+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.
+
+[IMPORTANT]
+====
+Modifying the {product-title} manifest files directly is not supported.
+====
+
+.Prerequisites
+
+* Generate the `install-config.yaml` file and complete any modifications to it.
+
+.Procedure
+
+. Use the following command to create manifests:
+
+----
+$ openshift-install create manifests --dir=<installation_directory> <1>
+----
+<1> Specify the directory name 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`:
+
+----
+$ touch <installation_directory>/manifests/cluster-network-03-config.yml <1>
+----
+<1> Specify the directory name that contains the `manifests/` directory for
+your cluster.
+
+After creating the file, three network configuration files are in the
+`manifests/` directory, as shown:
+
+----
+$ ls <installation_directory>/manifests/cluster-network-*
+cluster-network-01-crd.yml
+cluster-network-02-config.yml
+cluster-network-03-config.yml
+----
+
+. Open the `cluster-network-03-config.yml` file in an editor and enter a CR that
+describes the Operator configuration you want:
+
+[source,yaml]
+----
+apiVersion: operator.openshift.io/v1
+kind: Network
+metadata:
+  name: default
+spec: <1>
+  defaultNetwork:
+    type: OpenShiftSDN
+    openshiftSDNConfig:
+      mode: NetworkPolicy
+      mtu: 1450
+      vxlanPort: 4789
+----
+<1> The parameters for the `spec` field are only an example. Specify your
+configuration for the Network Operator in the CR.
+
+The Network Operator provides default values for the parameters in the CR, so
+you need to specify only the parameters that you want to change in the
+`Network.operator.openshift.io` CR.
+
+. Save the `cluster-network-03-config.yml` file and quit the text editor.
+. Optionally, back up the `manifests/cluster-network-03-config.yml` file. The
+installation program deletes the `manifests/` directory when creating the
+cluster.
--- a/modules/nw-operator-cr.adoc
+++ b/modules/nw-operator-cr.adoc
@@ -0,0 +1,130 @@
+// Module included in the following assemblies:
+//
+// * networking/configuring-network-operator.adoc
+// * installing/installing_aws/installing-aws-network-customizations.adoc
+
+ifeval::["{context}" == "installing-aws-network-customizations"]
+:install:
+endif::[]
+ifeval::["{context}" != "installing-aws-network-customizations"]
+:not-install:
+endif::[]
+
+// Extract parameter descriptions that may have a different ordinal
+// position depending on the module context.
+
+:kube-proxy: pass:q[The parameters in this section specify the `kube-proxy` \
+configuration. If you do not specify the parameter values, the \
+Network Operator applies the displayed default parameter values.]
+
+:kube-proxy-ip: pass:q[The IP address for `kube-proxy` to serve on. \
+The default value is `0.0.0.0`.]
+
+:kube-proxy-refresh: pass:q[The refresh period for `iptables` rules. The default \
+value is `30s`. Valid suffixes include `s`, `m`, and `h` and are described in \
+the link:https://golang.org/pkg/time/#ParseDuration[Go time package] \
+documentation.]
+
+:iptables-min-sync-period: pass:q[The minimum duration before refreshing `iptables` \
+rules. This parameter ensures that the refresh does not happen too frequently. \
+Valid suffixes include `s`, `m`, and `h` and are described in the \
+link:https://golang.org/pkg/time/#ParseDuration[Go time package]]
+
+// Begin module
+
+[id="network-networkoperator-default-cr-{context}"]
+= Network Operator Custom Resource (CR)
+
+The network configuration in an `Network.operator.openshift.io` Custom Resource
+(CR) stores the configuration settings for the Network Operator.
+
+The following CR displays the default configuration for the Network Operator and
+explains both the parameters you can configure and valid parameter values:
+
+.Network Operator CR
+[source,yaml]
+ifdef::install[]
+----
+apiVersion: operator.openshift.io/v1
+kind: Network
+spec:
+  clusterNetwork: <1>
+  - cidr: 10.128.0.0/14
+    hostPrefix: 23
+  serviceNetwork: 172.30.0.0/16 <1>
+  defaultNetwork:
+    type: OpenShiftSDN <1>
+    openshiftSDNConfig: <2>
+      mode: NetworkPolicy <3>
+      mtu: 1450 <4>
+      vxlanPort: 4789 <5>
+  kubeProxyConfig: <6>
+    bindAddress: 0.0.0.0 <7>
+    iptablesSyncPeriod: 30s <8>
+    proxyArguments:
+      iptables-min-sync-period: <9>
+      - 30s
+----
+<1> Specified in the `install-config.yaml` file.
+
+<2> Specify only if you want to override part of the {product-title} SDN
+configuration.
+
+<3> Configures the isolation mode for `OpenShiftSDN`. The allowed values are
+`Multitenant`, `Subnet`, or `NetworkPolicy`. The default value is
+`NetworkPolicy`.
+
+<4> MTU for the VXLAN overlay network. This value is normally configured
+automatically, but if the nodes in your cluster do not all use the same MTU,
+then you must set this explicitly to 50 less than the smallest node MTU value.
+
+<5> The port to use for all VXLAN packets. The default value is 4789. If you are
+running in a virtualized environment with existing nodes that are part of
+another VXLAN network then you may need to change this.
+
+<6> {kube-proxy}
+<7> {kube-proxy-ip}
+<8> {kube-proxy-refresh}
+<9> {iptables-min-sync-period}
+endif::install[]
+
+ifdef::not-install[]
+----
+apiVersion: operator.openshift.io/v1
+kind: Network
+spec:
+  clusterNetwork:
+  - cidr: 10.128.0.0/14 <1>
+    hostPrefix: 23 <1>
+  serviceNetwork: 172.30.0.0/16 <1>
+  defaultNetwork:
+    type: OpenShiftSDN <1>
+    openshiftSDNConfig: <2>
+      mode: NetworkPolicy <1>
+      mtu: 1450 <3>
+      vxlanPort: 4789 <4>
+  kubeProxyConfig: <5>
+    bindAddress: 0.0.0.0 <6>
+    iptablesSyncPeriod: 30s <7>
+    proxyArguments:
+      iptables-min-sync-period: <8>
+      - 30s
+----
+<1> Specified when the cluster is installed. It cannot be modified.
+
+<2> Specify only if you want to override part of the {product-title} SDN
+configuration.
+
+<3> MTU for the VXLAN overlay network. This value is normally configured
+automatically, but if the nodes in your cluster do not all use the same MTU,
+then you must set this value to 50 less than the smallest node MTU value.
+
+<4> The port to use for all VXLAN packets. The default value is 4789. If your
+network is in a virtualized environment with existing nodes that are part of
+another VXLAN network then you might need to change this.
+
+<5> {kube-proxy}
+<6> {kube-proxy-ip}
+<7> {kube-proxy-refresh}
+<8> {iptables-min-sync-period}
+endif::not-install[]
--- a/networking/configuring-network-operator.adoc
+++ b/networking/configuring-network-operator.adoc
@@ -0,0 +1,21 @@
+[id="configuring-network-operator"]
+= Configuring networking
+include::modules/common-attributes.adoc[]
+:context: configuring-network-operator
+
+toc::[]
+
+The Network Operator installs and upgrades the networking components on an
+{product-title} cluster. If you want to customize the network configuration, you
+must modify the settings before installing the cluster.
+
+[IMPORTANT]
+====
+You cannot modify your network settings after you install the cluster.
+====
+
+//Advanced network configuration defaults in operator config
+include::modules/nw-operator-cr.adoc[leveloffset=+1]
+
+//Modifying network configuration in a running cluster
+include::modules/nw-modify-config.adoc[leveloffset=+1]