Skip to main content
In this lesson you’ll troubleshoot a Kubernetes cluster where an application Deployment never becomes Ready. We’ll:
  • Inspect the cluster and the failing Deployment.
  • Identify which control-plane components are failing.
  • Fix typos and misconfigured hostPath volumes in static Pod manifests.
  • Confirm the cluster returns to a healthy state and Pods are scheduled.
Quick tip — make kubectl shorter and enable shell autocompletion:
Set an alias and enable bash completion so you can use k as a short form for kubectl.

​
1) Inspect the cluster and the failing Deployment

Start by verifying nodes and workloads:
List Deployments in the default namespace:
Describe the problematic Deployment to compare desired vs available replicas:
Check the ReplicaSet and its Pods:
Describe the Pod to gather scheduler-related clues:
If the Pod shows Node: <none>, it hasn’t been scheduled. The kube-scheduler is responsible for assigning Pods to nodes — check the scheduler next.

​
2) kube-scheduler CrashLoopBackOff — fix static manifest typo

List control-plane Pods in the kube-system namespace:
Describe the scheduler Pod to see why the container fails:
This indicates the scheduler executable specified in the static Pod manifest is incorrect. Static Pod manifests are read by the kubelet from the control plane host directory /etc/kubernetes/manifests. Edit the manifest on the control plane host to correct the command.
Static control-plane Pods are managed by kubelet reading manifest files from /etc/kubernetes/manifests. Edit those files on the control plane host to fix static Pod configuration.
Example of the incorrect command in the static manifest:
Correct the executable name to the proper kube-scheduler:
Save the manifest on the host. Kubelet will detect the change and recreate the static Pod. Watch the kube-system Pods until the scheduler is Running/Ready:
Once the scheduler is healthy, pending Pods should be scheduled. If not, proceed to the next step to check the controller manager.

​
3) Scale the Deployment and check kube-controller-manager

Try scaling the Deployment:
If the Deployment reports 1/2 (desired 2 but only 1 available), the controller manager may be failing. The controller-manager runs the control loops that reconcile Deployments and ReplicaSets. Check the controller manager Pod:
Describe and inspect logs for the controller manager Pod. A common cause is an incorrect --kubeconfig flag in the static manifest, pointing to a non-existent file:
If the kubeconfig path is wrong, the container will fail with “no such file or directory” or a similar message. Update the --kubeconfig flag to point to the correct file:
Save the manifest. After kubelet restarts the static Pod, verify the controller manager becomes Running/Ready:
When the controller manager is healthy, scaling operations should be processed by the ReplicaSet controller. Confirm additional Pods are created:

​
4) controller-manager: missing CA file — fix hostPath volume mapping

If scaling further fails (for example, scaling to 3 replicas but only 2 are created), check controller manager logs for filesystem/volume errors:
This indicates the controller-manager container cannot access the host’s PKI files, often due to a misconfigured hostPath volume in the static manifest. Inspect /etc/kubernetes/manifests/kube-controller-manager.yaml and review the volumes: section. Example of an incorrect hostPath mapping:
Fix the hostPath to point to the actual PKI directory on the host:
Save the manifest. After kubelet restarts the static Pod, confirm the controller manager becomes Ready and that the Deployment now reaches the desired replica count:
The left side is a web-based lab prompt about Kubernetes (deployments, replicasets and POD scaling). The right side is a terminal window filled with long base64-like certificate/key text and a root@controlplane prompt.

​
Troubleshooting checklist

Use this quick checklist when control-plane components fail or Pods remain pending. After any change to static manifests, kubelet will automatically restart the static Pod. Monitor status with:

​
Summary

  • If Pods are pending with Node: <none>, start by checking the kube-scheduler.
  • Static control-plane Pods are defined as manifest YAMLs in /etc/kubernetes/manifests and are managed by kubelet.
  • Common failures are caused by simple typos in the command: field or incorrect flags like --kubeconfig.
  • Filesystem errors (missing CA or kubeconfig) most often point to an incorrect hostPath mapping in the static manifest.
  • Edit the static manifest on the control-plane host, save it, then watch kubectl get pods -n kube-system --watch to confirm components return to Running/Ready.
  • Once control-plane components are healthy, Deployments and ReplicaSets will reconcile and Pods will be scheduled.

Watch Video