From a5b436bbfb85015700a967931ab22ea2a96e6e96 Mon Sep 17 00:00:00 2001 From: Jason Boxman Date: Mon, 25 Mar 2019 15:12:55 -0400 Subject: [PATCH] Add OpenShift SDN configuration content - OSDOCS-177 --- _topic_map.yml | 6 + ...installing-aws-network-customizations.adoc | 49 +++++++ modules/installation-aws-config-yaml.adoc | 62 ++++++++- modules/installation-launching-installer.adoc | 5 +- modules/nw-install-config-parameters.adoc | 52 +++++++ modules/nw-modify-config.adoc | 78 +++++++++++ .../nw-modifying-operator-install-config.adoc | 81 +++++++++++ modules/nw-operator-cr.adoc | 130 ++++++++++++++++++ networking/configuring-network-operator.adoc | 21 +++ 9 files changed, 479 insertions(+), 5 deletions(-) create mode 100644 installing/installing_aws/installing-aws-network-customizations.adoc create mode 100644 modules/nw-install-config-parameters.adoc create mode 100644 modules/nw-modify-config.adoc create mode 100644 modules/nw-modifying-operator-install-config.adoc create mode 100644 modules/nw-operator-cr.adoc create mode 100644 networking/configuring-network-operator.adoc diff --git a/_topic_map.yml b/_topic_map.yml index 86a8af97c9..b98987ca34 100644 --- 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 diff --git a/installing/installing_aws/installing-aws-network-customizations.adoc b/installing/installing_aws/installing-aws-network-customizations.adoc new file mode 100644 index 0000000000..1e188a2df5 --- /dev/null +++ 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] diff --git a/modules/installation-aws-config-yaml.adoc b/modules/installation-aws-config-yaml.adoc index c5fd8eb7dd..82e35694ae 100644 --- 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 diff --git a/modules/installation-launching-installer.adoc b/modules/installation-launching-installer.adoc index d7ba3d0ec3..d62a179d65 100644 --- 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= <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 diff --git a/modules/nw-install-config-parameters.adoc b/modules/nw-install-config-parameters.adoc new file mode 100644 index 0000000000..d7d2893e24 --- /dev/null +++ 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`. + +|==== diff --git a/modules/nw-modify-config.adoc b/modules/nw-modify-config.adoc new file mode 100644 index 0000000000..29be9af32a --- /dev/null +++ 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 +---- diff --git a/modules/nw-modifying-operator-install-config.adoc b/modules/nw-modifying-operator-install-config.adoc new file mode 100644 index 0000000000..9d3164571a --- /dev/null +++ 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= <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 +`/manifests/ directory`: ++ +---- +$ touch /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 /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. diff --git a/modules/nw-operator-cr.adoc b/modules/nw-operator-cr.adoc new file mode 100644 index 0000000000..640b16ca61 --- /dev/null +++ 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[] diff --git a/networking/configuring-network-operator.adoc b/networking/configuring-network-operator.adoc new file mode 100644 index 0000000000..07f3d3e95d --- /dev/null +++ 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]