×

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.

Clusters provisioned on bare metal, IBM Power®, IBM Z® infrastructure, single-node OpenShift, and VMware vSphere support dual-stack networking.

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

As a cluster administrator, you can convert your single-stack cluster network to a dual-stack cluster network. After converting to a dual-stack network, 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.

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.

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 cluster’s infrastructure and not the cluster’s network.

If you already upgraded your cluster to OpenShift Container Platform 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.

Example YAML configuration file with an added IPv4 address block for the machineNetwork network
- op: add
  path: /spec/platformSpec/baremetal/machineNetworks/- (1)
  value: 192.168.1.0/24
  # ...
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.
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
  1. 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: (1)
        cidr: fd01::/48
        hostPrefix: 64
    - op: add
      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 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.
  2. Patch the cluster network configuration by entering the following command in your CLI:

    $ 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
    network.config.openshift.io/cluster patched
  3. To 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/- (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.
  4. Patch the cluster’s infrastructure by entering the following command in your CLI:

    $ oc patch infrastructure cluster \(1)
      --type='json' --patch-file <file>.yaml
    1 Where file specifies the name of your created YAML file.
    Example output
    infrastructure/cluster patched
Verification
  1. Show the cluster network configuration by entering the following command in your CLI:

    $ oc describe network
  2. 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
    # ...
  3. Show the cluster infrastructure configuration by entering the following command in your CLI:

    $ oc describe network
  4. 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

As a cluster administrator, you can convert your dual-stack cluster network to a 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
  1. Edit the networks.config.openshift.io custom resource (CR) by running the following command:

    $ oc edit networks.config.openshift.io
  2. Remove the IPv6 specific configuration that you have added to the cidr and hostPrefix fields in the previous procedure.