Skip to main content

Windows Node Issues

Purpose: For operators, shows how to resolve kubeadm join failures, ContainerD service issues, and network routing problems.

Informational Only

Windows worker support is not part of the GA support commitment. Use this page only if you are operating an unsupported Windows worker deployment.

Prerequisites​

  • RDP or WinRM access to the Windows node
  • kubectl access to the cluster control plane
  • Ansible inventory configured for Windows hosts

kubeadm Join Failures​

Token Expired​

Symptom: kubeadm join fails with token has expired.

Tokens are valid for 24 hours by default. Generate a new one from a control plane node:

kubeadm token create --print-join-command

Use the new token in the Ansible playbook or run kubeadm join manually on the Windows node.

Control Plane Unreachable​

Symptom: kubeadm join hangs or fails with connection refused.

  1. From the Windows node, test connectivity to the API server:
Test-NetConnection -ComputerName <control-plane-ip> -Port 6443

  1. Verify firewall rules allow TCP 6443 from the Windows node to the control plane.

  2. Check that the control plane's --advertise-address is reachable from the Windows network segment.

Certificate Error​

Symptom: kubeadm join fails with certificate signed by unknown authority.

Pass the CA certificate hash from the kubeadm token create output, or use --discovery-token-unsafe-skip-ca-verification for testing only.

ContainerD Service Issues​

Service Not Running​

Get-Service containerd

If stopped, start it:

Start-Service containerd

Check logs in C:\ProgramData\containerd\root\panic.log for startup errors.

Image Pull Failures​

Symptom: Windows pods stuck in ErrImagePull.

  1. Verify ContainerD can pull images:
ctr images pull mcr.microsoft.com/windows/nanoserver:ltsc2022
  1. For air-gapped environments, verify the bastion registry is configured in ContainerD's config.toml:
C:\Program Files\containerd\config.toml

Check the [plugins."io.containerd.grpc.v1.cri".registry.mirrors] section.

Network Routing Issues​

Calico BGP Not Peering​

Windows nodes use Calico for networking with BGP peering to Linux nodes.

  1. Check Calico service on Windows:
Get-Service CalicoNode
Get-Service CalicoFelix
  1. Verify BGP peering from a Linux control plane node:
calicoctl node status

Windows nodes should appear in the peer list. If not, check:

  • TCP port 179 is open between Windows and Linux nodes
  • The Windows node's IP is in the Calico BGP configuration

Pod-to-Pod Communication Fails​

  1. Verify the Windows node has the correct pod CIDR assigned:
Get-HnsNetwork | Select-Object Name, Subnets
  1. Check that the HNS (Host Networking Service) network is healthy:
Get-HnsNetwork

If the network is in a bad state, restart the HNS service:

Restart-Service hns

Windows Feature Prerequisites​

The Ansible playbook installs required features. If running manually, verify:

Get-WindowsFeature Containers, Hyper-V

Both must show Installed. If not:

Install-WindowsFeature -Name Containers, Hyper-V -Restart