Node Bootstrapping fails due to invalid Dual-Stack Networking Configuration in vSphere Kubernetes Service

Products

• VMware vSphere Kubernetes Service

Issue/Introduction

• A newly provisioned vSphere with Kubernetes workload cluster (Guest Cluster) fails to complete provisioning and remains in a Ready: False state in the vCenter Server UI. Attempts to connect to the workload cluster via kubectl result in timeouts or EOF errors because the API server fails to initialize.
  
  
• When logging into the worker or control plane nodes directly via SSH, the kubelet service is observed to be in a continuous crash loop due to a node bootstrapping failure.
  
  
• Checking the cloud-init logs on the affected node at /var/log/cloud-init-output.log reveals an API validation error similar to the following:

[YYYY-MM-DD HH:MM:SS] [networking.serviceSubnet: Invalid value: "<IP>/16,<IP>/16": expected one (IPv4 or IPv6) CIDR or two CIDRs from each family for dual-stack networking, networking.podSubnet: Invalid value: "<IP>/16,<IP>/16": expected one (IPv4 or IPv6) CIDR or two CIDRs from each family for dual-stack networking]

Environment

VMware vSphere Kubernetes Service

Cause

• This issue is caused by an invalid Kubernetes network topology defined in the deployment YAML (Cluster specification).
  
  
• Strict Kubernetes networking rules dictate that a cluster must be configured as exactly one CIDR block for Single-Stack (e.g., one IPv4 subnet) or exactly two CIDR blocks from different IP families for Dual-Stack (e.g., one IPv4 subnet and one IPv6 subnet).
  
  
• When multiple IPv4 subnets are specified for Pods and/or Services, kubeadm detects two IP addresses of the same family, rejects the configuration during cloud-init, and exits with a fatal error.

Resolution

As core networking configurations (Pod and Service CIDRs) are immutable once a Kubernetes cluster begins its initial provisioning phase, this cannot be resolved by editing or patching the live cluster YAML.

1. Delete the failed workload cluster from the Supervisor namespace to remove the invalid deployment.

2. Update your Deployment Manifest (Cluster YAML) to ensure only a single IPv4 CIDR is assigned to Pods and Services. If a larger address space is required, consolidate the smaller subnets into a single, larger CIDR block. Example of a corrected configuration (consolidated into a /15 subnet):

spec:
  clusterNetwork:
    pods:
      cidrBlocks:
      - <IP>/15
    serviceDomain: cluster.local
    services:
      cidrBlocks:
      - <IP>/15

3. Redeploy the cluster by applying the corrected YAML to the Supervisor.