Dual-stack and IPv6 — modern IP addressing in Kubernetes

Dual-stack and IPv6 networking in Kubernetes allows Pods and Services to have both IPv4 and IPv6 addresses. This lesson walks the configuration, the migration path, the operational trade-offs, and the discipline.

Dual-stack concepts

flowchart LR
    A[Pod] --> B["IPv4: 10.244.1.5"]
    A --> C["IPv6: fd00::1"]
    D[Service] --> E["ClusterIP IPv4: 10.96.0.1"]
    D --> F["ClusterIP IPv6: fd00::1"]
    G[Client] -->|IPv4 client| E
    G -->|IPv6 client| F

Dual-stack concepts:

• Pod dual-stack. A Pod has both an IPv4 and an IPv6 address.
• Service dual-stack. A Service has both an IPv4 and an IPv6 ClusterIP.
• Client family selection. A client uses the IP family it supports; the Service routes to the matching family.

A dual-stack cluster can serve both IPv4 and IPv6 clients without separate clusters.

kubeadm init for dual-stack

kubeadm init \
  --control-plane-endpoint "lb-endpoint:6443" \
  --pod-network-cidr=10.244.0.0/16,fd00::/48 \
  --service-ipv4-dual-stack=10.96.0.0/12 \
  --service-ipv6-dual-stack=fd00:96::/108 \
  --upload-certs

The flags:

• --pod-network-cidr=10.244.0.0/16,fd00::/48 — Pod CIDRs in both families.
• --service-ipv4-dual-stack=10.96.0.0/12 — Service IPv4 CIDR.
• --service-ipv6-dual-stack=fd00:96::/108 — Service IPv6 CIDR.

After kubeadm init, the Service API is dual-stack.

The CNI configuration

# Calico dual-stack
apiVersion: operator.tigera.io/v1
kind: Installation
metadata:
  name: default
spec:
  calicoNetwork:
    ipPools:
      - cidr: 10.244.0.0/16
        encapsulation: VXLAN
      - cidr: fd00::/48
        encapsulation: None

# Cilium dual-stack
apiVersion: cilium.io/v2
kind: CiliumClusterwideNetworkPolicy
metadata:
  name: dual-stack
spec:
  ipam:
    operator:
      ipv4:
        cidrs:
          - 10.244.0.0/16
      ipv6:
        cidrs:
          - fd00::/48

The CNI must be configured for dual-stack IPAM. The CNI assigns Pods both an IPv4 and an IPv6 address.

Service dual-stack

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

The Service has:

• ipFamilyPolicy: DualStack. The Service accepts both families.
• ipFamilies. The order in which the Service gets its ClusterIPs.

kubectl get svc myapp -o jsonpath='{.spec.clusterIPs}'

["10.96.0.1", "fd00::1"]

The Service has both ClusterIPs.

The migration path

flowchart LR
    A[IPv4-only cluster] --> B[Enable dual-stack CNI]
    B --> C[Update kubeadm init flags]
    C --> D[New Pods get both families]
    D --> E[Update Services to DualStack]
    E --> F[Verify traffic on both families]
    F --> G[Decommission IPv4-only]

The migration:

1. Enable dual-stack in the CNI configuration.
2. Update kubeadm init flags (only for new clusters).
3. New Pods get both families; existing Pods stay IPv4-only.
4. Update Services to ipFamilyPolicy: DualStack.
5. Verify traffic on both families.
6. Eventually, decommission IPv4-only Pods (rare in practice).

The migration is incremental; both families coexist during the transition.

The operational trade-offs

flowchart LR
    A[Dual-stack] --> B[+ IPv4 and IPv6 clients served]
    A --> C[+ Future-proof for IPv6]
    A --> D[- More complex IPAM]
    A --> E[- Some CNIs not dual-stack ready]
    A --> F[- Operational complexity]

The trade-offs:

• Pros. IPv4 and IPv6 clients served from one cluster; future-proof for IPv6.
• Cons. More complex IPAM; some CNIs not dual-stack ready; operational complexity.

Quiz

The operational discipline

Dual-stack in production rests on five non-negotiable elements:

• Verify CNI support. Cilium, Calico — yes; older CNIs — no.
• Plan the IP ranges carefully. IPv6 /48 is generous; IPv4 /16 is typical.
• Update Services to DualStack. One by one, with verification.
• Monitor both families. Ensure traffic flows on both.
• Document the dual-stack configuration. IP ranges, CIDRs, CNI config.

Dual-stack is the future. The discipline is to adopt it for new clusters and migrate existing clusters incrementally.