From ceb69209255874a6db5a8ccc2253f9d952786a25 Mon Sep 17 00:00:00 2001 From: dfitzmau Date: Fri, 26 Apr 2024 16:24:10 +0100 Subject: [PATCH] OSDOCS-8931: Detail step for adding IPv6 to existing dual-stack clusters --- modules/nw-dual-stack-convert.adoc | 102 ++++++++++++++---- .../converting-to-dual-stack.adoc | 13 ++- 2 files changed, 92 insertions(+), 23 deletions(-) diff --git a/modules/nw-dual-stack-convert.adoc b/modules/nw-dual-stack-convert.adoc index 083d160c9977..0b6d5cbe27eb 100644 --- a/modules/nw-dual-stack-convert.adoc +++ b/modules/nw-dual-stack-convert.adoc @@ -2,11 +2,13 @@ [id="nw-dual-stack-convert_{context}"] = Converting to a dual-stack cluster network -As a cluster administrator, you can convert your single-stack cluster network to a dual-stack cluster network. +As a cluster administrator, you can convert your single-stack cluster network to a dual-stack cluster network. After converting to a dual-stack networking, new and existing pods have dual-stack networking enabled. + +Converting a single-stack cluster network to a dual-stack cluster network consists of creating patches and applying them to the cluster's network and infrastructure. [NOTE] ==== -After converting to dual-stack networking only newly created pods are assigned IPv6 addresses. Any pods created before the conversion must be recreated to receive an IPv6 address. +Each patch operation that changes `clusterNetwork`, `serviceNetwork`, `apiServerInternalIPs`, and `ingressIP` objects triggers a restart of the cluster. Changing the `MachineNetworks` object does not cause a reboot of the cluster. ==== .Prerequisites @@ -19,9 +21,8 @@ After converting to dual-stack networking only newly created pods are assigned I .Procedure -. To specify IPv6 address blocks for the cluster and service networks, create a file containing the following YAML: +. To specify IPv6 address blocks for the cluster and service networks, create a YAML configuration patch file that has a similar configuration to the following example: + --- [source,yaml] ---- - op: add @@ -33,45 +34,71 @@ After converting to dual-stack networking only newly created pods are assigned I path: /spec/serviceNetwork/- value: fd02::/112 <2> ---- -<1> Specify an object with the `cidr` and `hostPrefix` fields. The host prefix must be `64` or greater. The IPv6 CIDR prefix must be large enough to accommodate the specified host prefix. - +<1> Specify an object with the `cidr` and `hostPrefix` fields. The host prefix must be `64` or greater. The IPv6 Classless Inter-Domain Routing (CIDR) prefix must be large enough to accommodate the specified host prefix. <2> Specify an IPv6 CIDR with a prefix of `112`. Kubernetes uses only the lowest 16 bits. For a prefix of `112`, IP addresses are assigned from `112` to `128` bits. --- -. To patch the cluster network configuration, enter the following command: +. Patch the cluster network configuration by entering the following command in your CLI: + -[source,terminal] +[source,terminal,subs="+quotes"] ---- -$ oc patch network.config.openshift.io cluster \ +$ oc patch network.config.openshift.io cluster \// <1> --type='json' --patch-file .yaml ---- +<1> Where `file` specifies the name of your created YAML file. ++ +.Example output +[source,text] +---- +network.config.openshift.io/cluster patched +---- + +. To specify IPv6 Virtual IPs (VIPs) for API and Ingress services for your cluster, create a YAML configuration patch file that has a similar configuration to the following example: + --- -where: +[source,yaml] +---- +- op: add + path: /spec/platformSpec/baremetal/machineNetworks/- <1> + value: fd2e:6f44:5dd8::/64 +- op: add + path: /spec/platformSpec/baremetal/apiServerInternalIPs/- <2> + value: fd2e:6f44:5dd8::4 +- op: add + path: /spec/platformSpec/baremetal/ingressIPs/- + value: fd2e:6f44:5dd8::5 +---- +<1> Ensure that you specify an address block for the `machineNetwork` network where your machines operate. You must select both API and Ingress IP addresses for the machine network. +<2> Ensure that you specify each file path according to your platform. The example demonstrates a file path on a bare-metal platform. -`file`:: Specifies the name of the file you created in the previous step. --- +. Patch the cluster's infrastructure by entering the following command in your CLI: ++ +[source,terminal,subs="+quotes"] +---- +$ oc patch infrastructure cluster \// <1> + --type='json' --patch-file .yaml +---- +<1> Where `file` specifies the name of your created YAML file. + .Example output [source,text] ---- -network.config.openshift.io/cluster patched +infrastructure/cluster patched ---- .Verification -Complete the following step to verify that the cluster network recognizes the IPv6 address blocks that you specified in the previous procedure. - -. Display the network configuration: +. Show the cluster network configuration by entering the following command in your CLI: + [source,terminal] ---- $ oc describe network ---- + +. Verify the successful installation of the patch on the network configuration by checking that the cluster network configuration recognizes the IPv6 address blocks that you specified in the YAML file. + .Example output [source,text] ---- +# ... Status: Cluster Network: Cidr: 10.128.0.0/14 @@ -83,4 +110,43 @@ Status: Service Network: 172.30.0.0/16 fd02::/112 +# ... +---- + +. Show the cluster infrastructure configuration by entering the following command in your CLI: ++ +[source,terminal] +---- +$ oc describe network +---- + +. Verify the successful installation of the patch on the cluster infrastructure by checking that the infrastructure recognizes the IPv6 address blocks that you specified in the YAML file. ++ +.Example output +[source,text] +---- +# ... +spec: +# ... + platformSpec: + baremetal: + apiServerInternalIPs: + - 192.168.123.5 + - fd2e:6f44:5dd8::4 + ingressIPs: + - 192.168.123.10 + - fd2e:6f44:5dd8::5 +status: +# ... + platformStatus: + baremetal: + apiServerInternalIP: 192.168.123.5 + apiServerInternalIPs: + - 192.168.123.5 + - fd2e:6f44:5dd8::4 + ingressIP: 192.168.123.10 + ingressIPs: + - 192.168.123.10 + - fd2e:6f44:5dd8::5 +# ... ---- diff --git a/networking/ovn_kubernetes_network_provider/converting-to-dual-stack.adoc b/networking/ovn_kubernetes_network_provider/converting-to-dual-stack.adoc index 37473fe3c26a..6c77ca4951fc 100644 --- a/networking/ovn_kubernetes_network_provider/converting-to-dual-stack.adoc +++ b/networking/ovn_kubernetes_network_provider/converting-to-dual-stack.adoc @@ -6,14 +6,17 @@ include::_attributes/common-attributes.adoc[] toc::[] -As a cluster administrator, you can convert your IPv4 single-stack cluster to a dual-network cluster network that supports IPv4 and IPv6 address families. -After converting to dual-stack, all newly created pods are dual-stack enabled. +As a cluster administrator, you can convert your IPv4 single-stack cluster to a dual-network cluster network that supports IPv4 and IPv6 address families. After converting to dual-stack networking, new and existing pods have dual-stack networking enabled. -[NOTE] +Clusters provisioned on bare metal, {ibm-power-name}, {ibm-z-name} infrastructure, {sno}, and {vmw-full} support dual-stack networking. + +[IMPORTANT] ==== -* While using dual-stack networking, you cannot use IPv4-mapped IPv6 addresses, such as `::FFFF:198.51.100.1`, where IPv6 is required. -* A dual-stack network is supported on clusters provisioned on bare metal, {ibm-power-name}, {ibm-z-name} infrastructure, {sno}, and VMware vSphere. +When using dual-stack networking where IPv6 is required, you cannot use IPv4-mapped IPv6 addresses, such as `::FFFF:198.51.100.1`. ==== +// Converting to a dual-stack cluster network include::modules/nw-dual-stack-convert.adoc[leveloffset=+1] + +// Converting to a single-stack cluster network include::modules/nw-dual-stack-convert-back-single-stack.adoc[leveloffset=+1]