Merge pull request #51135 from rohennes/TELCODOCS-328-dual-vips

TELCODOCS-328 - Adding new VIP install params for IPv4 and IPv6

Author: EricPonvelle

modules/installation-configuration-parameters.adoc

@@ -1394,12 +1394,24 @@ Additional {rh-virtualization} configuration parameters are described in the fol
 |Required. The vNIC profile ID of the VM network interfaces. This can be inferred if the cluster network has a single profile.
 |String. For example: `3fa86930-0be5-4052-b667-b79f0a729692`
 
-|`platform.ovirt.api_vip`
-|Required. An IP address on the machine network that will be assigned to the API virtual IP (VIP). You can access the OpenShift API at this endpoint.
+|`platform.ovirt.api_vips`
+|Required. An IP address on the machine network that will be assigned to the API virtual IP (VIP). You can access the OpenShift API at this endpoint. For dual-stack networks, assign up to two IP addresses. The primary IP address must be from the IPv4 network. 
+
+[NOTE]
+====
+In {product-title} 4.12 and later, the `api_vip` configuration setting is deprecated. Instead, use a list format to enter a value in the `api_vips` configuration setting. The order of the list indicates the primary and secondary VIP address for each service.
+====
+
 |String. Example: `10.46.8.230`
 
-|`platform.ovirt.ingress_vip`
-|Required. An IP address on the machine network that will be assigned to the Ingress virtual IP (VIP).
+|`platform.ovirt.ingress_vips`
+|Required. An IP address on the machine network that will be assigned to the Ingress virtual IP (VIP). For dual-stack networks, assign up to two IP addresses. The primary IP address must be from the IPv4 network. 
+
+[NOTE]
+====
+In {product-title} 4.12 and later, the `ingress_vip` configuration setting is deprecated. Instead, use a list format to enter a value in the `ingress_vips` configuration setting. The order of the list indicates the primary and secondary VIP address for each service.
+====
+
 |String. Example: `10.46.8.232`
 
 |`platform.ovirt.affinityGroups`
@@ -1563,14 +1575,24 @@ in vSphere.
 |The vCenter cluster to install the {product-title} cluster in.
 |String
 
-|`platform.vsphere.apiVIP`
+|`platform.vsphere.apiVIPs`
 |The virtual IP (VIP) address that you configured for control plane API access.
 |An IP address, for example `128.0.0.1`.
 
-|`platform.vsphere.ingressVIP`
+[NOTE]
+====
+In {product-title} 4.12 and later, the `apiVIP` configuration setting is deprecated. Instead, use a list format to enter a value in the `apiVIPs` configuration setting.
+====
+
+|`platform.vsphere.ingressVIPs`
 |The virtual IP (VIP) address that you configured for cluster ingress.
 |An IP address, for example `128.0.0.1`.
 
+[NOTE]
+====
+In {product-title} 4.12 and later, the `ingressVIP` configuration setting is deprecated. Instead, use a list format to enter a value in the `ingressVIPs` configuration setting.
+====
+
 |`platform.vsphere.diskType`
 |Optional. The disk provisioning method. This value defaults to the vSphere default storage policy if not set.
 |Valid values are `thin`, `thick`, or `eagerZeroedThick`.

modules/installation-installer-provisioned-vsphere-config-yaml.adoc

@@ -83,8 +83,10 @@ platform:
     diskType: thin <7>
     network: VM_Network
     cluster: vsphere_cluster_name <8>
-    apiVIP: api_vip
-    ingressVIP: ingress_vip
+    apiVIPs: 
+      - api_vip
+    ingressVIPs: 
+      - ingress_vip
 ifdef::restricted[]
     clusterOSImage: http://mirror.example.com/images/rhcos-47.83.202103221318-0-vmware.x86_64.ova <9>
 endif::restricted[]
@@ -148,6 +150,11 @@ specify the base64-encoded user name and password for your mirror registry.
 <12> Provide the `imageContentSources` section from the output of the command to mirror the repository.
 endif::restricted[]
 
+[NOTE]
+====
+In {product-title} 4.12 and later, the `apiVIP` and `ingressVIP` configuration settings are deprecated. Instead, use a list format to enter values in the `apiVIPs` and `ingressVIPs` configuration settings.
+====
+
 ifeval::["{context}" == "installing-vsphere-installer-provisioned-network-customizations"]
 :!network:
 endif::[]

modules/installation-osp-custom-subnet.adoc

@@ -30,7 +30,7 @@ Clusters that use custom subnets have the following limitations:
 [NOTE]
 ====
 By default, the API VIP takes x.x.x.5 and the Ingress VIP takes x.x.x.7 from your network's CIDR block. To override these default values,
-set values for `platform.openstack.apiVIP` and `platform.openstack.ingressVIP` that are outside of the DHCP allocation pool.
+set values for `platform.openstack.apiVIPs` and `platform.openstack.ingressVIPs` that are outside of the DHCP allocation pool.
 ====
 
 [IMPORTANT]

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

@@ -17,14 +17,14 @@ You can deploy an {product-title} cluster that has its primary network interface
 .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.apiVIPs` property to the IP address for the API VIP.
+. Set the value of the `platform.openstack.ingressVIPs` 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.
+The `platform.openstack.apiVIPs` and `platform.openstack.ingressVIPs` 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
@@ -33,15 +33,19 @@ The `platform.openstack.apiVIP` and `platform.openstack.ingressVIP` properties m
         ...
         platform:
           openstack:
-            apiVIP: 192.0.2.13
-            ingressVIP: 192.0.2.23
+            apiVIPs: <1>
+              - 192.0.2.13 
+            ingressVIPs: <1>
+              - 192.0.2.23 
             machinesSubnet: fa806b2f-ac49-4bce-b9db-124bc64209bf
             # ...
         networking:
           machineNetwork:
           - cidr: 192.0.2.0/24
 ----
 
+<1> In {product-title} 4.12 and later, the `apiVIP` and `ingressVIP` configuration settings are deprecated. Instead, use a list format to enter values in the `apiVIPs` and `ingressVIPs` configuration settings.
+
 [WARNING]
 ====
 You cannot set the `platform.openstack.externalNetwork` or `platform.openstack.externalDNS` parameters while using a provider network for the primary network interface.

modules/installing-rhv-example-install-config-yaml.adoc

@@ -67,8 +67,10 @@ endif::openshift-origin[]
   - 172.30.0.0/16
 platform:
   ovirt:
-    api_vip: 10.46.8.230
-    ingress_vip: 192.168.1.5
+    api_vips: 
+      - 10.0.0.10
+    ingress_vips: 
+      - 10.0.0.11
     ovirt_cluster_id: 68833f9f-e89c-4891-b768-e2ba0815b76b
     ovirt_storage_domain_id: ed7b0f4e-0e96-492a-8fff-279213ee1468
     ovirt_network_name: ovirtmgmt
@@ -89,6 +91,11 @@ capabilities:
 ====
 Preallocating disks on file storage domains writes zeroes to the file. This might not actually preallocate disks depending on the underlying storage.
 ====
++
+[NOTE]
+====
+In {product-title} 4.12 and later, the `api_vip` and `ingress_vip` configuration settings are deprecated. Instead, use a list format to enter values in the `api_vips` and `ingress_vips` configuration settings.
+====
 
 [discrete]
 == Example minimal `install-config.yaml` file
@@ -101,8 +108,10 @@ metadata:
   name: test-cluster
 platform:
   ovirt:
-    api_vip: 10.46.8.230
-    ingress_vip: 10.46.8.232
+    api_vips: 
+      - 10.46.8.230
+    ingress_vips: 
+      - 10.46.8.232
     ovirt_cluster_id: 68833f9f-e89c-4891-b768-e2ba0815b76b
     ovirt_storage_domain_id: ed7b0f4e-0e96-492a-8fff-279213ee1468
     ovirt_network_name: ovirtmgmt
@@ -111,6 +120,10 @@ pullSecret: '{"auths": ...}'
 sshKey: ssh-ed12345 AAAA...
 ----
 
+[NOTE]
+====
+In {product-title} 4.12 and later, the `api_vip` and `ingress_vip` configuration settings are deprecated. Instead, use a list format to enter values in the `api_vips` and `ingress_vips` configuration settings.
+====
 
 [discrete]
 == Example Custom machine pools in an `install-config.yaml` file
@@ -147,8 +160,10 @@ metadata:
   name: test-cluster
 platform:
   ovirt:
-    api_vip: 10.46.8.230
-    ingress_vip: 10.46.8.232
+    api_vips: 
+      - 10.46.8.230
+    ingress_vips: 
+      - 10.46.8.232
     ovirt_cluster_id: 68833f9f-e89c-4891-b768-e2ba0815b76b
     ovirt_storage_domain_id: ed7b0f4e-0e96-492a-8fff-279213ee1468
     ovirt_network_name: ovirtmgmt
@@ -157,6 +172,11 @@ pullSecret: '{"auths": ...}'
 sshKey: ssh-ed25519 AAAA...
 ----
 
+[NOTE]
+====
+In {product-title} 4.12 and later, the `api_vip` and `ingress_vip` configuration settings are deprecated. Instead, use a list format to enter values in the `api_vips` and `ingress_vips` configuration settings.
+====
+
 [discrete]
 == Example non-enforcing affinity group
 

modules/ipi-install-additional-install-config-parameters.adoc

@@ -9,6 +9,7 @@
 See the following tables for the required parameters, the `hosts` parameter,
 and the `bmc` parameter for the `install-config.yaml` file.
 
+[cols="2,1,5"]
 [options="header"]
 .Required parameters
 |===
@@ -98,16 +99,26 @@ a| `provisioningNetworkInterface` |  | The name of the network interface on node
 
 | `defaultMachinePlatform` | | The default configuration used for machine pools without a platform configuration.
 
-| `apiVIP` | | (Optional) The virtual IP address for Kubernetes API communication.
+| `apiVIPs` | a| (Optional) The virtual IP address for Kubernetes API communication.
+
+This setting must either be provided in the `install-config.yaml` file as a reserved IP from the MachineNetwork or pre-configured in the DNS so that the default name resolves correctly. Use the virtual IP address and not the FQDN when adding a value to the `apiVIPs` configuration setting in the `install-config.yaml` file. The primary IP address must be from the IPv4 network when using dual stack networking. If not set, the installation program uses `api.<cluster_name>.<base_domain>` to derive the IP address from the DNS.
+
+[NOTE]
+====
+Before {product-title} 4.12, the cluster installation program only accepted an IPv4 address or an IPv6 address for the `apiVIP` configuration setting. From {product-title} 4.12 or later, the `apiVIP` configuration setting is deprecated. Instead, use a list format for the `apiVIPs` configuration setting to specify an IPv4 address, an IPv6 address or both IP address formats.
+====
 
-This setting must either be provided in the `install-config.yaml` file as a reserved IP from the MachineNetwork or pre-configured in the DNS so that the default name resolves correctly. Use the virtual IP address and not the FQDN when adding a value to the `apiVIP` configuration setting in the `install-config.yaml` file. The IP address must be from the primary IPv4 network when using dual stack networking. If not set, the installer uses `api.<cluster_name>.<base_domain>` to derive the IP address from the DNS.
 
 | `disableCertificateVerification` | `False` | `redfish` and `redfish-virtualmedia` need this parameter to manage BMC addresses. The value should be `True` when using a self-signed certificate for BMC addresses.
 
-| `ingressVIP` | | (Optional) The virtual IP address for ingress traffic.
+| `ingressVIPs` | a| (Optional) The virtual IP address for ingress traffic.
 
-This setting must either be provided in the `install-config.yaml` file as a reserved IP from the MachineNetwork or pre-configured in the DNS so that the default name resolves correctly. Use the virtual IP address and not the FQDN when adding a value to the `ingressVIP` configuration setting in the `install-config.yaml` file. The IP address must be from the primary IPv4 network when using dual stack networking. If not set, the installer uses `test.apps.<cluster_name>.<base_domain>` to derive the IP address from the DNS.
+This setting must either be provided in the `install-config.yaml` file as a reserved IP from the MachineNetwork or pre-configured in the DNS so that the default name resolves correctly. Use the virtual IP address and not the FQDN when adding a value to the `ingressVIPs` configuration setting in the `install-config.yaml` file. The primary IP address must be from the IPv4 network when using dual stack networking. If not set, the installation program uses `test.apps.<cluster_name>.<base_domain>` to derive the IP address from the DNS.
 
+[NOTE]
+====
+Before {product-title} 4.12, the cluster installation program only accepted an IPv4 address or an IPv6 address for the `ingressVIP` configuration setting. In {product-title} 4.12 and later, the `ingressVIP` configuration setting is deprecated. Instead, use a list format for the `ingressVIPs` configuration setting to specify an IPv4 addresses, an IPv6 addresses or both IP address formats.
+====
 
 |===
 

modules/ipi-install-configuring-the-install-config-file.adoc

@@ -36,8 +36,10 @@ controlPlane:
     baremetal: {}
 platform:
   baremetal:
-    apiVIP: <api_ip>
-    ingressVIP: <wildcard_ip>
+    apiVIPs:
+      - <api_ip>
+    ingressVIPs:
+      - <wildcard_ip>
     provisioningNetworkCIDR: <CIDR>
     bootstrapExternalStaticIP: <bootstrap_static_ip_address> <2>
     bootstrapExternalStaticGateway: <bootstrap_static_gateway> <3>
@@ -95,6 +97,11 @@ sshKey: '<ssh_pub_key>'
 <4> See the BMC addressing sections for more options.
 <5> Set the path to the installation disk drive, for example, `/dev/disk/by-id/wwn-0x64cd98f04fde100024684cf3034da5c2`.
 
+[NOTE]
+====
+Before {product-title} 4.12, the cluster installation program only accepted an IPv4 address or and IPv6 address for the `apiVIP` and `ingressVIP` configuration settings. In {product-title} 4.12 and later, these configuration settings are deprecated. Instead, use a list format in the `apiVIPs` and `ingressVIPs` configuration settings to specify IPv4 addresses, IPv6 addresses or both IP address formats. 
+====
+
 . Create a directory to store the cluster configuration:
 +
 [source,terminal]

modules/ipi-install-modifying-install-config-for-dual-stack-network.adoc

@@ -6,7 +6,7 @@
 [id='modifying-install-config-for-dual-stack-network_{context}']
 = Optional: Deploying with dual-stack networking
 
-To deploy an {product-title} cluster with dual-stack networking, edit the `machineNetwork`, `clusterNetwork`, and `serviceNetwork` configuration settings in the `install-config.yaml` file. Each setting must have two CIDR entries each. Ensure the first CIDR entry is the IPv4 setting and the second CIDR entry is the IPv6 setting.
+For dual-stack networking in {product-title} clusters, you can configure IPv4 and IPv6 address endpoints for cluster nodes. To configure IPv4 and IPv6 address endpoints for cluster nodes, edit the `machineNetwork`, `clusterNetwork`, and `serviceNetwork` configuration settings in the `install-config.yaml` file. Each setting must have two CIDR entries each. Ensure the first CIDR entry is the IPv4 setting and the second CIDR entry is the IPv6 setting.
 
 [source,yaml]
 ----
@@ -27,3 +27,17 @@ serviceNetwork:
 ====
 The API VIP IP address and the Ingress VIP address must be of the primary IP address family when using dual-stack networking. Currently, Red Hat does not support dual-stack VIPs or dual-stack networking with IPv6 as the primary IP address family. However, Red Hat does support dual-stack networking with IPv4 as the primary IP address family. Therefore, the IPv4 entries must go *before* the IPv6 entries.
 ====
+
+To provide an interface to the cluster for applications that use IPv4 and IPv6 addresses, configure IPv4 and IPv6 virtual IP (VIP) address endpoints for the Ingress VIP and API VIP services. To configure IPv4 and IPv6 address endpoints, edit the `apiVIPs` and `ingressVIPs` configuration settings in the `install-config.yaml` file . The `apiVIPs` and `ingressVIPs` configuration settings use a list format. The order of the list indicates the primary and secondary VIP address for each service.
+
+[source,yaml]
+----
+platform:
+  baremetal:
+    apiVIPs:
+      - <api_ipv4>
+      - <api_ipv6>
+    ingressVIPs:
+      - <wildcard_ipv4>
+      - <wildcard_ipv6>
+----

modules/ipi-install-modifying-install-config-for-no-provisioning-network.adoc

@@ -12,8 +12,10 @@ To deploy an {product-title} cluster without a `provisioning` network, make the
 ----
 platform:
   baremetal:
-    apiVIP: <api_VIP>
-    ingressVIP: <ingress_VIP>
+    apiVIPs: 
+      - <api_VIP>
+    ingressVIPs: 
+      - <ingress_VIP>
     provisioningNetwork: "Disabled" <1>
 ----