How to Setup an IPv6-Only Cluster

An IPv6-only Kubernetes cluster operates exclusively using IPv6 addresses, without support for IPv4. This configuration is ideal for environments that are transitioning away from IPv4 or want to take full advantage of IPv6’s expanded address space. This document, explains how to set up an IPv6-only cluster, including key configurations and necessary checks to ensure proper setup.

Prerequisites

Before setting up an IPv6-only cluster, ensure that:

  • Your environment supports IPv6.

  • Network infrastructure, such as routers, firewalls, and DNS, are configured to handle IPv6 traffic.

  • Any underlying infrastructure (e.g. cloud providers, bare metal setups) must be IPv6-compatible.

Setting Up an IPv6-Only Cluster

The process of creating an IPv6-only cluster involves specifying only IPv6 CIDRs for pods and services during the bootstrap process. Unlike dual-stack, only IPv6 CIDRs are used.

  1. Bootstrap Kubernetes with IPv6 CIDRs

Start by bootstrapping the Kubernetes cluster and providing only IPv6 CIDRs for pods and services:

sudo k8s bootstrap --timeout 10m --interactive

When prompted, set the pod and service CIDRs to IPv6 ranges. For example:

Please set the Pod CIDR: [fd01::/108]
Please set the Service CIDR: [fd98::/108]

Alternatively, these values can be configured in a bootstrap configuration file named bootstrap-config.yaml in this example:

pod-cidr: fd01::/108
service-cidr: fd98::/108

Specify the configuration file during the bootstrapping process:

sudo k8s bootstrap --file bootstrap-config.yaml

  1. Verify Pod and Service Creation

Once the cluster is up, verify that all pods are running:

sudo k8s kubectl get pods -A

Deploy a pod with an nginx web-server and expose it via a service to verify connectivity of the IPv6-only cluster. Create a manifest file nginx-ipv6.yaml with the following content:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: nginx-ipv6
spec:
  selector:
    matchLabels:
      run: nginx-ipv6
  replicas: 1
  template:
    metadata:
      labels:
        run: nginx-ipv6
    spec:
      containers:
      - name: nginx-ipv6
        image: rocks.canonical.com/cdk/diverdane/nginxipv6:1.0.0
        ports:
        - containerPort: 80
---
apiVersion: v1
kind: Service
metadata:
  name: nginx-ipv6
  labels:
    run: nginx-ipv6
spec:
  type: NodePort
  ipFamilies:
  - IPv6
  ports:
  - port: 80
    protocol: TCP
  selector:
    run: nginx-ipv6

Deploy the web-server and its service by running:

sudo k8s kubectl apply -f nginx-ipv6.yaml

  1. Verify IPv6 Connectivity

Retrieve the service details to confirm an IPv6 address is assigned:

sudo k8s kubectl get service nginx-ipv6 -n default

Obtain the service’s IPv6 address from the output:

NAME         TYPE       CLUSTER-IP    EXTERNAL-IP   PORT(S)        AGE
nginx-ipv6   NodePort   fd98::7534    <none>        80:32248/TCP   2m

Use the assigned IPv6 address to test connectivity:

curl http://[fd98::7534]/

A welcome message from the nginx web-server is displayed when IPv6 connectivity is set up correctly.

IPv6-Only Cluster Considerations

Service and Pod CIDR Sizing

Use /108 as the maximum size for Service CIDRs. Larger ranges (e.g., /64) may lead to allocation errors or Kubernetes failing to initialize the IPv6 address allocator.