Converting to IPv4/IPv6 dual stack networking - OVN-Kubernetes network plugin | Networking

Converting to a dual-stack cluster network
Converting to a single-stack cluster network

To enable IPv4 and IPv6 on your cluster network in OKD, you can convert a single-stack cluster to dual-stack networking. After conversion, new and existing pods can use both address families when you re-create workloads as needed.

When using dual-stack networking where IPv6 is required, you cannot use IPv4-mapped IPv6 addresses, such as ::FFFF:198.51.100.1.

Additional resources

OVN-Kubernetes purpose

Converting to a dual-stack cluster network

To convert your cluster network from IPv4 single-stack to dual-stack in OKD, you can patch the cluster network and, on installer-provisioned infrastructure, the infrastructure custom resources. You must re-create existing pods after conversion to receive IPv6 addresses.

As a cluster administrator, you can convert your single-stack cluster network to a dual-stack cluster network.

After converting your cluster to use dual-stack networking, you must re-create any existing pods for them to receive IPv6 addresses, because only new pods are assigned IPv6 addresses.

Converting a single-stack cluster network to a dual-stack cluster network consists of creating patches and applying them to the network and infrastructure of the cluster. You can convert to a dual-stack cluster network for a cluster that runs on either installer-provisioned infrastructure or user-provisioned infrastructure.

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.

On installer-provisioned infrastructure only, if you need to add IPv6 virtual IPs (VIPs) for API and Ingress services to an existing dual-stack-configured cluster, you need to patch only the infrastructure and not the network for the cluster.

If you already upgraded your cluster to OKD 4.16 or later and you need to convert the single-stack cluster network to a dual-stack cluster network, you must specify an existing IPv4 machineNetwork network configuration from the install-config.yaml file for API and Ingress services in the YAML configuration patch file. This configuration ensures that IPv4 traffic exists in the same network interface as the default gateway.

The following example adds an IPv4 address block for the machineNetwork network:

- op: add
  path: /spec/platformSpec/baremetal/machineNetworks/-
  value: 192.168.1.0/24
  # ...

where:

/spec/platformSpec/baremetal/machineNetworks/-: Specifies an address block for the machineNetwork network where your machines operate. You must select both API and Ingress IP addresses for the machine network.

Prerequisites

You installed the OpenShift CLI (oc).
You are logged in to the cluster with a user with cluster-admin privileges.
Your cluster uses the OVN-Kubernetes network plugin.
The cluster nodes have IPv6 addresses.
You have configured an IPv6-enabled router based on your infrastructure.

Procedure

To specify IPv6 address blocks for cluster and service networks, create a YAML configuration patch file that has a similar configuration to the following example:
```
- op: add
  path: /spec/clusterNetwork/-
  value:
    cidr: fd01::/48
    hostPrefix: 64
- op: add
  path: /spec/serviceNetwork/-
  value: fd02::/112
```
where:

/spec/clusterNetwork/-

Specifies an object with the cidr and hostPrefix parameters. 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.

/spec/serviceNetwork/-

Specifies 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.
Patch the cluster network configuration by entering the following command in your CLI:
```
$ oc patch network.config.openshift.io cluster \
  --type='json' --patch-file <file>.yaml
```
For <file>, specify the name of the YAML file you created.
Example output
```
network.config.openshift.io/cluster patched
```
On installer-provisioned infrastructure where you added IPv6 VIPs for API and Ingress services, complete the following steps:
1. Specify IPv6 VIPs for API and Ingress services for your cluster. Create a YAML configuration patch file that has a similar configuration to the following example:
  - op: add path: /spec/platformSpec/baremetal/machineNetworks/- value: fd2e:6f44:5dd8::/64 - op: add path: /spec/platformSpec/baremetal/apiServerInternalIPs/- value: fd2e:6f44:5dd8::4 - op: add path: /spec/platformSpec/baremetal/ingressIPs/- value: fd2e:6f44:5dd8::5
  where:
  
  /spec/platformSpec/baremetal/machineNetworks/-
  
  Specifies an address block for the machineNetwork network where your machines operate. You must select both API and Ingress IP addresses for the machine network.
  
  /spec/platformSpec/baremetal/apiServerInternalIPs/-
  
  Specifies each file path according to your platform. The example demonstrates a file path on a bare metal platform.
2. Patch the infrastructure by entering the following command in your CLI:
  $ oc patch infrastructure cluster \ --type='json' --patch-file <file>.yaml
  For <file>, specify the name of the YAML file you created.
  Example output
  infrastructure/cluster patched

Verification

Show the cluster network configuration by entering the following command in your CLI:
```
$ 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

# ...
Status:
  Cluster Network:
    Cidr:               10.128.0.0/14
    Host Prefix:        23
    Cidr:               fd01::/48
    Host Prefix:        64
  Cluster Network MTU:  1400
  Network Type:         OVNKubernetes
  Service Network:
    172.30.0.0/16
    fd02::/112
# ...

Complete the following additional tasks for a cluster that runs on installer-provisioned infrastructure:

Show the cluster infrastructure configuration by entering the following command in your CLI:
```
$ oc describe infrastructure
```

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

# ...
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
# ...

Converting to a single-stack cluster network

To revert dual-stack networking in OKD, you can edit the cluster network configuration and remove the IPv4 or IPv6 blocks you added during dual-stack conversion. You can convert back only to the same single-stack family you had before dual-stack (IPv4 or IPv6).

If you originally converted your IPv4 single-stack cluster network to a dual-stack cluster, you can convert only back to the IPv4 single-stack cluster and not an IPv6 single-stack cluster network. The same restriction applies for converting back to an IPv6 single-stack cluster network.

Prerequisites

You installed the OpenShift CLI (oc).
You are logged in to the cluster with a user with cluster-admin privileges.
Your cluster uses the OVN-Kubernetes network plugin.
The cluster nodes have IPv6 addresses.
You have enabled dual-stack networking.

Procedure

Edit the networks.config.openshift.io custom resource (CR) by running the following command:
```
$ oc edit networks.config.openshift.io
```
Remove the IPv4 or IPv6 configuration that you added to the cidr and the hostPrefix parameters from completing the "Converting to a dual-stack cluster network " procedure steps.

Converting to IPv4/IPv6 dual-stack networking

Converting to a dual-stack cluster network

Converting to a single-stack cluster network