Changing Service and Pod CIDR Ranges in vSphere Kubernetes Guest Cluster

Products

• VMware vSphere Kubernetes Service

Issue/Introduction

• This article explains the behavior and supportability of changing the Service IP CIDR and Pod IP CIDR ranges in an existing Kubernetes Guest Cluster/TKG Guest Cluster deployed within a vSphere with Tanzu Supervisor Cluster.
• The Service and Pod CIDR ranges are defined during the initial creation of the Guest Cluster. These ranges are embedded into the cluster’s control plane and networking components such as:
  • kube-controller-manager
  • CoreDNS
  • CNI (Container Network Interface) configuration

Environment

VMware vSphere Kubernetes Service

Cause

Once the cluster is provisioned, these parameters cannot be modified dynamically because changing them would require re-initialization of the networking stack and re-allocation of service IPs and pod subnets, which could break cluster communication and workload stability.

Resolution

Changing the Service CIDR and Pod CIDR ranges on an existing Tanzu Kubernetes Guest Cluster is not supported.

To apply new CIDR ranges:

1. Delete the existing Guest Cluster after ensuring that all workloads and configurations are backed up or exported.
2. Release the existing IP ranges from the networking stack, i.e. NSX IP Pool, etc. 
3. Redeploy the Guest Cluster with the desired Service and Pod CIDR values in the cluster configuration YAML.

Additional Information

For detailed guidance on configuring and managing network settings on Supervisor and Guest Clusters, refer to the following documentation: Change Workload Network Settings on a Supervisor Configured with NSX