Merge pull request #32632 from maxwelldb/osp-provider-networks-osdocs1877

[ShiftStack: OSDOCS-1877] Add provider network installation docs

Author: maxwelldb

images/openshift-on-openstack-provider-network.png

@@ -13,7 +13,6 @@ In {product-title} version {product-version}, you can install a customized clust
 * You reviewed details about the xref:../../architecture/architecture-installation.adoc#architecture-installation[{product-title} installation and update] processes.
 * You read the documentation on xref:../../installing/installing-preparing.adoc#installing-preparing[selecting a cluster installation method and preparing it for users].
 * You verified that {product-title} {product-version} is compatible with your {rh-openstack} version by using the xref:../../architecture/architecture-installation.adoc#supported-platforms-for-openshift-clusters_architecture-installation[Supported platforms for OpenShift clusters] section. You can also compare platform support across different versions by viewing the link:https://access.redhat.com/articles/4679401[{product-title} on {rh-openstack} support matrix].
-* Your network configuration does not rely on a provider network. Provider networks are not supported.
 * You have a storage service installed in {rh-openstack}, such as block storage (Cinder) or object storage (Swift). Object storage is the recommended storage technology for {product-title} registry cluster deployment. For more information, see xref:../../scalability_and_performance/optimizing-storage.adoc#optimizing-storage[Optimizing storage].
 * You have the metadata service enabled in {rh-openstack}.
 
@@ -30,6 +29,17 @@ include::modules/installation-configure-proxy.adoc[leveloffset=+2]
 include::modules/installation-configuration-parameters.adoc[leveloffset=+1]
 include::modules/installation-osp-custom-subnet.adoc[leveloffset=+2]
 include::modules/installation-osp-deploying-bare-metal-machines.adoc[leveloffset=+2]
+include::modules/installation-osp-provider-networks.adoc[leveloffset=+2]
+include::modules/installation-osp-provider-network-preparation.adoc[leveloffset=+3]
+include::modules/installation-osp-deploying-provider-networks-installer.adoc[leveloffset=+3]
+
+[TIP]
+====
+You can add additional networks, including provider networks, to the `platform.openstack.additionalNetworkIDs` list.
+
+After you deploy your cluster, you can attach pods to additional networks. For more information, see xref:../../networking/multiple_networks/understanding-multiple-networks.adoc#understanding-multiple-networks[Understanding multiple networks].
+====
+
 include::modules/installation-osp-config-yaml.adoc[leveloffset=+2]
 include::modules/ssh-agent-using.adoc[leveloffset=+1]
 include::modules/installation-osp-accessing-api.adoc[leveloffset=+1]

installing/installing_openstack/installing-openstack-installer-custom.adoc

@@ -13,7 +13,6 @@ In {product-title} version {product-version}, you can install a customized clust
 * You reviewed details about the xref:../../architecture/architecture-installation.adoc#architecture-installation[{product-title} installation and update] processes.
 * You read the documentation on xref:../../installing/installing-preparing.adoc#installing-preparing[selecting a cluster installation method and preparing it for users].
 * You verified that {product-title} {product-version} is compatible with your {rh-openstack} version by using the xref:../../architecture/architecture-installation.adoc#supported-platforms-for-openshift-clusters_architecture-installation[Supported platforms for OpenShift clusters] section. You can also compare platform support across different versions by viewing the link:https://access.redhat.com/articles/4679401[{product-title} on {rh-openstack} support matrix].
-* Your network configuration does not rely on a provider network. Provider networks are not supported.
 * You have a storage service installed in {rh-openstack}, such as block storage (Cinder) or object storage (Swift). Object storage is the recommended storage technology for {product-title} registry cluster deployment. For more information, see xref:../../scalability_and_performance/optimizing-storage.adoc#optimizing-storage[Optimizing storage].
 
 include::modules/installation-osp-about-kuryr.adoc[leveloffset=+1]
@@ -37,6 +36,17 @@ include::modules/installation-configure-proxy.adoc[leveloffset=+2]
 include::modules/installation-configuration-parameters.adoc[leveloffset=+1]
 include::modules/installation-osp-custom-subnet.adoc[leveloffset=+2]
 include::modules/installation-osp-kuryr-config-yaml.adoc[leveloffset=+2]
+include::modules/installation-osp-provider-networks.adoc[leveloffset=+2]
+include::modules/installation-osp-provider-network-preparation.adoc[leveloffset=+3]
+include::modules/installation-osp-deploying-provider-networks-installer.adoc[leveloffset=+3]
+
+[TIP]
+====
+You can add additional networks, including provider networks, to the `platform.openstack.additionalNetworkIDs` list.
+
+After you deploy your cluster, you can attach pods to additional networks. For more information, see xref:../../networking/multiple_networks/understanding-multiple-networks.adoc#understanding-multiple-networks[Understanding multiple networks].
+====
+
 include::modules/ssh-agent-using.adoc[leveloffset=+1]
 include::modules/installation-osp-accessing-api.adoc[leveloffset=+1]
 include::modules/installation-osp-accessing-api-floating.adoc[leveloffset=+2]

installing/installing_openstack/installing-openstack-installer-kuryr.adoc

@@ -19,7 +19,6 @@ In {product-title} {product-version}, you can install a cluster on
 ====
 Because the installation media is on the mirror host, you can use that computer to complete all installation steps.
 ====
-* Your network configuration does not rely on a provider network. Provider networks are not supported.
 * You have the metadata service enabled in {rh-openstack}.
 
 include::modules/installation-about-restricted-network.adoc[leveloffset=+1]

installing/installing_openstack/installing-openstack-installer-restricted.adoc

@@ -12,7 +12,6 @@ In {product-title} version {product-version}, you can install a cluster on
 
 * You reviewed details about the xref:../../architecture/architecture-installation.adoc#architecture-installation[{product-title} installation and update] processes.
 * You read the documentation on xref:../../installing/installing-preparing.adoc#installing-preparing[selecting a cluster installation method and preparing it for users].
-* Your network configuration does not rely on a provider network. Provider networks are not supported.
 * On {rh-openstack}, you have access to an external network that does not overlap these CIDR ranges:
 ** `10.0.0.0/16`
 ** `172.30.0.0/16`

installing/installing_openstack/installing-openstack-installer.adoc

@@ -15,7 +15,6 @@ Using your own infrastructure allows you to integrate your cluster with existing
 * You reviewed details about the xref:../../architecture/architecture-installation.adoc#architecture-installation[{product-title} installation and update] processes.
 * You read the documentation on xref:../../installing/installing-preparing.adoc#installing-preparing[selecting a cluster installation method and preparing it for users].
 * You verified that {product-title} {product-version} is compatible with your {rh-openstack} version by using the xref:../../architecture/architecture-installation.adoc#supported-platforms-for-openshift-clusters_architecture-installation[Supported platforms for OpenShift clusters] section. You can also compare platform support across different versions by viewing the link:https://access.redhat.com/articles/4679401[{product-title} on {rh-openstack} support matrix].
-* Your network configuration does not rely on a provider network. Provider networks are not supported.
 * You have an {rh-openstack} account where you want to install {product-title}.
 * On the machine from which you run the installation program, you have:
 ** A single directory in which you can keep the files you create during the installation process
@@ -45,6 +44,17 @@ include::modules/installation-initializing.adoc[leveloffset=+1]
 include::modules/installation-configuration-parameters.adoc[leveloffset=+1]
 include::modules/installation-osp-custom-subnet.adoc[leveloffset=+2]
 include::modules/installation-osp-kuryr-config-yaml.adoc[leveloffset=+2]
+include::modules/installation-osp-provider-networks.adoc[leveloffset=+2]
+include::modules/installation-osp-provider-network-preparation.adoc[leveloffset=+3]
+include::modules/installation-osp-deploying-provider-networks-installer.adoc[leveloffset=+3]
+
+[TIP]
+====
+You can add additional networks, including provider networks, to the `platform.openstack.additionalNetworkIDs` list.
+
+After you deploy your cluster, you can attach pods to additional networks. For more information, see xref:../../networking/multiple_networks/understanding-multiple-networks.adoc#understanding-multiple-networks[Understanding multiple networks].
+====
+
 include::modules/installation-osp-fixing-subnet.adoc[leveloffset=+2]
 include::modules/installation-osp-emptying-worker-pools.adoc[leveloffset=+2]
 include::modules/installation-osp-modifying-networktype.adoc[leveloffset=+2]

installing/installing_openstack/installing-openstack-user-kuryr.adoc

@@ -15,7 +15,6 @@ Using your own infrastructure allows you to integrate your cluster with existing
 * You reviewed details about the xref:../../architecture/architecture-installation.adoc#architecture-installation[{product-title} installation and update] processes.
 * You read the documentation on xref:../../installing/installing-preparing.adoc#installing-preparing[selecting a cluster installation method and preparing it for users].
 * You verified that {product-title} {product-version} is compatible with your {rh-openstack} version by using the xref:../../architecture/architecture-installation.adoc#supported-platforms-for-openshift-clusters_architecture-installation[Supported platforms for OpenShift clusters] section. You can also compare platform support across different versions by viewing the link:https://access.redhat.com/articles/4679401[{product-title} on {rh-openstack} support matrix].
-* Your network configuration does not rely on a provider network. Provider networks are not supported.
 * You have an {rh-openstack} account where you want to install {product-title}.
 * On the machine from which you run the installation program, you have:
 ** A single directory in which you can keep the files you create during the installation process
@@ -42,6 +41,17 @@ include::modules/installation-osp-custom-subnet.adoc[leveloffset=+2]
 include::modules/installation-osp-config-yaml.adoc[leveloffset=+2]
 include::modules/installation-osp-fixing-subnet.adoc[leveloffset=+2]
 include::modules/installation-osp-emptying-worker-pools.adoc[leveloffset=+2]
+include::modules/installation-osp-provider-networks.adoc[leveloffset=+2]
+include::modules/installation-osp-provider-network-preparation.adoc[leveloffset=+3]
+include::modules/installation-osp-deploying-provider-networks-installer.adoc[leveloffset=+3]
+
+[TIP]
+====
+You can add additional networks, including provider networks, to the `platform.openstack.additionalNetworkIDs` list.
+
+After you deploy your cluster, you can attach pods to additional networks. For more information, see xref:../../networking/multiple_networks/understanding-multiple-networks.adoc#understanding-multiple-networks[Understanding multiple networks].
+====
+
 include::modules/installation-user-infra-generate-k8s-manifest-ignition.adoc[leveloffset=+1]
 include::modules/installation-osp-converting-ignition-resources.adoc[leveloffset=+1]
 include::modules/installation-osp-creating-control-plane-ignition.adoc[leveloffset=+1]

installing/installing_openstack/installing-openstack-user.adoc

@@ -0,0 +1,49 @@
+// Module included in the following assemblies:
+//
+// * installing/installing_openstack/installing-openstack-installer-custom.adoc
+// * installing/installing_openstack/installing-openstack-installer-kuryr.adoc
+// * installing/installing_openstack/installing-openstack-user-kuryr.adoc
+// * installing/installing_openstack/installing-openstack-user.adoc
+
+[id="installation-osp-deploying-provider-networks-installer_{context}"]
+= Deploying a cluster that has a primary interface on a provider network
+
+You can deploy an {product-title} cluster that has its primary network interface on an {rh-openstack-first} provider network.
+.Prerequisites
+
+* Your {rh-openstack-first} deployment is configured as described by "{rh-openstack} provider network requirements for cluster installation".
+
+.Procedure
+
+. In a text editor, open the `install-config.yaml` file.
+. Set the value of the `platform.openstack.apiVIP` property to the IP address for the API VIP.
+. Set the value of the `platform.openstack.ingressVIP` property to the IP address for the Ingress VIP.
+. Set the value of the `platform.openstack.machinesSubnet` property to the UUID of the provider network subnet.
+. Set the value of the `networking.machineNetwork.cidr` property to the CIDR block of the provider network subnet.
+
+[IMPORTANT]
+====
+The `platform.openstack.apiVIP` and `platform.openstack.ingressVIP` properties must both be unassigned IP addresses from the `networking.machineNetwork.cidr` block.
+====
+
+.Section of an installation configuration file for a cluster that relies on a {rh-openstack} provider network
+[source,yaml]
+----
+        ...
+        platform:
+          openstack:
+            apiVIP: 192.0.2.13
+            ingressVIP: 192.0.2.23
+            machinesSubnet: fa806b2f-ac49-4bce-b9db-124bc64209bf
+            (...)
+        networking:
+          machineNetwork:
+          - cidr: 192.0.2.0/24
+----
+
+[WARNING]
+====
+You cannot set the `platform.openstack.externalNetwork` or `platform.openstack.externalDNS` parameters while using a provider network for the primary network interface.
+====
+
+When you deploy the cluster, the installer uses the `install-config.yaml` file to deploy the cluster on the provider network.

modules/installation-osp-deploying-provider-networks-installer.adoc

@@ -0,0 +1,56 @@
+// Module included in the following assemblies:
+//
+// * installing/installing_openstack/installing-openstack-installer-custom.adoc
+// * installing/installing_openstack/installing-openstack-installer-kuryr.adoc
+// * installing/installing_openstack/installing-openstack-user-kuryr.adoc
+// * installing/installing_openstack/installing-openstack-user.adoc
+
+[id="installation-osp-provider-network-preparation_{context}"]
+= {rh-openstack} provider network requirements for cluster installation
+
+Before you install an {product-title} cluster, your {rh-openstack-first} deployment and provider network must meet a number of conditions:
+
+* The link:https://access.redhat.com/documentation/en-us/red_hat_openstack_platform/16.1/html/networking_guide/networking-concepts_networking-concepts#install-networking_networking-concepts[{rh-openstack} networking service (Neutron) is enabled] and accessible through the {rh-openstack} networking API.
+* The {rh-openstack} networking service has the link:https://access.redhat.com/documentation/en-us/red_hat_openstack_platform/16.1/html/networking_guide/config-allowed-address-pairs_config-allowed-address-pairs#overview-allow-addr-pairs_config-allowed-address-pairs[port security and allowed address pairs extensions enabled].
+* The provider network can be shared with other tenants.
++
+[TIP]
+====
+Use the `openstack network create` command with the `--share` flag to create a network that can be shared.
+====
+* The {rh-openstack} project that you use to install the cluster must own the provider network, as well as an appropriate subnet.
++
+[TIP]
+====
+To create a network for a project that is named "openshift," enter the following command::
+[source,terminal]
+----
+$ openstack network create --project openshift
+----
+
+To create a subnet for a project that is named "openshift," enter the following command::
+[source,terminal]
+----
+$ openstack subnet create --project openshift
+----
+
+To learn more about creating networks on {rh-openstack}, read link:https://access.redhat.com/documentation/en-us/red_hat_openstack_platform/16.1/html/networking_guide/networking-concepts_networking-concepts#tenant-provider-networks_networking-concepts[the provider networks documentation].
+====
++
+If the cluster is owned by the `admin` user, you must run the installer as that user to create ports on the network.
++
+[IMPORTANT]
+====
+Provider networks must be owned by the {rh-openstack} project that is used to create the cluster. If they are not, the {rh-openstack} Compute service (Nova) cannot request a port from that network.
+====
+
+* Verify that the provider network can reach the {rh-openstack} metadata service IP address, which is `169.254.169.254` by default.
++
+Depending on your {rh-openstack} SDN and networking service configuration, you might need to create provide the route when you create the subnet. For example:
++
+[source,terminal]
+----
+$ openstack subnet create --dhcp --host-route destination=169.254.169.254/32,gateway=192.0.2.2 ...
+----
+
+* Optional: To secure the network, create link:https://access.redhat.com/documentation/en-us/red_hat_openstack_platform/16.1/html/networking_guide/config-rbac-policies_config-rbac-policies[role-based access control (RBAC)] rules that limit network access to a single project.

modules/installation-osp-provider-network-preparation.adoc

@@ -0,0 +1,28 @@
+// Module included in the following assemblies:
+//
+// * installing/installing_openstack/installing-openstack-installer-custom.adoc
+// * installing/installing_openstack/installing-openstack-installer-kuryr.adoc
+// * installing/installing_openstack/installing-openstack-user-kuryr.adoc
+// * installing/installing_openstack/installing-openstack-user.adoc
+
+[id="installation-osp-provider-networks_{context}"]
+= Cluster deployment on {rh-openstack} provider networks
+
+You can deploy your {product-title} clusters on {rh-openstack-first} with a primary network interface on a provider network. Provider networks are commonly used to give projects direct access to a public network that can be used to reach the Internet. You can also share provider networks among projects as part of the network creation process.
+
+{rh-openstack} provider networks map directly to an existing physical network in the data center. A {rh-openstack} administrator must create them.
+
+In the following example, {product-title} workloads are connected to a data center by using a provider network:
+
+image::openshift-on-openstack-provider-network.png[A diagram that depicts four OpenShift workloads on OpenStack. Each workload is connected by its NIC to an external data center by using a provider network.]
+
+{product-title} clusters that are installed on provider networks do not require tenant networks or floating IP addresses. The installer does not create these resources during installation.
+
+Example provider network types include flat (untagged) and VLAN (802.1Q tagged).
+
+[NOTE]
+====
+A cluster can support as many provider network connections as the network type allows. For example, VLAN networks typically support up to 4096 connections.
+====
+
+You can learn more about provider and tenant networks in link:https://access.redhat.com/documentation/en-us/red_hat_openstack_platform/16.1/html/networking_guide/networking-concepts_networking-concepts#provider-networks_networking-concepts[the {rh-openstack} documentation].