Dual-stack support with kubeadm

FEATURE STATE: Kubernetes v1.23 [stable]

Your Kubernetes cluster includes dual-stack networking, which means that cluster networking lets you use either address family. In a cluster, the control plane can assign both an IPv4 address and an IPv6 address to a single Pod or a Service.

Before you begin

You need to have installed the kubeadm tool, following the steps from Installing kubeadm.

For each server that you want to use as a node, make sure it allows IPv6 forwarding. On Linux, you can set this by running run sysctl -w net.ipv6.conf.all.forwarding=1 as the root user on each server.

You need to have an IPv4 and and IPv6 address range to use. Cluster operators typically use private address ranges for IPv4. For IPv6, a cluster operator typically chooses a global unicast address block from within 2000::/3, using a range that is assigned to the operator. You don’t have to route the cluster’s IP address ranges to the public internet.

The size of the IP address allocations should be suitable for the number of Pods and Services that you are planning to run.

Note: If you are upgrading an existing cluster with the kubeadm upgrade command, kubeadm does not support making modifications to the pod IP address range (“cluster CIDR”) nor to the cluster’s Service address range (“Service CIDR”).

Create a dual-stack cluster

To create a dual-stack cluster with kubeadm init you can pass command line arguments similar to the following example:

  1. # These address ranges are examples
  2. kubeadm init --pod-network-cidr=10.244.0.0/16,2001:db8:42:0::/56 --service-cidr=10.96.0.0/16,2001:db8:42:1::/112

To make things clearer, here is an example kubeadm configuration file kubeadm-config.yaml for the primary dual-stack control plane node.

  1. ---
  2. apiVersion: kubeadm.k8s.io/v1beta3
  3. kind: ClusterConfiguration
  4. networking:
  5.   podSubnet: 10.244.0.0/16,2001:db8:42:0::/56
  6.   serviceSubnet: 10.96.0.0/16,2001:db8:42:1::/112
  7. ---
  8. apiVersion: kubeadm.k8s.io/v1beta3
  9. kind: InitConfiguration
  10. localAPIEndpoint:
  11.   advertiseAddress: "10.100.0.1"
  12.   bindPort: 6443
  13. nodeRegistration:
  14.   kubeletExtraArgs:
  15.     node-ip: 10.100.0.2,fd00:1:2:3::2

advertiseAddress in InitConfiguration specifies the IP address that the API Server will advertise it is listening on. The value of advertiseAddress equals the --apiserver-advertise-address flag of kubeadm init.

Run kubeadm to initiate the dual-stack control plane node:

  1. kubeadm init --config=kubeadm-config.yaml

The kube-controller-manager flags --node-cidr-mask-size-ipv4|--node-cidr-mask-size-ipv6 are set with default values. See configure IPv4/IPv6 dual stack.

Note: The --apiserver-advertise-address flag does not support dual-stack.

Join a node to dual-stack cluster

Before joining a node, make sure that the node has IPv6 routable network interface and allows IPv6 forwarding.

Here is an example kubeadm configuration file kubeadm-config.yaml for joining a worker node to the cluster.

  1. apiVersion: kubeadm.k8s.io/v1beta3
  2. kind: JoinConfiguration
  3. discovery:
  4.   bootstrapToken:
  5.     apiServerEndpoint: 10.100.0.1:6443
  6.     token: "clvldh.vjjwg16ucnhp94qr"
  7.     caCertHashes:
  8.     - "sha256:a4863cde706cfc580a439f842cc65d5ef112b7b2be31628513a9881cf0d9fe0e"
  9.     # change auth info above to match the actual token and CA certificate hash for your cluster
  10. nodeRegistration:
  11.   kubeletExtraArgs:
  12.     node-ip: 10.100.0.3,fd00:1:2:3::3

Also, here is an example kubeadm configuration file kubeadm-config.yaml for joining another control plane node to the cluster.

  1. apiVersion: kubeadm.k8s.io/v1beta3
  2. kind: JoinConfiguration
  3. controlPlane:
  4.   localAPIEndpoint:
  5.     advertiseAddress: "10.100.0.2"
  6.     bindPort: 6443
  7. discovery:
  8.   bootstrapToken:
  9.     apiServerEndpoint: 10.100.0.1:6443
  10.     token: "clvldh.vjjwg16ucnhp94qr"
  11.     caCertHashes:
  12.     - "sha256:a4863cde706cfc580a439f842cc65d5ef112b7b2be31628513a9881cf0d9fe0e"
  13.     # change auth info above to match the actual token and CA certificate hash for your cluster
  14. nodeRegistration:
  15.   kubeletExtraArgs:
  16.     node-ip: 10.100.0.4,fd00:1:2:3::4

advertiseAddress in JoinConfiguration.controlPlane specifies the IP address that the API Server will advertise it is listening on. The value of advertiseAddress equals the --apiserver-advertise-address flag of kubeadm join.

  1. kubeadm join --config=kubeadm-config.yaml

Create a single-stack cluster

Note: Dual-stack support doesn’t mean that you need to use dual-stack addressing. You can deploy a single-stack cluster that has the dual-stack networking feature enabled.

To make things more clear, here is an example kubeadm configuration file kubeadm-config.yaml for the single-stack control plane node.

  1. apiVersion: kubeadm.k8s.io/v1beta3
  2. kind: ClusterConfiguration
  3. networking:
  4.   podSubnet: 10.244.0.0/16
  5.   serviceSubnet: 10.96.0.0/16

What’s next