Exploring Cluster Status with kubectl: A Practical Guide

Previously in this course, we covered Setting Up Your Local Environment: kubectl and Local Clusters. Now that you have a functioning environment, this lesson adds the ability to peer into the "black box" of your cluster to verify that everything is running correctly.

In the world of distributed systems, "it works on my machine" isn't enough. You need to verify that your cluster nodes are healthy, your API server is reachable, and the system components are ready to receive your workloads.

The CLI as Your Window into Cluster Health

The primary way we interact with a Kubernetes cluster is through the API server, which acts as the gateway for all administrative commands. When you run kubectl, you are sending requests to this server. If that connection fails, you can't manage your resources.

To understand the health of the entire system, we focus on three specific areas:

1. Connectivity: Is the API server responding?
2. Node Health: Are the worker nodes ready to host containers?
3. Control Plane Status: Are the internal services running correctly?

Checking API Server Connectivity

Before you do anything else, verify that your client can reach the cluster. If kubectl cannot talk to the API server, all other commands will fail.

Use the cluster-info command to verify the connection:

Bash
kubectl cluster-info

This command returns the URL of the Kubernetes control plane. If you see an output indicating the "Kubernetes control plane is running," you have successfully established a connection. If this command hangs or returns a "connection refused" error, check your local cluster provider (like Minikube or Kind) to ensure it is actually started.

Listing Cluster Nodes

Nodes are the workhorses of your infrastructure. As we discussed in Anatomy of a Kubernetes Cluster: Nodes and Architecture, every pod runs on a node. If a node is "NotReady," your applications cannot be scheduled or executed.

To list the nodes in your cluster, use:

Bash
kubectl get nodes

The output will include a STATUS column. You want to see Ready.

Inspecting Cluster Component Status

Beyond nodes, Kubernetes runs several critical system components (like the scheduler and controller manager) within the kube-system namespace. You can check their health by querying the "componentstatuses" resource:

Bash
kubectl get componentstatuses

Note: In modern Kubernetes versions, this command is being deprecated in favor of checking the health of the individual pods within the system namespace. If you don't get meaningful output, don't panic—it usually means your API server is secured or configured in a way that limits this specific view.

A more modern way to check if the control plane is healthy is to list the pods in the system namespace:

Bash
kubectl get pods -n kube-system

You should see all pods in a Running state with a status of 1/1 (meaning 1 container ready out of 1 total).

Hands-on Exercise

It's time to verify your own environment. Follow these steps in your terminal:

1. Verify Connection: Run kubectl cluster-info and note the control plane URL.
2. Check Nodes: Run kubectl get nodes and confirm your node is in the Ready state.
3. Explore System Pods: Run kubectl get pods -n kube-system and count how many pods are currently Running.

Common Pitfalls

• Wrong Context: You might be connected to a different cluster than you think. Always run kubectl config current-context if you aren't sure which cluster you are querying.
• Namespace Confusion: If you run kubectl get pods and see nothing, you might be looking at the default namespace. Remember to add -n kube-system if you are looking for cluster-level infrastructure.
• Network Latency: If kubectl commands are slow, your connection to the API server might be unstable. This is common when using remote clusters over a VPN.

FAQ

Q: What should I do if my node is "NotReady"? A: Check the node's events using kubectl describe node <node-name>. Look for "Ready" or "MemoryPressure" events at the bottom of the output.

Q: Can I see more details than just the status? A: Yes! Use kubectl get nodes -o wide to see extra information like the internal IP address and the OS version.

Q: Does "Running" mean the app is working? A: Not necessarily. "Running" only means the container has started. The application inside might still be crashing or failing its internal health checks. We will cover how to debug those issues in later lessons.

Recap

In this lesson, we moved from managing basic containers to observing the health of a distributed cluster. We verified API server connectivity, inspected node readiness, and learned how to check the status of core system components. These commands are your first line of defense when things go wrong.

Up next: We will dive into Namespaces, the fundamental way Kubernetes allows you to slice a single cluster into multiple virtual environments.