Skip to content

OSDOCS-8931: Detail step for adding IPv6 to existing dual-stack clusters #75232

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
May 9, 2024
Merged

OSDOCS-8931: Detail step for adding IPv6 to existing dual-stack clusters #75232

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
102 changes: 84 additions & 18 deletions modules/nw-dual-stack-convert.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,11 +2,13 @@
[id="nw-dual-stack-convert_{context}"]
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This doc set should link to https://docs.openshift.com/container-platform/4.15/installing/installing_bare_metal_ipi/ipi-install-installation-workflow.html#modifying-install-config-for-dual-stack-network_ipi-install-installation-workflow ?

= 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
Expand All @@ -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
Expand All @@ -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 <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 <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
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Do these two verification steps have to be done in order? If the order doesn't matter, switch the ordered list to a bulleted list :)

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes, they are separate because the patch commands are different.


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
Expand All @@ -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
# ...
----
13 changes: 8 additions & 5 deletions networking/ovn_kubernetes_network_provider/converting-to-dual-stack.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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]