Investigate a cluster's state with kubectl

Diagnosing the root cause of Google Kubernetes Engine (GKE) issues often requiresinspecting the live state, configuration, and events of your Kubernetesresources in detail. To move beyond surface-level symptoms, you need tools todirectly query and interact with the cluster's control plane.

Use this page to learn essentialkubectl commands for investigating the livestate of your cluster. Learning these commands lets you gather detailedinformation directly from the Kubernetes control plane, helping you understandwhy a problem is occurring.

This information is important for Platform admins and operators who need toperform in-depth cluster health checks, manage resources, and troubleshootinfrastructure issues at a granular level. It's also essential forApplication developers for debugging application behavior, inspecting Podlogs and events, and verifying the exact state of their deployments within theKubernetes environment. For more information about the common roles and exampletasks that we reference in Google Cloud content, seeCommon GKE user roles and tasks.

Before you begin

Before you start, perform the following tasks:

  • Install kubectl.

  • Configure thekubectl command-line tool to communicate with your cluster:

    gcloudcontainerclustersget-credentialsCLUSTER_NAME\--location=LOCATION

    Replace the following:

    • CLUSTER_NAME: the name of your cluster.
    • LOCATION: the Compute Enginelocationof the control plane of your cluster. Provide a region for regionalclusters, or a zone for zonal clusters.

  • Review your permissions. To see if you have the required permissions to runkubectl commands, use thekubectl auth can-i command. For example, tosee if you have permission to runkubectl get nodes, run thekubectl authcan-i get nodes command.

    If you have the required permissions, the command returnsyes; otherwise,the command returnsno.

    If you lack permission to run akubectl command, you might see an errormessage similar to the following:

    Error from server (Forbidden): pods "POD_NAME" is forbidden: User"USERNAME@DOMAIN.com" cannot list resource "pods" in API group "" in thenamespace "default"

    If you don't have the required permissions, ask your cluster administratorto assign the necessary roles to you.

Get an overview of what's running

Thekubectl get command helps you to see an overall view of what's happeningin your cluster. Use the following commands to see the status of two of the mostimportant cluster components, nodes and Pods:

  1. To check if your nodes are healthy, view details about all nodes andtheir statuses:

    kubectlgetnodes

    The output is similar to the following:

    NAME                                        STATUS   ROLES    AGE     VERSIONgke-cs-cluster-default-pool-8b8a777f-224a   Ready    <none>   4d23h   v1.32.3-gke.1785003gke-cs-cluster-default-pool-8b8a777f-egb2   Ready    <none>   4d22h   v1.32.3-gke.1785003gke-cs-cluster-default-pool-8b8a777f-p5bn   Ready    <none>   4d22h   v1.32.3-gke.1785003

    Any status other thanReady requires additional investigation.

  2. To check if your Pods are healthy, view details about all Pods andtheir statuses:

    kubectlgetpods--all-namespaces

    The output is similar to the following:

    NAMESPACE   NAME       READY   STATUS      RESTARTS   AGEkube-system netd-6nbsq 3/3     Running     0          4d23hkube-system netd-g7tpl 3/3     Running     0          4d23h

    Any status other thanRunning requires additional investigation. Hereare some common statuses that you might see:

    • Running: a healthy, running state.
    • Pending: the Pod is waiting to be scheduled on a node.
    • CrashLoopBackOff: the containers in the Pod are repeatedlycrashing in a loop because the app starts, exits with an error,and is then restarted by Kubernetes.
    • ImagePullBackOff: the Pod can't pull the container image.

The preceding commands are only two examples of how you can use thekubectlget command. You can also use the command to learn more about many types ofKubernetes resources. For a full list of the resources that you can explore, seekubectl getin the Kubernetes documentation.

Tip: Add-o wide to yourkubectl get commands to see additionalinformation about your resources. For example, thekubectl get nodes -o widecommand adds the following columns to the output:Internal-IP,External-IP,OS-Image,Kernel-Version, andContainer-Runtime.

Learn more about specific resources

After you identify a problem, you need to get more details. An example of aproblem could be a Pod that doesn't have a status ofRunning. To get moredetails, use thekubectl describe command.

For example, to describe a specific Pod, run the following command:

kubectldescribepodPOD_NAME-nNAMESPACE_NAME

Replace the following:

  • POD_NAME: the name of the Pod experiencing issues.
  • NAMESPACE_NAME: the namespace that the Pod is in.If you're not sure what the namespace is, review theNamespace columnfrom the output of thekubectl get pods command.

The output of thekubectl describe command includes detailed information aboutyour resource. Here are some of the most helpful sections to review when youtroubleshoot a Pod:

  • Status: the current status of the Pod.
  • Conditions: the overall health and readiness of the Pod.
  • Restart Count: how many times the containers in the Pod haverestarted. High numbers can be a cause of concern.
  • Events: a log of important things that have happened to this Pod,like being scheduled to a node, pulling its container image, and whetherany errors occurred. TheEvents section is often where you can find thedirect clues to why a Pod is failing.

Like thekubectl get command, you can use thekubectl describe command tolearn more about multiple types of resources. For a full list of the resourcesthat you can explore, seekubectl describein the Kubernetes documentation.

What's next

Except as otherwise noted, the content of this page is licensed under theCreative Commons Attribution 4.0 License, and code samples are licensed under theApache 2.0 License. For details, see theGoogle Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.

Last updated 2026-02-18 UTC.