openshift/openshift-docs
1
0
Fork 0
mirror of https://github.com/openshift/openshift-docs.git synced 2026-02-05 12:46:18 +01:00
Code Issues Releases Activity

OSDOCS-10163: adds IPv6 single config to MicroShift

Browse Source
This commit is contained in:
“Shauna Diaz”
2024-07-22 14:58:01 -04:00
committed by openshift-cherrypick-robot
parent 1960c83e11
commit f9f6540837
10 changed files with 436 additions and 6 deletions
Download Patch File Download Diff File Expand all files Collapse all files

4
_topic_maps/_topic_map_ms.yml
View File

@@ -385,8 +385,10 @@ Name: Configuring
Dir: microshift_configuring
Distros: microshift
Topics:
- Name: Using configuration tools
- Name: Using the MicroShift configuration file
File: microshift-using-config-tools
- Name: Configuring IPv6 networking
File: microshift-nw-ipv6-config
- Name: Cluster access with kubeconfig
File: microshift-cluster-access-kubeconfig
- Name: Using custom certificate authorities

26
microshift_configuring/microshift-nw-ipv6-config.adoc Normal file
View File

@@ -0,0 +1,26 @@
:_mod-docs-content-type: ASSEMBLY
[id="microshift-nw-ipv6-config"]
= Configuring IPv6 single or dual-stack networking
include::_attributes/attributes-microshift.adoc[]
:context: microshift-nw-ipv6-config
toc::[]
You can use the IPv6 networking protocol in either single-stack or dual-stack networking modes.
include::modules/microshift-nw-ipv6-concept.adoc[leveloffset=+1]
include::modules/microshift-nw-ipv6-single-stack-config.adoc[leveloffset=+1]
include::modules/microshift-nw-ipv6-dual-stack-config.adoc[leveloffset=+1]
include::modules/microshift-nw-ipv6-dual-stack-migrating-config.adoc[leveloffset=+1]
//OCP module, edit with conditionals and care
include::modules/nw-ovn-kuberentes-limitations.adoc[leveloffset=+1]
[id="additional-resources_microshift-ipv6-config_{context}"]
[role="_additional-resources"]
== Additional resources
* 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)

2
microshift_configuring/microshift-using-config-tools.adoc
View File

@@ -1,6 +1,6 @@
:_mod-docs-content-type: ASSEMBLY
[id="microshift-using-config-tools"]
= How configuration tools work
= Using the {microshift-short} configuration file
include::_attributes/attributes-microshift.adoc[]
:context: microshift-configuring

2
modules/microshift-audit-logs-config-proc.adoc
View File

@@ -1,4 +1,4 @@
// Text snippet included in the following assemblies:
// Module included in the following assemblies:
//
// * microshift_configuring/microshift-audit-logs-config.adoc

4
modules/microshift-cni-customization-matrix.adoc
View File

@@ -38,7 +38,7 @@ The following table summarizes the status of networking features and capabilitie
|IPsec encryption for intra-cluster communication|Not available|N/A
|IPv6|Not available ^[5]^|N/A
|IPv6|Supported ^[5]^|N/A
|Ingress router|Yes|Yes ^[6]^
@@ -49,5 +49,5 @@ The following table summarizes the status of networking features and capabilitie
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.
3. There is no built-in transparent proxying of egress traffic in {microshift-short}. Egress must be manually configured.
4. Setting up the firewalld service is supported by {op-system-ostree}.
5. IPv6 is not supported. IPv6 can only be used by connecting to other networks with the {microshift-short} Multus CNI plugin.
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.
6. Configure by using the {microshift-short} `config.yaml` file.

21
modules/microshift-nw-ipv6-concept.adoc Normal file
View File

@@ -0,0 +1,21 @@
// Module included in the following assemblies:
//
// * microshift_configuring/microshift-using-config-tools.adoc
:_mod-docs-content-type: CONCEPT
[id="microshift-intro-ipv6_{context}"]
= IPv6 networking with {microshift-short}
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.
* 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.
* After migrating to dual-stack networking, both new and existing pods have dual-stack networking enabled.
* 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.
* 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.
[IMPORTANT]
====
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.
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.
====

108
modules/microshift-nw-ipv6-dual-stack-config.adoc Normal file
View File

@@ -0,0 +1,108 @@
// Module included in the following assemblies:
//
// * microshift_configuring/microshift-using-config-tools.adoc
:_mod-docs-content-type: PROCEDURE
[id="microshift-configuring-ipv6-dual-stack-config_{context}"]
= Configuring IPv6 dual-stack networking before {microshift-short} starts
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.
* The first IP family in the configuration is the primary IP stack in the cluster.
* After the cluster is running with dual-stack networking, enable application pods and add-on services for dual-stack by restarting them.
[IMPORTANT]
====
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.
====
[IMPORTANT]
====
When using dual-stack networking where IPv6 is required, you cannot use IPv4-mapped IPv6 addresses, such as `::FFFF:198.51.100.1`.
====
.Prerequisites
* You installed the OpenShift CLI (`oc`).
* You have root access to the cluster.
* Your cluster uses the OVN-Kubernetes network plugin.
* The host has both IPv4 and IPv6 addresses and routes, including a default for each.
* The host has at least two L3 networks, IPv4 and IPv6.
.Procedure
. 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`.
. 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.
+
[NOTE]
====
After you create it, the `config.yaml` file takes precedence over built-in settings.
====
. If you have not started {microshift-short}, replace the default values in the `network` section of the {microshift-short} YAML with your valid values.
+
.Example dual-stack IPv6 networking configuration with network assignments
[source,yaml]
----
apiServer:
# ...
apiServer:
subjectAltNames:
- 192.168.113.117
- 2001:db9:ca7:ff::1db8
network:
clusterNetwork:
- 10.42.0.0/16
- fd01::/48 <1>
serviceNetwork:
- 10.43.0.0/16
- fd02::/112 <2>
node:
nodeIP: 192.168.113.117 <3>
nodeIPv6: 2001:db9:ca7:ff::1db8 <4>
# ...
----
<1> Specify an IPv6 `clusterNetwork` with a CIDR value that is less than `64`.
<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.
<3> Example node IP address. Must be an IPv4 address family.
<4> Example node IP address for dual-stack configuration. Must be an IPv6 address family. Configurable only with dual-stack networking.
. Complete any other configurations you require, then start {microshift-short} by running the following command:
+
[source,terminal]
----
$ sudo systemctl start microshift
----
. Restart any application pods or add-on services to enable dual-stack networking.
.Verification
. 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:
.. Retrieve the networks defined in the node resource by running the following command:
+
[source,terminal]
----
$ oc get pod -n openshift-ingress router-default-5b75594b4-w7w6s -o jsonpath='{.status.podIPs}'
----
+
.Example output
[source,text]
----
[{"ip":"10.42.0.4"},{"ip":"fd01:0:0:1::4"}]
----
.. Retrieve the networks defined by the host network pods by running the following command:
+
[source,terminal]
----
$ oc get pod -n openshift-ovn-kubernetes ovnkube-master-2fm2k -o jsonpath='{.status.podIPs}'
----
+
.Example output
[source,terminal]
----
[{"ip":"192.168.113.117"},{"ip":"2001:db9:ca7:ff::1db8"}]
----

149
modules/microshift-nw-ipv6-dual-stack-migrating-config.adoc Normal file
View File

@@ -0,0 +1,149 @@
// Module included in the following assemblies:
//
// * microshift_configuring/microshift-using-config-tools.adoc
:_mod-docs-content-type: PROCEDURE
[id="microshift-nw-ipv6-dual-stack-migrating-config_{context}"]
= Migrating a {microshift-short} cluster to IPv6 dual-stack networking
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.
* The first IP family in the configuration is the primary IP stack in the cluster.
* {microshift-short} system pods and services are automatically updated upon {microshift-short} restart.
* After the cluster is migrated to dual-stack networking and has restarted, enable workload pods and services for dual-stack networking by restarting them.
[IMPORTANT]
====
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.
====
[IMPORTANT]
====
When using dual-stack networking where IPv6 is required, you cannot use IPv4-mapped IPv6 addresses, such as `::FFFF:198.51.100.1`.
====
.Prerequisites
* You installed the OpenShift CLI (`oc`).
* You have root access to the cluster.
* Your cluster uses the OVN-Kubernetes network plugin.
* The host has both IPv4 and IPv6 addresses and routes, including a default for each.
* The host has at least two L3 networks, IPv4 and IPv6.
.Procedure
. 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`.
. 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.
+
[NOTE]
====
After you create it, the `config.yaml` file takes precedence over built-in settings.
====
. Add IPv6 configurations to the `network` section of the {microshift-short} YAML with your valid values:
+
[WARNING]
====
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.
====
+
.. Add an IPv6 configuration for a second network in the `network` section of the {microshift-short} YAML with your valid values.
.. Add network assignments to the `network` section of the {microshift-short} `config.yaml` to enable dual stack with IPv6 as secondary network.
+
.Example dual-stack IPv6 configuration with network assignments
+
[source,terminal]
----
# ...
apiServer:
subjectAltNames:
- 192.168.113.117
- 2001:db9:ca7:ff::1db8 <1>
network:
clusterNetwork:
- 10.42.0.0/16 <2>
- fd01::/48 <3>
serviceNetwork:
- 10.43.0.0/16
- fd02::/112 <4>
node:
nodeIP: 192.168.113.117 <5>
nodeIPv6: 2001:db9:ca7:ff::1db8 <6>
# ...
----
<1> The IPv6 node address.
<2> IPv4 network. Specify a `clusterNetwork` with a CIDR value that is less than `24`.
<3> IPv6 network. Specify a `clusterNetwork` with a CIDR value that is less than `64`.
<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.
<5> Example node IP address. Maintain the previous IPv4 IP address.
<6> Example node IP address. Must be an IPv6 address family.
. Complete any other configurations you require, then restart {microshift-short} by running the following command:
+
[source,terminal]
----
$ sudo systemctl restart microshift
----
. Restart any additional services and installed applications.
.Verification
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:
. Retrieve the status of the pods by running the following command:
+
[source,terminal]
----
$ oc get pod -A -o wide
----
+
.Example output
+
[source,text]
----
NAMESPACE NAME READY STATUS RESTARTS AGE IP NODE NOMINATED NODE READINESS GATES
kube-system csi-snapshot-controller-bb7cb654b-7s5ql 1/1 Running 0 46m 10.42.0.6 microshift-9 <none> <none>
kube-system csi-snapshot-webhook-95f475949-jrqv8 1/1 Running 0 46m 10.42.0.4 microshift-9 <none> <none>
openshift-dns dns-default-zxkqn 2/2 Running 0 46m 10.42.0.5 microshift-9 <none> <none>
openshift-dns node-resolver-r2h5z 1/1 Running 0 46m 192.168.113.117 microshift-9 <none> <none>
openshift-ingress router-default-5b75594b4-228z7 1/1 Running 0 2m5s 10.42.0.3 microshift-9 <none> <none>
openshift-ovn-kubernetes ovnkube-master-bltk7 4/4 Running 2 (2m32s ago) 2m36s 192.168.113.117 microshift-9 <none> <none>
openshift-ovn-kubernetes ovnkube-node-9ghgs 1/1 Running 2 (2m32s ago) 46m 192.168.113.117 microshift-9 <none> <none>
openshift-service-ca service-ca-5d7bd9db6-qgwgw 1/1 Running 0 46m 10.42.0.7 microshift-9 <none> <none>
openshift-storage lvms-operator-656cd9b59b-8rpf4 1/1 Running 0 46m 10.42.0.8 microshift-9 <none> <none>
openshift-storage vg-manager-wqmh4 1/1 Running 2 (2m39s ago) 46m 10.42.0.10 microshift-9 <none> <none>
----
. Retrieve the networks defined by the OVN-K network plugin by running the following command:
+
[source,terminal]
----
$ oc get pod -n openshift-ovn-kubernetes ovnkube-master-bltk7 -o jsonpath='{.status.podIPs}'
----
+
.Example output
[source,text]
----
[{"ip":"192.168.113.117"},{"ip":"2001:db9:ca7:ff::1db8"}]
----
. Retrieve the networks defined in the node resource by running the following command:
+
[source,terminal]
----
$ oc get pod -n openshift-ingress router-default-5b75594b4-228z7 -o jsonpath='{.status.podIPs}'
----
+
.Example output
[source,text]
----
[{"ip":"10.42.0.3"},{"ip":"fd01:0:0:1::3"}]
----
[NOTE]
====
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.
====

114
modules/microshift-nw-ipv6-single-stack-config.adoc Normal file
View File

@@ -0,0 +1,114 @@
// Module included in the following assemblies:
//
// * microshift_configuring/microshift-using-config-tools.adoc
:_mod-docs-content-type: PROCEDURE
[id="microshift-configuring-ipv6-single-stack-config_{context}"]
= Configuring IPv6 single-stack networking
You can use the IPv6 network protocol by updating the {microshift-short} service configuration file.
.Prerequisites
* You installed the OpenShift CLI (`oc`).
* You have root access to the cluster.
* Your cluster uses the OVN-Kubernetes network plugin.
* The host has an IPv6 address and IPv6 routes, including the default.
.Procedure
. 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`.
. 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.
+
[NOTE]
====
After you create it, the `config.yaml` file takes precedence over built-in settings.
====
. Replace the default values in the `network` section of the {microshift-short} YAML with your valid values.
+
.Example single-stack IPv6 networking configuration
[source,yaml]
----
apiServer:
# ...
network:
clusterNetwork:
- fd01::/48 <1>
serviceNetwork:
- fd02::/112 <2>
node:
nodeIP: 2600:1f14:1c48:ee00:2d76:3190:5bc2:5aef <3>
# ...
----
<1> Specify a `clusterNetwork` with a CIDR value that is less than `64`.
<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.
<3> Example node IP address. Valid values are IP addresses in the IPv6 address family. You must only specify an IPv6 address when an IPv4 network is also present. If an IPv4 network is not present, the {microshift-short} service automatically fills in this value upon restart.
. Complete any other configurations you require, then start {microshift-short} by running the following command:
+
[source,terminal]
----
$ sudo systemctl start microshift
----
.Verification
. Retrieve the networks defined in the node resource by running the following command:
+
[source,terminal]
----
$ oc get node -o jsonpath='{.items[].spec.podCIDRs[]}'
----
+
.Example output
[source,text]
----
fd01::/48
----
. Retrieve the status of the pods by running the following command:
+
[source,terminal]
----
$ oc get pod -A -o wide
----
+
.Example output
+
[source,text]
----
NAMESPACE NAME READY STATUS RESTARTS AGE IP NODE NOMINATED NODE READINESS GATES
kube-system csi-snapshot-controller-bb7cb654b-rqrt6 1/1 Running 0 65s fd01:0:0:1::5 microshift-9 <none> <none>
kube-system csi-snapshot-webhook-95f475949-nbz8x 1/1 Running 0 61s fd01:0:0:1::6 microshift-9 <none> <none>
openshift-dns dns-default-cjn66 2/2 Running 0 62s fd01:0:0:1::9 microshift-9 <none> <none>
openshift-dns node-resolver-ppnjb 1/1 Running 0 63s 2001:db9:ca7:ff::1db8 microshift-9 <none> <none>
openshift-ingress router-default-6d97d7b8b6-wdtmg 1/1 Running 0 61s fd01:0:0:1::8 microshift-9 <none> <none>
openshift-ovn-kubernetes ovnkube-master-gfvp5 4/4 Running 0 63s 2001:db9:ca7:ff::1db8 microshift-9 <none> <none>
openshift-ovn-kubernetes ovnkube-node-bnpjh 1/1 Running 0 63s 2001:db9:ca7:ff::1db8 microshift-9 <none> <none>
openshift-service-ca service-ca-5d7bd9db6-j25bd 1/1 Running 0 60s fd01:0:0:1::4 microshift-9 <none> <none>
openshift-storage lvms-operator-656cd9b59b-bwr47 1/1 Running 0 63s fd01:0:0:1::7 microshift-9 <none> <none>
openshift-storage vg-manager-f7dmk 1/1 Running 0 27s fd01:0:0:1::a microshift-9 <none> <none>
----
. Retrieve the status of services by running the following command:
+
[source,terminal]
----
$ oc get svc -A
----
+
.Example output
[source,terminal]
----
NAMESPACE NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE
default kubernetes ClusterIP fd02::1 <none> 443/TCP 3m42s
kube-system csi-snapshot-webhook ClusterIP fd02::4c4f <none> 443/TCP 3m20s
openshift-dns dns-default ClusterIP fd02::a <none> 53/UDP,53/TCP,9154/TCP 2m58s
openshift-ingress router-default LoadBalancer fd02::f2e6 2001:db9:ca7:ff::1db8,fd01:0:0:1::2,fd02::1:0,fd69::2 80:31133/TCP,443:31996/TCP 2m58s
openshift-ingress router-internal-default ClusterIP fd02::c55e <none> 80/TCP,443/TCP,1936/TCP 2m58s
openshift-storage lvms-operator-metrics-service ClusterIP fd02::7afb <none> 443/TCP 2m58s
openshift-storage lvms-webhook-service ClusterIP fd02::d8dd <none> 443/TCP 2m58s
openshift-storage vg-manager-metrics-service ClusterIP fd02::fc1 <none> 443/TCP 2m58s
----

12
modules/nw-ovn-kuberentes-limitations.adoc
View File

@@ -1,6 +1,7 @@
// Module included in the following assemblies:
//
// * networking/ovn_kubernetes_network_provider/about-ovn-kubernetes.adoc
// * microshift_networking/microshift-nw-ipv6-config.adoc
[id="nw-ovn-kubernetes-limitations_{context}"]
= OVN-Kubernetes IPv6 and dual-stack limitations
@@ -8,7 +9,12 @@
The OVN-Kubernetes network plugin has the following limitations:
// The foll limitation is also recorded in the installation section.
ifndef::microshift[]
* For clusters configured for dual-stack networking, both IPv4 and IPv6 traffic must use the same network interface as the default gateway.
endif::microshift[]
ifdef::microshift[]
* For a cluster configured for dual-stack networking, both IPv4 and IPv6 traffic must use the same network interface as the default gateway.
endif::microshift[]
If this requirement is not met, pods on the host in the `ovnkube-node` daemon set enter the `CrashLoopBackOff` state.
If you display a pod with a command such as `oc get pod -n openshift-ovn-kubernetes -l app=ovnkube-node -o yaml`, the `status` field contains more than one message about the default gateway, as shown in the following output:
+
@@ -20,8 +26,12 @@ F1006 16:09:50.985939 60651 ovnkube.go:130] multiple gateway interfaces detect
----
+
The only resolution is to reconfigure the host networking so that both IP families use the same network interface for the default gateway.
ifndef::microshift[]
* For clusters configured for dual-stack networking, both the IPv4 and IPv6 routing tables must contain the default gateway.
endif::microshift[]
ifdef::microshift[]
* For a cluster configured for dual-stack networking, both the IPv4 and IPv6 routing tables must contain the default gateway.
endif::microshift[]
If this requirement is not met, pods on the host in the `ovnkube-node` daemon set enter the `CrashLoopBackOff` state.
If you display a pod with a command such as `oc get pod -n openshift-ovn-kubernetes -l app=ovnkube-node -o yaml`, the `status` field contains more than one message about the default gateway, as shown in the following output:
+