VKS cluster provisioning hangs in Provisioning state with ControlPlaneUnhealthy warning: Machine does not have a corresponding Node yet

Products

• VMware vSphere Kubernetes Service

Issue/Introduction

During initial deployment, a VKS cluster remains indefinitely in a Provisioning state.

1. Inspecting the cluster status reveals that a VKS control plane VM is deployed, but reconciliation stalls during preflight checks.
2. Checking events on the KubeadmControlPlane controller yields the following recurring warnings:

Type     Reason                 Age                  From                            Message

----     ------                 ----                 ----                            -------

Warning  ControlPlaneUnhealthy  13m (x496 over 133m)  kubeadmcontrolplane-controller  Waiting for control plane to pass preflight checks to continue reconciliation: Machine ##### does not have a corresponding Node yet (Machine.status.nodeRef not set)

Warning  ControlPlaneUnhealthy  3m56s (x42 over 11m)  kubeadmcontrolplane-controller  Waiting for control plane to pass preflight checks to continue reconciliation: Machine ##### does not have a corresponding Node yet (Machine.status.nodeRef not set)

Environment

VMware vSphere Kubernetes Servcie

Cause

During VKS cluster reconciliation, newly created Guest control plane nodes must establish secure network communication back to the Supervisor control plane API endpoints.

If external firewalls, security groups, or internal network policies block TCP ports 6443 (Kubernetes API) and 443 (vCenter API/WCP) from the VKS cluster subnet to the Supervisor control plane network:

• The VKS control plane VM cannot complete its bootstrap registration API handshakes with the Supervisor.
• The Machine.status.nodeRef property remains unset in the Cluster API specification.
• Reconciliation stalls permanently in a ControlPlaneUnhealthy preflight failure loop.

Resolution

Step 1: Verify Network Connectivity

Log into the deployed VKS control plane VM (or a host in the same network segment) and test reachability to the Supervisor Control Plane IP addresses on ports 6443 and 443:

# Test Kubernetes API access

nc -zv <Supervisor_Control_Plane_IP> 6443 

# Test vCenter / WCP API access

nc -zv <Supervisor_Control_Plane_IP> 443

Result: If the connection times out or returns Connection refused, traffic is blocked along the network path.

Step 2: Update Network Firewall Rules

Configure network firewalls, NSX Security Groups, and routing tables to permit bidirectional communication between the Guest Cluster subnet and the Supervisor Control Plane network for the following required ports:

Source	Destination	Protocol / Port	Purpose
VKS Cluster Subnet	Supervisor Control Plane	TCP 6443	Kubernetes API Server communication
VKS Cluster Subnet	Supervisor Control Plane	TCP 443	vSphere Control Plane / vCenter API

Step 3: Confirm Cluster Reconciliation

Once firewall rules are updated, verify that preflight checks pass and node registration completes:

      1. Check that the machine populates its node reference:

       kubectl get machines -n <namespace>

      2. Monitor the KubeadmControlPlane status until the condition transitions to Ready:

       kubectl get kubeadmcontrolplane -n <namespace>