Merge pull request #9044 from shiftstack/add-ipv6-docs

OSASINFRA-3615: OpenStack: Add installation steps for single stack IPv6 clusters

Author: openshift-merge-bot[bot]

docs/user/openstack/customization.md

@@ -173,14 +173,14 @@ In the `install-config.yaml` file, the value of the `controlPlanePort` property
 
 * Any subnet used by `controlPlanePort` have DHCP enabled.
 * The CIDR of any subnet listed in `controlPlanePort.fixedIPs` matches the CIDRs listed on `networks.machineNetwork`.
-* When using dual-stack Network the api and ingress Ports needs to be pre-created by the user. Also, the installer user must have permission to add tags and security groups to those pre-created Ports. The value of the fixed IPs of the Ports needs to be specified at the `apiVIPs` and `ingressVIPs` options in the `install-config.yaml`.
-* If not using dual-stack, the installer user must have permission to create ports on this network, including ports with fixed IP addresses.
+* When using dual-stack or single stack IPv6 Network the api and ingress Ports needs to be pre-created by the user. Also, the installer user must have permission to add tags and security groups to those pre-created Ports. The value of the fixed IPs of the Ports needs to be specified at the `apiVIPs` and `ingressVIPs` options in the `install-config.yaml`.
+* If not using dual-stack or single stack IPv6, the installer user must have permission to create ports on this network, including ports with fixed IP addresses.
 
 You should also be aware of the following limitations:
 
 * If you plan to install a cluster that uses floating IPs, the `controlPlanePort` must be attached to a router that is connected to the `externalNetwork`.
 * The installer will not create a private network or subnet for your OpenShift machines if the `controlPlanePort` is set in the `install-config.yaml`.
-* By default when not using dual-stack, the API and Ingress VIPs use the .5 and .7 of your network CIDR. To prevent other services from taking the ports that are assigned to the API and Ingress VIPs, set the `apiVIP` and `ingressVIP` options in the `install-config.yaml` to addresses that are outside of the DHCP allocation pool.
+* By default when not using dual-stack or single stack IPv6, the API and Ingress VIPs use the .5 and .7 of your network CIDR. To prevent other services from taking the ports that are assigned to the API and Ingress VIPs, set the `apiVIP` and `ingressVIP` options in the `install-config.yaml` to addresses that are outside of the DHCP allocation pool.
 * You cannot use the `externalDNS` property at the same time as a custom `controlPlanePort`. If you want to add a DNS to your cluster while using a custom subnet, [add it to the subnet in OpenStack](https://docs.openstack.org/neutron/rocky/admin/config-dns-res.html).
 
 ## Additional Networks

docs/user/openstack/deploy_dual_stack_cluster.md

@@ -4,15 +4,15 @@
 
 - [Prerequisites](#prerequisites)
 - [Creating DualStack Networks for the cluster](#creating-dualstack-networks-for-the-cluster)
-- [Creating DualStack API and Ingress VIPs Ports for the cluster](#creating-dualstack-api-and-ingress-vips-for-the-cluster)
+- [Creating DualStack API and Ingress VIPs Ports for the cluster](#creating-dualstack-api-and-ingress-vips-ports-for-the-cluster)
 - [Deploy OpenShift](#deploy-openshift)
 
 ## Prerequisites
 
 * Installation with dual-stack is only allowed when using one OpenStack network with one IPv4 and IPv6 subnet.
 * API and Ingress VIPs ports needs to pre-created by the user and the addresses specified in the `install-config.yaml`.
 * Add the IPv6 Subnet to a neutron router to provide router advertisements.
-* The dualstack network MTU must accomodate the minimun MTU for IPv6, which is 1280, and OVN-Kubernetes encapsulation overhead, which is 100.
+* The dualstack network MTU must accommodate the minimum MTU for IPv6, which is 1280, and OVN-Kubernetes encapsulation overhead, which is 100.
 
 Additional prerequisites are listed at the [OpenStack Platform Customization docs](./customization.md)
 

docs/user/openstack/deploy_single_stack_ipv6_cluster.md

@@ -0,0 +1,101 @@
+# Creating a single stack IPv6 cluster on OpenStack
+
+## Table of Contents
+
+- [Prerequisites](#prerequisites)
+- [Creating Network for the cluster](#creating-network-for-the-cluster)
+- [Creating IPv6 API and Ingress VIPs Ports for the cluster](#creating-ipv6-api-and-ingress-vips-ports-for-the-cluster)
+- [Deploy OpenShift](#deploy-openshift)
+
+## Prerequisites
+
+* Installation with single stack IPv6 is only allowed when using one pre-created OpenStack IPv6 subnet.
+* DNS must be configured in the Subnet.
+* Add the IPv6 Subnet to a neutron router to provide router advertisements.
+* The network MTU must accommodate the minimum MTU for IPv6, which is 1280, and OVN-Kubernetes encapsulation overhead, which is 100.
+* API and Ingress VIPs ports needs to pre-created by the user and the addresses specified in the `install-config.yaml`.
+* A local image registry needs to be pre-configured to mirror the images over IPv6.
+
+Additional prerequisites are listed at the [OpenStack Platform Customization docs](./customization.md)
+
+**Note**: Converting a dual-stack cluster to single stack IPv6 cluster is not supported with OpenStack.
+
+## Creating Network for the cluster
+
+You must create one network and add the IPv6 subnet. Here is an example:
+
+```sh
+$ openstack network create --project <project-name> --share --external --provider-physical-network <physical-network> --provider-network-type flat v6-network
+$ openstack subnet create --project <project-name> v6-subnet --subnet-range fd2e:6f44:5dd8:c956::/64 --dhcp --dns-nameserver <dns-address> --network v6-network --ip-version 6 --ipv6-ra-mode stateful --ipv6-address-mode stateful
+```
+
+**Note**: using an IPv6 slaac subnet is not supported given a known [OpenStack issue](https://bugzilla.redhat.com/show_bug.cgi?id=2304331) that prevents DNS from working.
+
+Given the above example uses a provider network, this network can be added to the router external gateway to enable external connectivity and router advertisements with the following command:
+```sh
+$ openstack router set --external-gateway v6-network <router-id>
+```
+
+## Creating IPv6 API and Ingress VIPs Ports for the cluster
+
+You must create the API and Ingress VIPs Ports with the following commands:
+
+```sh
+$ openstack port create api --network v6-network
+$ openstack port create ingress --network v6-network
+```
+
+## Deploy OpenShift
+
+Now that the Networking resources are pre-created you can deploy OpenShift. Here is an example of `install-config.yaml`:
+
+```yaml
+apiVersion: v1
+baseDomain: mydomain.test
+compute:
+- name: worker
+  platform:
+    openstack:
+      type: m1.xlarge
+  replicas: 3
+controlPlane:
+  name: master
+  platform:
+    openstack:
+      type: m1.xlarge
+  replicas: 3
+metadata:
+  name: mycluster
+networking:
+  machineNetwork:
+  - cidr: "fd2e:6f44:5dd8:c956::/64"
+  clusterNetwork:
+  - cidr: fd01::/48
+    hostPrefix: 64
+  serviceNetwork:
+  - fd02::/112
+platform:
+  openstack:
+    ingressVIPs: ['fd2e:6f44:5dd8:c956::383']
+    apiVIPs: ['fd2e:6f44:5dd8:c956::9a']
+    controlPlanePort:
+      fixedIPs:
+      - subnet:
+          name: subnet-v6
+      network:
+        name: v6-network
+imageContentSources:
+- mirrors:
+  - <mirror>
+  source: quay.io/openshift-release-dev/ocp-v4.0-art-dev
+- mirrors:
+  - <mirror>
+  source: registry.ci.openshift.org/ocp/release
+additionalTrustBundle: |
+<certificate-of-the-mirror>
+```
+There are important things to note:
+
+The subnets under `platform.openstack.controlPlanePort.fixedIPs` can contain both id or name. The same applies to the network `platform.openstack.controlPlanePort.network`.
+
+The image content sources contains the details of the mirror to be used. Please follow the docs to configure a [local image registry](https://docs.openshift.com/container-platform/4.16/installing/disconnected_install/installing-mirroring-creating-registry.html).