Debug Pods and ReplicationControllers

    You need to have a Kubernetes cluster, and the kubectl command-line tool must be configured to communicate with your cluster. It is recommended to run this tutorial on a cluster with at least two nodes that are not acting as control plane hosts. If you do not already have a cluster, you can create one by using minikube or you can use one of these Kubernetes playgrounds:

    To check the version, enter .

    • You should be familiar with the basics of and with Pods’ lifecycles.

    The first step in debugging a pod is taking a look at it. Check the current state of the pod and recent events with the following command:

    Look at the state of the containers in the pod. Are they all Running? Have there been recent restarts?

    Continue debugging depending on the state of the pods.

    Insufficient resources

    You may have exhausted the supply of CPU or Memory in your cluster. In this case you can try several things:

    • Terminate unneeded pods to make room for pending pods.

    • Check that the pod is not larger than your nodes. For example, if all nodes have a capacity of cpu:1, then a pod with a request of will never be scheduled.

      You can check node capacities with the kubectl get nodes -o <format> command. Here are some example command lines that extract the necessary information:

      1. kubectl get nodes -o yaml | egrep '\sname:|cpu:|memory:'
      2. kubectl get nodes -o json | jq '.items[] | {name: .metadata.name, cap: .status.capacity}'

    Using hostPort

    When you bind a pod to a hostPort there are a limited number of places that the pod can be scheduled. In most cases, is unnecessary; try using a service object to expose your pod. If you do require hostPort then you can only schedule as many pods as there are nodes in your container cluster.

    If a pod is stuck in the Waiting state, then it has been scheduled to a worker node, but it can’t run on that machine. Again, the information from kubectl describe ... should be informative. The most common cause of Waiting pods is a failure to pull the image. There are three things to check:

    • Make sure that you have the name of the image correct.
    • Run a manual on your machine to see if the image can be pulled.

    Once your pod has been scheduled, the methods described in Debug Running Pods are available for debugging.

    ReplicationControllers are fairly straightforward. They can either create pods or they can’t. If they can’t create pods, then please refer to the to debug your pods.

    You can also use kubectl describe rc ${CONTROLLER_NAME} to inspect events related to the replication controller.