Dual-stack networking — IPv4 and IPv6 side by side

Dual-stack networking lets a Pod have both an IPv4 and an IPv6 address. The cluster runs both stacks simultaneously. The kubelet and the CNI plugin must support dual-stack; the cluster operator must size both IPv4 and IPv6 pools. This lesson walks the dual-stack configuration, the failure modes, and the operational discipline of evolving from IPv4-only to dual-stack.

What dual-stack is

A dual-stack cluster gives every Pod two IP addresses: one IPv4 and one IPv6. The Pod’s status has both:

status:
  podIPs:
    - ip: 10.244.1.5
    - ip: 2001:db8:1::5

The Pod can communicate over either stack. The Service can route to either address. The cluster’s DNS serves both A and AAAA records.

flowchart LR
    A[Pod 1] -->|IPv4: 10.244.1.5| B[Cluster IPv4]
    A -->|IPv6: 2001:db8:1::5| C[Cluster IPv6]
    B --> D[Underlying network]
    C --> D

The cluster runs both stacks. The cluster operator must configure both stacks; the CNI plugin must both.

The dual-stack configuration

The kubeadm dual-stack init:

kubeadm init \
  --pod-network-cidr=10.244.0.0/16,2001:db8::/32 \
  --service-cidr=10.96.0.0/16,2001:db8:1::/112

The comma-separated values are the two CIDRs. The kubeadm configures the API server, the controller-manager, and the kubelet with both stacks.

The kubelet config:

node-ip: 10.0.0.1,2001:db8::1
cluster-cidr: 10.244.0.0/16,2001:db8::/32

The kubelet has two node IPs and two cluster CIDRs. The CNI plugin reads the kubelet’s config and configures both stacks.

The CNI plugin’s dual-stack support

The CNI plugin must support dual-stack:

• Calico: supports dual-stack via separate IP pools (one IPv4, one IPv6).
• Cilium: supports dual-stack natively.
• Flannel: supports dual-stack via the IPv6 backend.
• Weave: supports dual-stack in recent versions.

The cluster operator must verify the CNI plugin’s support. A CNI plugin that does not support dual-stack will assign only an IPv4 address; the IPv6 stack is empty.

The Service dual-stack

A Service in dual-stack mode has both IPv4 and IPv6 cluster IPs:

apiVersion: v1
kind: Service
metadata:
  name: billing
spec:
  ipFamilies:
    - IPv4
    - IPv6
  ipFamilyPolicy: PreferDualStack
  selector:
    app: billing
  ports:
    - port: 80
      targetPort: 8080

The ipFamilyPolicy field controls the dual-stack behaviour:

• SingleStack: the Service has one IP family.
• PreferDualStack: the Service has both if both are available; falls back to one if the cluster does not support dual-stack.
• RequireDualStack: the Service has both; if the cluster does not support dual-stack, the Service is not created.

The ipFamilies field controls the order of the IPs.

The cluster operator’s audit

The cluster operator can audit the dual-stack configuration:

# The Service's IPs
kubectl get svc billing -o jsonpath='{.spec.clusterIPs}'

["10.96.0.10", "2001:db8:1::10"]

# Substitute the dual-stack Pod you are checking:
POD=billing-7d4f9c6b85-nm2zt

# The Pod's IPs
kubectl get pod "$POD" -o jsonpath='{.status.podIPs}'

[{"ip":"10.244.1.5"},{"ip":"2001:db8:1::5"}]

The cluster operator must verify both stacks are present. A Pod with only one IP is a sign that the CNI plugin or the kubelet is misconfigured.

The migration path

The migration from IPv4-only to dual-stack is a significant change:

1. Inventory the cluster. Understand the applications, the CNI plugin, and the underlying network.
2. Verify the CNI plugin’s dual-stack support. The CNI plugin must be updated.
3. Plan the IPv6 pool. The IPv6 pool is the cluster’s IPv6 address space; size it for the maximum Pod count.
4. Cordon and drain the nodes. The migration must be performed node by node.
5. Update the kubelet config. The kubelet must be reconfigured to support both stacks.
6. Restart the kubelet. The kubelet reads the new config on restart.
7. Cordon and drain the next node. Repeat for every node.
8. Verify the cluster. Confirm the Pods have both IPs.

The migration is disruptive. The cluster operator must plan the maintenance window.

The failure modes

The dual-stack’s failure modes:

• CNI plugin does not support dual-stack: the Pod has only an IPv4 address. The fix is to update the CNI plugin.
• Underlying network does not support IPv6: the IPv6 traffic is dropped. The fix is to coordinate with the network team.
• Service dual-stack misconfigured: the Service has only one IP. The fix is to set the ipFamilyPolicy correctly.
• Pod-to-Pod IPv6 connectivity fails: the underlying network or the CNI plugin is the issue. The fix is to verify the configuration.

The operational discipline

The dual-stack’s operational discipline:

• Document the cluster’s dual-stack configuration. The cluster operator must understand the two stacks.
• Verify the CNI plugin’s dual-stack support. The CNI plugin must be updated.
• Plan the dual-stack migration. The migration is disruptive; the maintenance window must be planned.
• Audit the Pod’s IPs. The Pod must have both IPs.
• Audit the Service’s IPs. The Service must have both IPs.
• Monitor both stacks. The metrics must cover both IPv4 and IPv6 traffic.
• Document the dual-stack choice. The dual-stack is the cluster’s network configuration; the documentation is the reference.

Quiz

Production discipline

• Dual-stack gives every Pod two IPs. The cluster runs both stacks.
• The CNI plugin must support dual-stack. A CNI plugin that supports only IPv4 will assign only an IPv4 address.
• The kubelet must be configured for dual-stack. The comma-separated values are the two CIDRs.
• The migration is disruptive. The cluster operator must plan the maintenance window.
• Audit the Pod’s IPs. The Pod must have both IPs.
• Audit the Service’s IPs. The Service must have both IPs.
• Monitor both stacks. The metrics must cover both IPv4 and IPv6 traffic.
• Document the dual-stack choice. The dual-stack is the cluster’s network configuration; the documentation is the reference.
• Plan the cluster’s evolution. The dual-stack is the cluster’s network future; the operator must understand the destination.