Skip to content

Conversation

@kartikjoshi21
Copy link
Contributor

@kartikjoshi21 kartikjoshi21 commented Dec 8, 2025

This PR introduces the core configuration and CLI plumbing for IPv6 and dual-stack clusters in minikube. It does not change kubeadm/CNI templates or control-plane bindings yet; those come in follow-up PRs.

Concretely, it:

  • Adds an --ip-family flag to minikube start:

    • ipv4 (default, current behaviour)
    • ipv6
    • dual
  • Wires IPv6-aware CIDRs and addresses into ClusterConfig / KubernetesConfig:

    • --service-cluster-ip-range-v6KubernetesConfig.ServiceCIDRv6
    • --pod-cidrKubernetesConfig.PodCIDR (IPv4)
    • --pod-cidr-v6KubernetesConfig.PodCIDRv6 (IPv6)
    • --subnet-v6ClusterConfig.Subnetv6 (KIC Docker/Podman network)
    • --host-only-cidr-v6ClusterConfig.HostOnlyCIDRv6 (VirtualBox)
    • --static-ipv6ClusterConfig.StaticIPv6
  • Extends Node with an IPv6 field so later PRs can populate node IPs.

  • Adds defaults for IPv6 CIDRs:

    • DefaultServiceCIDRv6 = "fd00::/108"
    • DefaultPodCIDRv6 = "fd01::/64"
  • Introduces normalizeAndValidateIPFamily() which:

    • Normalises IP family to ipv4 / ipv6 / dual (defaulting to ipv4),
    • Sets IPv6 defaults when an IPv6-capable family is selected,
    • Keeps the existing IPv4 PodCIDR default (cni.DefaultPodCIDR) for ipv4/dual,
    • Validates CIDRs/addresses for --subnet-v6, --service-cluster-ip-range-v6, --pod-cidr, --pod-cidr-v6, and --static-ipv6.
  • Adds guardrails for IPv6/dual on the Docker driver:

    • IPv6-only clusters require a Linux Docker daemon (not Docker Desktop),
    • Dual-stack on Docker Desktop prints a warning,
    • Prints a tip about enabling IPv6 in daemon.json if the daemon/network blocks IPv6 bridge networks.

For --ip-family=ipv4 with no IPv6 flags, minikube behaves exactly as today (IPv4-only cluster, existing Service/Pod CIDR defaults, no CNI or kubeadm behaviour change).

Fixes: #8535

Refer to #22061 (comment) comment for testing steps.
Tested and verified on:

PS C:\Users\kartikjoshi> wsl --version
WSL version: 2.6.2.0
Kernel version: 6.6.87.2-1
WSLg version: 1.0.71
MSRDC version: 1.2.6353
Direct3D version: 1.611.1-81528511
DXCore version: 10.0.26100.1-240331-1435.ge-release
Windows version: 10.0.26200.7093

@k8s-ci-robot
Copy link
Contributor

[APPROVALNOTIFIER] This PR is NOT APPROVED

This pull-request has been approved by: kartikjoshi21
Once this PR has been reviewed and has the lgtm label, please assign prezha for approval. For more information see the Code Review Process.

The full list of commands accepted by this bot can be found here.

Needs approval from an approver in each of these files:

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

@k8s-ci-robot k8s-ci-robot added size/L Denotes a PR that changes 100-499 lines, ignoring generated files. needs-ok-to-test Indicates a PR that requires an org member to verify it is safe to test. labels Dec 8, 2025
@k8s-ci-robot
Copy link
Contributor

Hi @kartikjoshi21. Thanks for your PR.

I'm waiting for a github.com member to verify that this patch is reasonable to test. If it is, they should reply with /ok-to-test on its own line. Until that is done, I will not automatically test new commits in this PR, but the usual testing commands by org members will still work. Regular contributors should join the org to skip this step.

Once the patch is verified, the new status will be reflected by the ok-to-test label.

I understand the commands that are listed here.

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes-sigs/prow repository.

@k8s-ci-robot k8s-ci-robot added the cncf-cla: yes Indicates the PR's author has signed the CNCF CLA. label Dec 8, 2025
@minikube-bot
Copy link
Collaborator

Can one of the admins verify this patch?

@kartikjoshi21
Copy link
Contributor Author

Logs with basic flags plumbing and current behavior validation

kartikjoshi@kartikjoshiwindows:~/minikube-ipv6-support/minikube$ ./out/minikube delete --all --purge
🔥  Deleting "minikube" in docker ...
🔥  Removing /home/kartikjoshi/.minikube/machines/minikube ...
💀  Removed all traces of the "minikube" cluster.
🔥  Successfully deleted all profiles
💀  Successfully purged minikube directory located at - [/home/kartikjoshi/.minikube]
📌  Kicbase images have not been deleted. To delete images run:
    ▪ docker rmi gcr.io/k8s-minikube/kicbase-builds:v0.0.48-1763789673-21948 gcr.io/k8s-minikube/kicbase-builds:v0.0.48-1760939008-21773 gcr.io/k8s-minikube/kicbase-builds:v0.0.48-1759745255-21703 gcr.io/k8s-minikube/kicbase-builds:v0.0.47-1756116447-21413
kartikjoshi@kartikjoshiwindows:~/minikube-ipv6-support/minikube$ ./out/minikube start \
  --driver=docker \
  --cni=bridge \
  --ip-family=ipv4

kubectl get nodes -o wide
kubectl get pods -A -o wide
😄  minikube v1.37.0 on Ubuntu 24.04 (kvm/amd64)
✨  Using the docker driver based on user configuration
📌  Using Docker driver with root privileges
👍  Starting "minikube" primary control-plane node in "minikube" cluster
🚜  Pulling base image v0.0.48-1763789673-21948 ...
💾  Downloading Kubernetes v1.34.1 preload ...
    > preloaded-images-k8s-v18-v1...:  337.01 MiB / 337.01 MiB  100.00% 3.73 Mi
🔥  Creating docker container (CPUs=2, Memory=3072MB) ...
🐳  Preparing Kubernetes v1.34.1 on Docker 29.0.2 ...
🔗  Configuring bridge CNI (Container Networking Interface) ...
🔎  Verifying Kubernetes components...
    ▪ Using image gcr.io/k8s-minikube/storage-provisioner:v5
🌟  Enabled addons: storage-provisioner, default-storageclass
🏄  Done! kubectl is now configured to use "minikube" cluster and "default" namespace by default
NAME       STATUS   ROLES           AGE   VERSION   INTERNAL-IP    EXTERNAL-IP   OS-IMAGE                         KERNEL-VERSION                     CONTAINER-RUNTIME
minikube   Ready    control-plane   5s    v1.34.1   192.168.49.2   <none>        Debian GNU/Linux 12 (bookworm)   6.6.87.2-microsoft-standard-WSL2   docker://29.0.2
NAMESPACE     NAME                               READY   STATUS    RESTARTS   AGE   IP             NODE       NOMINATED NODE   READINESS GATES
kube-system   etcd-minikube                      0/1     Running   0          4s    192.168.49.2   minikube   <none>           <none>
kube-system   kube-apiserver-minikube            0/1     Running   0          4s    192.168.49.2   minikube   <none>           <none>
kube-system   kube-controller-manager-minikube   0/1     Running   0          3s    192.168.49.2   minikube   <none>           <none>
kube-system   kube-scheduler-minikube            0/1     Running   0          3s    192.168.49.2   minikube   <none>           <none>
kube-system   storage-provisioner                0/1     Pending   0          1s    <none>         <none>     <none>           <none>
kartikjoshi@kartikjoshiwindows:~/minikube-ipv6-support/minikube$ kubectl get pods -A -o wide
NAMESPACE     NAME                               READY   STATUS    RESTARTS       AGE     IP             NODE       NOMINATED NODE   READINESS GATES
kube-system   coredns-66bc5c9577-qcbk6           1/1     Running   0              2m5s    10.244.0.2     minikube   <none>           <none>
kube-system   etcd-minikube                      1/1     Running   0              2m11s   192.168.49.2   minikube   <none>           <none>
kube-system   kube-apiserver-minikube            1/1     Running   0              2m11s   192.168.49.2   minikube   <none>           <none>
kube-system   kube-controller-manager-minikube   1/1     Running   0              2m10s   192.168.49.2   minikube   <none>           <none>
kube-system   kube-proxy-jcvhm                   1/1     Running   0              2m5s    192.168.49.2   minikube   <none>           <none>
kube-system   kube-scheduler-minikube            1/1     Running   0              2m10s   192.168.49.2   minikube   <none>           <none>
kube-system   storage-provisioner                1/1     Running   1 (2m3s ago)   2m8s    192.168.49.2   minikube   <none>           <none>
kartikjoshi@kartikjoshiwindows:~/minikube-ipv6-support/minikube$
kartikjoshi@kartikjoshiwindows:~/minikube-ipv6-support/minikube$ docker network inspect minikube
[
    {
        "Name": "minikube",
        "Id": "c1162b89eeb5fc041f022fcffbe8f9a44c3778146abf90a3d1c4f0c4e21138ad",
        "Created": "2025-11-27T05:16:25.564927403Z",
        "Scope": "local",
        "Driver": "bridge",
        "EnableIPv4": true,
        "EnableIPv6": false,
        "IPAM": {
            "Driver": "default",
            "Options": {},
            "Config": [
                {
                    "Subnet": "192.168.49.0/24",
                    "Gateway": "192.168.49.1"
                }
            ]
        },
        "Internal": false,
        "Attachable": false,
        "Ingress": false,
        "ConfigFrom": {
            "Network": ""
        },
        "ConfigOnly": false,
        "Containers": {
            "20f782bd5029fc4a3e291e6180d993ae3ed62bb70eac66c4f1d44dbc088cdb42": {
                "Name": "minikube",
                "EndpointID": "a12e850a99129399eabb8b14cd4ccdeef571109be83f76d76e40537f98c68736",
                "MacAddress": "6e:19:61:a9:95:10",
                "IPv4Address": "192.168.49.2/24",
                "IPv6Address": ""
            }
        },
        "Options": {
            "--icc": "",
            "--ip-masq": "",
            "com.docker.network.driver.mtu": "1500"
        },
        "Labels": {
            "created_by.minikube.sigs.k8s.io": "true",
            "name.minikube.sigs.k8s.io": "minikube"
        }
    }
]

kartikjoshi@kartikjoshiwindows:~/minikube-ipv6-support/minikube$ ./out/minikube delete --all --purge
./out/minikube start \
  --driver=docker \
  --cni=bridge \
  --ip-family=ipv6 \
  --service-cluster-ip-range-v6=fd00::/108 \
  --pod-cidr-v6=fd01::/64
🔥  Deleting "minikube" in docker ...
🔥  Removing /home/kartikjoshi/.minikube/machines/minikube ...
💀  Removed all traces of the "minikube" cluster.
🔥  Successfully deleted all profiles
💀  Successfully purged minikube directory located at - [/home/kartikjoshi/.minikube]
📌  Kicbase images have not been deleted. To delete images run:
    ▪ docker rmi gcr.io/k8s-minikube/kicbase-builds:v0.0.48-1763789673-21948 gcr.io/k8s-minikube/kicbase-builds:v0.0.48-1760939008-21773 gcr.io/k8s-minikube/kicbase-builds:v0.0.48-1759745255-21703 gcr.io/k8s-minikube/kicbase-builds:v0.0.47-1756116447-21413
😄  minikube v1.37.0 on Ubuntu 24.04 (kvm/amd64)
✨  Using the docker driver based on user configuration
📌  Using Docker driver with root privileges
💡  If Docker daemon IPv6 is disabled, enable it in /etc/docker/daemon.json and restart:
  {"ipv6": true, "fixed-cidr-v6": "fd00:55:66::/64"}
👍  Starting "minikube" primary control-plane node in "minikube" cluster
🚜  Pulling base image v0.0.48-1763789673-21948 ...
💾  Downloading Kubernetes v1.34.1 preload ...
    > preloaded-images-k8s-v18-v1...:  337.01 MiB / 337.01 MiB  100.00% 1.83 Mi
🔥  Creating docker container (CPUs=2, Memory=3072MB) ...
🐳  Preparing Kubernetes v1.34.1 on Docker 29.0.2 ...
🔗  Configuring bridge CNI (Container Networking Interface) ...
🔎  Verifying Kubernetes components...
    ▪ Using image gcr.io/k8s-minikube/storage-provisioner:v5
🌟  Enabled addons: storage-provisioner, default-storageclass
🏄  Done! kubectl is now configured to use "minikube" cluster and "default" namespace by default
kartikjoshi@kartikjoshiwindows:~/minikube-ipv6-support/minikube$ docker network inspect
docker: 'docker network inspect' requires at least 1 argument

Usage:  docker network inspect [OPTIONS] NETWORK [NETWORK...]

See 'docker network inspect --help' for more information
kartikjoshi@kartikjoshiwindows:~/minikube-ipv6-support/minikube$ docker network inspect minikube
[
    {
        "Name": "minikube",
        "Id": "b84287d9edfc3b6e15a154b9ae611ea0664dca10fd3a85908784064dcefaf089",
        "Created": "2025-11-26T11:34:27.616639443Z",
        "Scope": "local",
        "Driver": "bridge",
        "EnableIPv4": true,
        "EnableIPv6": false,
        "IPAM": {
            "Driver": "default",
            "Options": {},
            "Config": [
                {
                    "Subnet": "192.168.49.0/24",
                    "Gateway": "192.168.49.1"
                }
            ]
        },
        "Internal": false,
        "Attachable": false,
        "Ingress": false,
        "ConfigFrom": {
            "Network": ""
        },
        "ConfigOnly": false,
        "Containers": {
            "2bf3628d6001aa223242e4cef1b0b098eb59ac7749acf4fde7615ac54495d354": {
                "Name": "minikube",
                "EndpointID": "aa21a413ae7660ea35e6bcfe7fb19fdc628dda5c77bc319822d212517c782bb3",
                "MacAddress": "76:c8:b1:14:67:6c",
                "IPv4Address": "192.168.49.2/24",
                "IPv6Address": ""
            }
        },
        "Options": {
            "--icc": "",
            "--ip-masq": "",
            "com.docker.network.driver.mtu": "1500"
        },
        "Labels": {
            "created_by.minikube.sigs.k8s.io": "true",
            "name.minikube.sigs.k8s.io": "minikube"
        }
    }
]

kartikjoshi@kartikjoshiwindows:~/minikube-ipv6-support/minikube$ ./out/minikube start -p ipfam-bad \
  --driver=docker \
  --cni=bridge \
  --ip-family=foo
😄  [ipfam-bad] minikube v1.37.0 on Ubuntu 24.04 (kvm/amd64)
✨  Using the docker driver based on user configuration
📌  Using Docker driver with root privileges

❌  Exiting due to MK_USAGE: Invalid --ip-family foo. Must be one of: ipv4, ipv6, dual.

kartikjoshi@kartikjoshiwindows:~/minikube-ipv6-support/minikube$ ./out/minikube start -p bad-svc-v6 \
  --driver=docker \
  --ip-family=dual \
  --service-cluster-ip-range-v6=not-a-cidr
😄  [bad-svc-v6] minikube v1.37.0 on Ubuntu 24.04 (kvm/amd64)
✨  Using the docker driver based on user configuration
📌  Using Docker driver with root privileges

❌  Exiting due to MK_USAGE: --service-cluster-ip-range-v6 must be a valid IPv6 CIDR: invalid CIDR address: not-a-cidr


@kartikjoshi21
Copy link
Contributor Author

Testing

All tests were done with a locally built out/minikube.

1. Default IPv4 cluster (no new flags)

```bash
./out/minikube start --driver=docker --alsologtostderr -v=1
kubectl get nodes -o wide
Expectations:

Cluster starts and behaves as before.
2. --ip-family validation
bash
Copy code
./out/minikube start --driver=docker --ip-family=foobar
Expectations:

Fails with a usage error:

Invalid --ip-family foobar. Must be one of: ipv4, ipv6, dual.

No cluster is created.
3. CIDR validation / type checking
3.1 --pod-cidr must be IPv4
./out/minikube start \
  --driver=docker \
  --ip-family=dual \
  --pod-cidr=fd01::/64
Expectations:

Fails with a usage error mentioning --pod-cidr must be a valid IPv4 CIDR.
3.2 --pod-cidr-v6 must be IPv6

./out/minikube start \
  --driver=docker \
  --ip-family=dual \
  --pod-cidr-v6=10.244.0.0/16
Expectations:

Fails with a usage error mentioning --pod-cidr-v6 must be a valid IPv6 CIDR.
3.3 --service-cluster-ip-range-v6 must be IPv6
./out/minikube start \
  --driver=docker \
  --ip-family=dual \
  --service-cluster-ip-range-v6=10.96.0.0/12
Expectations:

Fails with a usage error mentioning --service-cluster-ip-range-v6 must be a valid IPv6 CIDR.
3.4 --subnet-v6 must be IPv6
./out/minikube start \
  --driver=docker \
  --subnet-v6=10.0.0.0/24
Expectations:

Fails with a usage error mentioning --subnet-v6 must be a valid IPv6 CIDR.
4. --static-ipv6 validation
./out/minikube start \
  --driver=docker \
  --ip-family=dual \
  --static-ipv6=192.168.49.2
Expectations:

Fails with a usage error:

--static-ipv6 must be a valid IPv6 address.

@medyagh
Copy link
Member

medyagh commented Dec 10, 2025

/ok-to-test

@k8s-ci-robot k8s-ci-robot added ok-to-test Indicates a non-member PR verified by an org member that is safe to test. and removed needs-ok-to-test Indicates a PR that requires an org member to verify it is safe to test. labels Dec 10, 2025
@minikube-pr-bot
Copy link

kvm2 driver with docker runtime

┌───────────────────┬──────────┬────────────────────────┐
│      COMMAND      │ MINIKUBE │ MINIKUBE  ( PR 22061 ) │
├───────────────────┼──────────┼────────────────────────┤
│ minikube start    │ 41.8s    │ 41.1s                  │
│ ⚠️  enable ingress │ 33.8s    │ 103.6s ⚠️               │
└───────────────────┴──────────┴────────────────────────┘

Times for minikube start: 42.5s 42.3s 41.7s 42.3s 40.1s
Times for minikube (PR 22061) start: 40.9s 39.8s 40.5s 40.1s 44.5s

Times for minikube ingress: 64.4s 24.8s 24.2s 24.8s 30.8s
Times for minikube (PR 22061) ingress: 337.8s 45.8s 44.7s 43.8s 45.8s

docker driver with docker runtime

┌───────────────────┬──────────┬────────────────────────┐
│      COMMAND      │ MINIKUBE │ MINIKUBE  ( PR 22061 ) │
├───────────────────┼──────────┼────────────────────────┤
│ minikube start    │ 21.7s    │ 21.3s                  │
│ ⚠️  enable ingress │ 25.6s    │ 34.0s ⚠️                │
└───────────────────┴──────────┴────────────────────────┘

Times for minikube start: 22.9s 19.8s 20.2s 22.3s 23.2s
Times for minikube (PR 22061) start: 19.7s 19.7s 22.2s 21.5s 23.3s

Times for minikube ingress: 28.6s 27.6s 23.6s 21.6s 26.6s
Times for minikube (PR 22061) ingress: 37.6s 41.6s 45.6s 16.6s 28.6s

docker driver with containerd runtime

┌────────────────┬──────────┬────────────────────────┐
│    COMMAND     │ MINIKUBE │ MINIKUBE  ( PR 22061 ) │
├────────────────┼──────────┼────────────────────────┤
│ minikube start │ 18.9s    │ 19.7s                  │
│ enable ingress │ 64.1s    │ 63.4s                  │
└────────────────┴──────────┴────────────────────────┘

Times for minikube start: 17.5s 18.3s 19.4s 19.3s 20.0s
Times for minikube (PR 22061) start: 19.2s 18.4s 22.0s 21.3s 17.8s

Times for minikube ingress: 60.1s 54.1s 58.1s 83.1s 65.1s
Times for minikube (PR 22061) ingress: 61.1s 51.1s 95.6s 26.1s 83.1s

@k8s-ci-robot
Copy link
Contributor

@kartikjoshi21: The following tests failed, say /retest to rerun all failed tests or /retest-required to rerun all mandatory failed tests:

Test name Commit Details Required Rerun command
integration-vfkit-docker-macos-arm64 1c88f6d link false /test integration-vfkit-docker-macos-arm64
integration-docker-containerd-linux-x86-64 1c88f6d link true /test integration-docker-containerd-linux-x86-64
integration-docker-docker-linux-arm64 1c88f6d link true /test integration-docker-docker-linux-arm64
integration-docker-crio-linux-x86-64 1c88f6d link true /test integration-docker-crio-linux-x86-64
integration-kvm-crio-linux-x86-64 1c88f6d link true /test integration-kvm-crio-linux-x86-64

Full PR test history. Your PR dashboard. Please help us cut down on flakes by linking to an open issue when you hit one in your PR.

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes-sigs/prow repository. I understand the commands that are listed here.

@minikube-pr-bot
Copy link

Here are the number of top 10 failed tests in each environments with lowest flake rate.

Environment Test Name Flake Rate
KVM_Linux_crio (3 failed) TestFunctionalNewestKubernetes/Versionv1.35.0-beta.0/parallel/DashboardCmd(gopogh) Unknown
KVM_Linux (9 failed) TestISOImage/PersistentMounts//data(gopogh) Unknown
KVM_Linux (9 failed) TestISOImage/PersistentMounts//var/lib/docker(gopogh) Unknown
KVM_Linux (9 failed) TestISOImage/PersistentMounts//var/lib/cni(gopogh) Unknown
KVM_Linux (9 failed) TestISOImage/PersistentMounts//var/lib/kubelet(gopogh) Unknown
KVM_Linux (9 failed) TestISOImage/PersistentMounts//var/lib/minikube(gopogh) Unknown
KVM_Linux (9 failed) TestISOImage/PersistentMounts//var/lib/toolbox(gopogh) Unknown
KVM_Linux (9 failed) TestISOImage/PersistentMounts//var/lib/boot2docker(gopogh) Unknown
KVM_Linux (9 failed) TestISOImage/VersionJSON(gopogh) Unknown
KVM_Linux (9 failed) TestISOImage/eBPFSupport(gopogh) Unknown

Besides the following environments also have failed tests:

  • Docker_Linux_crio: 29 failed (gopogh)

  • Docker_Linux_crio_arm64: 40 failed (gopogh)

To see the flake rates of all tests by environment, click here.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

cncf-cla: yes Indicates the PR's author has signed the CNCF CLA. ok-to-test Indicates a non-member PR verified by an org member that is safe to test. size/L Denotes a PR that changes 100-499 lines, ignoring generated files.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Add support for IPv6

5 participants