vSphere Kubernetes Service (VKS) Cluster Creation Fails with "Error while creating objects of type: vpcSubnet - does not have spare capacity to satisfy new block subnet "

Products

Tanzu Kubernetes Runtime VMware vSphere Kubernetes Service

Issue/Introduction

When attempting to provision a vSphere Kubernetes Service (VKS) guest cluster, the deployment fails during the network initialization phase. Users may observe the following error messages:

Topology Error: TopologyReconcileFailed, Message: ClusterClass is not successfully reconciled: status of VariablesReady condition on ClusterClass must be "True"

Infrastructure Error: The condition type InfrastructureReady reports Status: False with the reason NotReady / SubnetPortNotReady.

NSX Fault String:

Message:    network interface "eth0" error: network interface is not ready: SubnetPortNotReady - error occurred while processing the SubnetPort CR. Error: nsx error code: 500157, message: Error while creating objects of type: vpcSubnet, details: , related error: [{Details: , ErrorCode: 520012, ErrorMessage: IpAddressBlock [/orgs/default/projects/f996175a-/infra/ip-blocks/<VPC_Name>-<IP BLOCK>] does not have spare capacity to satisfy new block subnet /orgs/default/projects/f996175a-XXXX-XXXX-XXXX-XXXXXXXX/vpcs/<VPC_Name>/subnets/kubernetes-cluster-XXXX-XXXX_XXX-XXXX-XXXX-XXXX-b4215d8e1846_694d806f/ip-pools/static-ipv4-default/ip-subnets/XXXXXXXX-XXXX-XXXXX-a409-a1bb6350e625 of size 256., ModuleName: Policy}]

Environment

vSphere Kubernetes Runtime

vSphere Kubernetes Service

VMware NSX

Cause

This issue occurs due to IP capacity exhaustion within the parent NSX Virtual Private Cloud (VPC) Private IP block assigned to the target namespace.

The allocated NSX IP Address Block does not contain sufficient free IP addresses to satisfy the subnet allocation requirements for the new VKS cluster. Specifically, the VKS provisioning workflow requires a dedicated and contiguous /24 subnet (256 IP addresses) for the guest cluster node network.

For example, consider a parent VPC IP CIDR of /24.

During VKS cluster provisioning, the system automatically attempts to allocate a contiguous /24 subnet from the parent IP block for the guest cluster node network. However, if the parent block itself is only a /24, and a portion of that range is already reserved for VPC gateway routing overhead or existing allocations, the remaining address space becomes insufficient to carve out a new contiguous /24 subnet.

As a result, subnet allocation fails, leading to the following errors:

SubnetPortNotReady
NSX error code 520012

In summary, the issue is caused by the parent VPC IP block being too small to satisfy the subnet allocation requirements of the VKS cluster provisioning logic.

Note:
The Pod CIDR (for example, [IP_ADDRESS]/24) is an internal logical overlay network managed by the cluster CNI and does not consume physical IP addresses from the NSX VPC parent IP block. The VPC IP block is used exclusively for:

Virtual machine node interfaces (eth0)
Load Balancer VIP allocations

Resolution

Log in to the NSX Manager user interface.
Navigate to the IP Address Pools/Blocks configuration for the target VPC project.
Review the current IP capacity and utilization.
Expand the existing IP block or assign an additional IP address block that contains a minimum of 256 contiguous free IP addresses or reduce the Public subnet.
Once sufficient capacity is confirmed in NSX, retry the VKS cluster deployment.

Reference image from NSX:

Additional Information

Reference:

"does not have spare capacity to satisfy new block subnet ... Error code 520012" when enabling Default Outbound NAT on VPC Connectivity Profile

You can find the free IP left using API call from SDDC:

GET "https://NSX_Manager/policy/api/v1/infra/ip-blocks/<UUID>/usage"
Enter host password for user 'admin':
"used_ip_ranges" : [ "192.168.X.X - 192.168.X.XX" ],
"available_ip_ranges" : [ ],
"used_ips_count" : "32".
"available_ips_count" : "0"