Skip to content

Commit f06721a

Browse files
ShaunaDiazShaunaDiaz
authored
Merge pull request #79226 from ShaunaDiaz/OSDOCS-10163
OSDOCS-10163: adds IPv6 config to MicroShift
2 parents 6c78441 + 10b894a commit f06721a

10 files changed

+436
-6
lines changed

‎_topic_maps/_topic_map_ms.yml

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -385,8 +385,10 @@ Name: Configuring
385385
Dir: microshift_configuring
386386
Distros: microshift
387387
Topics:
388-
- Name: Using configuration tools
388+
- Name: Using the MicroShift configuration file
389389
File: microshift-using-config-tools
390+
- Name: Configuring IPv6 networking
391+
File: microshift-nw-ipv6-config
390392
- Name: Cluster access with kubeconfig
391393
File: microshift-cluster-access-kubeconfig
392394
- Name: Using custom certificate authorities

‎microshift_configuring/microshift-nw-ipv6-config.adoc

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
:_mod-docs-content-type: ASSEMBLY
2+
[id="microshift-nw-ipv6-config"]
3+
= Configuring IPv6 single or dual-stack networking
4+
include::_attributes/attributes-microshift.adoc[]
5+
:context: microshift-nw-ipv6-config
6+
7+
toc::[]
8+
9+
You can use the IPv6 networking protocol in either single-stack or dual-stack networking modes.
10+
11+
include::modules/microshift-nw-ipv6-concept.adoc[leveloffset=+1]
12+
13+
include::modules/microshift-nw-ipv6-single-stack-config.adoc[leveloffset=+1]
14+
15+
include::modules/microshift-nw-ipv6-dual-stack-config.adoc[leveloffset=+1]
16+
17+
include::modules/microshift-nw-ipv6-dual-stack-migrating-config.adoc[leveloffset=+1]
18+
19+
//OCP module, edit with conditionals and care
20+
include::modules/nw-ovn-kuberentes-limitations.adoc[leveloffset=+1]
21+
22+
[id="additional-resources_microshift-ipv6-config_{context}"]
23+
[role="_additional-resources"]
24+
== Additional resources
25+
26+
* link:https://docs.redhat.com/en/documentation/red_hat_enterprise_linux/9/html/configuring_and_managing_networking/using-networkmanager-to-disable-ipv6-for-a-specific-connection_configuring-and-managing-networking[Using NetworkManager to disable IPv6 for a specific connection] (Red Hat Enterprise Linux documentation)

‎microshift_configuring/microshift-using-config-tools.adoc

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
:_mod-docs-content-type: ASSEMBLY
22
[id="microshift-using-config-tools"]
3-
= How configuration tools work
3+
= Using the {microshift-short} configuration file
44
include::_attributes/attributes-microshift.adoc[]
55
:context: microshift-configuring
66

‎modules/microshift-audit-logs-config-proc.adoc

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
// Text snippet included in the following assemblies:
1+
// Module included in the following assemblies:
22
//
33
// * microshift_configuring/microshift-audit-logs-config.adoc
44

‎modules/microshift-cni-customization-matrix.adoc

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -38,7 +38,7 @@ The following table summarizes the status of networking features and capabilitie
3838

3939
|IPsec encryption for intra-cluster communication|Not available|N/A
4040

41-
|IPv6|Not available ^[5]^|N/A
41+
|IPv6|Supported ^[5]^|N/A
4242

4343
|Ingress router|Yes|Yes ^[6]^
4444

@@ -49,5 +49,5 @@ The following table summarizes the status of networking features and capabilitie
4949
2. You can use the multicast DNS protocol (mDNS) to allow name resolution and service discovery within a Local Area Network (LAN) using multicast exposed on the `5353/UDP` port.
5050
3. There is no built-in transparent proxying of egress traffic in {microshift-short}. Egress must be manually configured.
5151
4. Setting up the firewalld service is supported by {op-system-ostree}.
52-
5. IPv6 is not supported. IPv6 can only be used by connecting to other networks with the {microshift-short} Multus CNI plugin.
52+
5. IPv6 is supported in both single-stack and dual-stack networks with the OVN-Kubernetes network plugin. IPv6 can also be used by connecting to other networks with the {microshift-short} Multus CNI plugin.
5353
6. Configure by using the {microshift-short} `config.yaml` file.

‎modules/microshift-nw-ipv6-concept.adoc

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * microshift_configuring/microshift-using-config-tools.adoc
4+
5+
:_mod-docs-content-type: CONCEPT
6+
[id="microshift-intro-ipv6_{context}"]
7+
= IPv6 networking with {microshift-short}
8+
9+
The {microshift-short} service defaults to IPv4 address families cluster-wide. However, IPv6 single-stack and IPv4/IPv6 dual-stack networking is available on supported platforms.
10+
11+
* When you set the values for IPv6 in the {microshift-short} configuration file and restart the service, settings managed by the OVN-Kubernetes network plugin are updated automatically.
12+
* After migrating to dual-stack networking, both new and existing pods have dual-stack networking enabled.
13+
* If you require cluster-wide IPv6 access, such as for the control plane and other services, use the following configuration examples. The {microshift-short} Multus Container Network Interface (CNI) plugin can enable IPv6 for pods.
14+
* For dual-stack networking, each {microshift-short} cluster network and service network supports up to two values in the cluster and service network configuration parameters.
15+
16+
[IMPORTANT]
17+
====
18+
Plan for IPv6 before starting {microshift-short} for the first time. Switching a cluster to and from different IP families is not supported unless you are migrating a cluster from default single-stack to dual-stack networking.
19+
20+
If you configure your networking for either IPv6 single stack or IPv4/IPv6 dual stack, you must restart application pods and services. Otherwise pods and services remain configured with the default IP family.
21+
====

‎modules/microshift-nw-ipv6-dual-stack-config.adoc

Lines changed: 108 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,108 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * microshift_configuring/microshift-using-config-tools.adoc
4+
5+
:_mod-docs-content-type: PROCEDURE
6+
[id="microshift-configuring-ipv6-dual-stack-config_{context}"]
7+
= Configuring IPv6 dual-stack networking before {microshift-short} starts
8+
9+
You can configure your {microshift-short} cluster to run on dual-stack networking that supports IPv4 and IPv6 address families by using the configuration file before starting the service.
10+
11+
* The first IP family in the configuration is the primary IP stack in the cluster.
12+
* After the cluster is running with dual-stack networking, enable application pods and add-on services for dual-stack by restarting them.
13+
14+
[IMPORTANT]
15+
====
16+
The OVN-Kubernetes network plugin requires that both IPv4 and IPv6 default routes be on the same network device. IPv4 and IPv6 default routes on separate network devices is not supported.
17+
====
18+
19+
[IMPORTANT]
20+
====
21+
When using dual-stack networking where IPv6 is required, you cannot use IPv4-mapped IPv6 addresses, such as `::FFFF:198.51.100.1`.
22+
====
23+
24+
.Prerequisites
25+
26+
* You installed the OpenShift CLI (`oc`).
27+
* You have root access to the cluster.
28+
* Your cluster uses the OVN-Kubernetes network plugin.
29+
* The host has both IPv4 and IPv6 addresses and routes, including a default for each.
30+
* The host has at least two L3 networks, IPv4 and IPv6.
31+
32+
.Procedure
33+
34+
. If you have not done so, make a copy of the provided `config.yaml.default` file in the `/etc/microshift/` directory, renaming it `config.yaml`.
35+
36+
. Keep the new {microshift-short} `config.yaml` in the `/etc/microshift/` directory. Your `config.yaml` file is read every time the {microshift-short} service starts.
37+
+
38+
[NOTE]
39+
====
40+
After you create it, the `config.yaml` file takes precedence over built-in settings.
41+
====
42+
43+
. If you have not started {microshift-short}, replace the default values in the `network` section of the {microshift-short} YAML with your valid values.
44+
+
45+
.Example dual-stack IPv6 networking configuration with network assignments
46+
[source,yaml]
47+
----
48+
apiServer:
49+
# ...
50+
apiServer:
51+
subjectAltNames:
52+
- 192.168.113.117
53+
- 2001:db9:ca7:ff::1db8
54+
network:
55+
clusterNetwork:
56+
- 10.42.0.0/16
57+
- fd01::/48 <1>
58+
serviceNetwork:
59+
- 10.43.0.0/16
60+
- fd02::/112 <2>
61+
node:
62+
nodeIP: 192.168.113.117 <3>
63+
nodeIPv6: 2001:db9:ca7:ff::1db8 <4>
64+
# ...
65+
----
66+
<1> Specify an IPv6 `clusterNetwork` with a CIDR value that is less than `64`.
67+
<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.
68+
<3> Example node IP address. Must be an IPv4 address family.
69+
<4> Example node IP address for dual-stack configuration. Must be an IPv6 address family. Configurable only with dual-stack networking.
70+
71+
. Complete any other configurations you require, then start {microshift-short} by running the following command:
72+
+
73+
[source,terminal]
74+
----
75+
$ sudo systemctl start microshift
76+
----
77+
78+
. Restart any application pods or add-on services to enable dual-stack networking.
79+
80+
.Verification
81+
82+
. You can verify that all of the system services and pods to have two IP addresses, one for each family, by using the following steps:
83+
84+
.. Retrieve the networks defined in the node resource by running the following command:
85+
+
86+
[source,terminal]
87+
----
88+
$ oc get pod -n openshift-ingress router-default-5b75594b4-w7w6s -o jsonpath='{.status.podIPs}'
89+
----
90+
+
91+
.Example output
92+
[source,text]
93+
----
94+
[{"ip":"10.42.0.4"},{"ip":"fd01:0:0:1::4"}]
95+
----
96+
97+
.. Retrieve the networks defined by the host network pods by running the following command:
98+
+
99+
[source,terminal]
100+
----
101+
$ oc get pod -n openshift-ovn-kubernetes ovnkube-master-2fm2k -o jsonpath='{.status.podIPs}'
102+
----
103+
+
104+
.Example output
105+
[source,terminal]
106+
----
107+
[{"ip":"192.168.113.117"},{"ip":"2001:db9:ca7:ff::1db8"}]
108+
----

‎modules/microshift-nw-ipv6-dual-stack-migrating-config.adoc

Lines changed: 149 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,149 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * microshift_configuring/microshift-using-config-tools.adoc
4+
5+
:_mod-docs-content-type: PROCEDURE
6+
[id="microshift-nw-ipv6-dual-stack-migrating-config_{context}"]
7+
= Migrating a {microshift-short} cluster to IPv6 dual-stack networking
8+
9+
You can convert a single-stack cluster to dual-stack cluster networking that supports IPv4 and IPv6 address families by setting two entries in the service and cluster network parameters in the {microshift-short} configuration file.
10+
11+
* The first IP family in the configuration is the primary IP stack in the cluster.
12+
* {microshift-short} system pods and services are automatically updated upon {microshift-short} restart.
13+
* After the cluster is migrated to dual-stack networking and has restarted, enable workload pods and services for dual-stack networking by restarting them.
14+
15+
[IMPORTANT]
16+
====
17+
The OVN-Kubernetes network plugin requires that both IPv4 and IPv6 default routes be on the same network device. IPv4 and IPv6 default routes on separate network devices is not supported.
18+
====
19+
20+
[IMPORTANT]
21+
====
22+
When using dual-stack networking where IPv6 is required, you cannot use IPv4-mapped IPv6 addresses, such as `::FFFF:198.51.100.1`.
23+
====
24+
25+
.Prerequisites
26+
27+
* You installed the OpenShift CLI (`oc`).
28+
* You have root access to the cluster.
29+
* Your cluster uses the OVN-Kubernetes network plugin.
30+
* The host has both IPv4 and IPv6 addresses and routes, including a default for each.
31+
* The host has at least two L3 networks, IPv4 and IPv6.
32+
33+
.Procedure
34+
35+
. If you have not done so, make a copy of the provided `config.yaml.default` file in the `/etc/microshift/` directory, renaming it `config.yaml`.
36+
37+
. Keep the new {microshift-short} `config.yaml` in the `/etc/microshift/` directory. Your `config.yaml` file is read every time the {microshift-short} service starts.
38+
+
39+
[NOTE]
40+
====
41+
After you create it, the `config.yaml` file takes precedence over built-in settings.
42+
====
43+
44+
. Add IPv6 configurations to the `network` section of the {microshift-short} YAML with your valid values:
45+
+
46+
[WARNING]
47+
====
48+
You must keep the same first entry across restarts and migrations. This is true for any migration: single-to-dual stack, or dual-to-single stack. A complete wipe of the etcd database is required if a change to the first entry is needed. This might result in application data loss and is not supported.
49+
====
50+
+
51+
.. Add an IPv6 configuration for a second network in the `network` section of the {microshift-short} YAML with your valid values.
52+
53+
.. Add network assignments to the `network` section of the {microshift-short} `config.yaml` to enable dual stack with IPv6 as secondary network.
54+
+
55+
.Example dual-stack IPv6 configuration with network assignments
56+
+
57+
[source,terminal]
58+
----
59+
# ...
60+
apiServer:
61+
subjectAltNames:
62+
- 192.168.113.117
63+
- 2001:db9:ca7:ff::1db8 <1>
64+
network:
65+
clusterNetwork:
66+
- 10.42.0.0/16 <2>
67+
- fd01::/48 <3>
68+
serviceNetwork:
69+
- 10.43.0.0/16
70+
- fd02::/112 <4>
71+
node:
72+
nodeIP: 192.168.113.117 <5>
73+
nodeIPv6: 2001:db9:ca7:ff::1db8 <6>
74+
# ...
75+
----
76+
<1> The IPv6 node address.
77+
<2> IPv4 network. Specify a `clusterNetwork` with a CIDR value that is less than `24`.
78+
<3> IPv6 network. Specify a `clusterNetwork` with a CIDR value that is less than `64`.
79+
<4> 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.
80+
<5> Example node IP address. Maintain the previous IPv4 IP address.
81+
<6> Example node IP address. Must be an IPv6 address family.
82+
83+
. Complete any other configurations you require, then restart {microshift-short} by running the following command:
84+
+
85+
[source,terminal]
86+
----
87+
$ sudo systemctl restart microshift
88+
----
89+
90+
. Restart any additional services and installed applications.
91+
92+
.Verification
93+
94+
You can verify that all of the system services and pods to have two IP addresses, one for each family, by using the following steps:
95+
96+
. Retrieve the status of the pods by running the following command:
97+
+
98+
[source,terminal]
99+
----
100+
$ oc get pod -A -o wide
101+
----
102+
+
103+
.Example output
104+
+
105+
[source,text]
106+
----
107+
NAMESPACE NAME READY STATUS RESTARTS AGE IP NODE NOMINATED NODE READINESS GATES
108+
kube-system csi-snapshot-controller-bb7cb654b-7s5ql 1/1 Running 0 46m 10.42.0.6 microshift-9 <none> <none>
109+
kube-system csi-snapshot-webhook-95f475949-jrqv8 1/1 Running 0 46m 10.42.0.4 microshift-9 <none> <none>
110+
openshift-dns dns-default-zxkqn 2/2 Running 0 46m 10.42.0.5 microshift-9 <none> <none>
111+
openshift-dns node-resolver-r2h5z 1/1 Running 0 46m 192.168.113.117 microshift-9 <none> <none>
112+
openshift-ingress router-default-5b75594b4-228z7 1/1 Running 0 2m5s 10.42.0.3 microshift-9 <none> <none>
113+
openshift-ovn-kubernetes ovnkube-master-bltk7 4/4 Running 2 (2m32s ago) 2m36s 192.168.113.117 microshift-9 <none> <none>
114+
openshift-ovn-kubernetes ovnkube-node-9ghgs 1/1 Running 2 (2m32s ago) 46m 192.168.113.117 microshift-9 <none> <none>
115+
openshift-service-ca service-ca-5d7bd9db6-qgwgw 1/1 Running 0 46m 10.42.0.7 microshift-9 <none> <none>
116+
openshift-storage lvms-operator-656cd9b59b-8rpf4 1/1 Running 0 46m 10.42.0.8 microshift-9 <none> <none>
117+
openshift-storage vg-manager-wqmh4 1/1 Running 2 (2m39s ago) 46m 10.42.0.10 microshift-9 <none> <none>
118+
----
119+
120+
. Retrieve the networks defined by the OVN-K network plugin by running the following command:
121+
+
122+
[source,terminal]
123+
----
124+
$ oc get pod -n openshift-ovn-kubernetes ovnkube-master-bltk7 -o jsonpath='{.status.podIPs}'
125+
----
126+
+
127+
.Example output
128+
[source,text]
129+
----
130+
[{"ip":"192.168.113.117"},{"ip":"2001:db9:ca7:ff::1db8"}]
131+
----
132+
133+
. Retrieve the networks defined in the node resource by running the following command:
134+
+
135+
[source,terminal]
136+
----
137+
$ oc get pod -n openshift-ingress router-default-5b75594b4-228z7 -o jsonpath='{.status.podIPs}'
138+
----
139+
+
140+
.Example output
141+
[source,text]
142+
----
143+
[{"ip":"10.42.0.3"},{"ip":"fd01:0:0:1::3"}]
144+
----
145+
146+
[NOTE]
147+
====
148+
To return to single-stack networking, you can remove the second entry to the networks and return to the single stack that was configured before migrating to dual-stack.
149+
====

0 commit comments

Comments
 (0)