kubectl Basics for Troubleshooting

kubectl is the main command-line tool you use to inspect, troubleshoot, and manage Kubernetes resources. Before going deeper into pods and deployments, you need to get comfortable asking the cluster what is happening.

Kubernetes Field Notes · Foundation Level · Estimated reading time: 18 minutes

What this lesson covers

This lesson introduces the kubectl commands you will use constantly when learning and troubleshooting Kubernetes.

By the end, you should understand how to:

• Check which cluster kubectl is using
• List nodes, namespaces, pods, deployments, and services
• Use wide output for more detail
• Describe resources for human-readable troubleshooting detail
• Read pod logs
• View cluster events
• Exec into a container for inspection
• Use port-forward for quick local testing
• Clean up the resources created in the lab

Before you start

This lab assumes you already completed the local Kubernetes lab setup and have a kind cluster available.

Start Docker Desktop, then open PowerShell and confirm your cluster is available:

kubectl config current-context
kubectl get nodes

If your kind cluster does not exist anymore, recreate it:

kind create cluster --name stealth-k8s-lab

Then confirm kubectl is pointed at the correct context:

kubectl config current-context

You should see:

kind-stealth-k8s-lab

kubectl mental model

kubectl sends requests to the Kubernetes API server. The API server is part of the control plane. When you run a command like kubectl get pods, you are asking the cluster for information about pod resources.

The basic pattern looks like this:

kubectl [action] [resource] [name] [flags]

Examples:

kubectl get pods
kubectl describe pod nginx-lab
kubectl logs nginx-lab
kubectl delete deployment nginx-lab

The official kubectl reference describes commands such as get, describe, logs, exec, and explain as core ways to interact with cluster resources.

Step 1: Check your current context

Run:

kubectl config current-context

This tells you which cluster kubectl is currently pointed at.

In this lab, you want:

kind-stealth-k8s-lab

Why this matters

If you work with multiple clusters, the current context matters a lot. Running commands against the wrong context is one of the easiest ways to confuse yourself or affect the wrong environment.

Step 2: List nodes

Run:

kubectl get nodes

This shows the nodes registered with the cluster.

In a basic kind cluster, you should see one node:

NAME                            STATUS   ROLES           AGE   VERSION
stealth-k8s-lab-control-plane   Ready    control-plane   10m   v1.xx.x

What to look for

• NAME: The node name.
• STATUS: Whether the node is Ready.
• ROLES: The role of the node.
• AGE: How long the node has existed.
• VERSION: The Kubernetes version running on the node.

Step 3: List namespaces

Run:

kubectl get namespaces

Namespaces are used to organize Kubernetes resources inside a cluster.

You will usually see namespaces such as:

default
kube-node-lease
kube-public
kube-system
local-path-storage

Why this matters

Many beginner mistakes happen because people look in the wrong namespace. If you run kubectl get pods without specifying a namespace, kubectl only shows pods in the current namespace, usually default.

Step 4: List pods across all namespaces

Run:

kubectl get pods -A

The -A flag means all namespaces.

This gives you a broader view of what is running in the cluster, including Kubernetes system components.

What to look for

• NAMESPACE: Where the pod lives.
• NAME: The pod name.
• READY: How many containers in the pod are ready.
• STATUS: Current pod status.
• RESTARTS: How many times containers restarted.
• AGE: How long the pod has existed.

Step 5: Create a small test deployment

Create an nginx deployment:

kubectl create deployment nginx-troubleshooting-lab --image=nginx:latest

Now list deployments:

kubectl get deployments

Then list pods:

kubectl get pods

Kubernetes creates a pod managed by the deployment.

Step 6: Use wide output

Run:

kubectl get pods -o wide

Wide output shows more detail, including information such as pod IP and node placement.

This is useful when you want to know where a pod is running or what IP Kubernetes assigned to it.

Step 7: Describe the deployment

Run:

kubectl describe deployment nginx-troubleshooting-lab

The Kubernetes docs describe describe as showing detailed information about selected resources, including related resources such as events.

What to look for

• Labels and selectors
• Replica counts
• Pod template details
• Container image
• Events

Do not try to memorize the full output. Learn where to look.

Step 8: Describe the pod

First get the pod name:

kubectl get pods

Then describe the pod by replacing <pod-name> with your actual pod name:

kubectl describe pod <pod-name>

What to look for

• Pod status
• Container state
• Image used
• Node placement
• IP address
• Volume mounts
• Events at the bottom

Commands such as get, describe, logs, exec, and explain are core ways to inspect and interact with Kubernetes resources.

Step 9: Read pod logs

Run:

kubectl logs <pod-name>

The official kubectl logs reference says this command prints logs for a container in a pod, and the container name is optional when the pod has only one container.

For nginx, you may not see much until the container receives traffic. That is normal.

Step 10: Follow logs

To stream logs live, run:

kubectl logs -f <pod-name>

Press Ctrl+C to stop following logs.

Step 11: View events

Run:

kubectl get events

Events are useful when Kubernetes is telling you what happened: scheduling decisions, image pulls, failed mounts, restarts, and other resource activity.

To sort events by creation time, run:

kubectl get events --sort-by=.metadata.creationTimestamp

The official kubectl reference includes kubectl events and related event inspection commands as part of the kubectl command set.

Step 12: Exec into the pod

You can run a command inside a container with kubectl exec. The official reference describes exec as executing a command in a container.

Run:

kubectl exec -it <pod-name> -- /bin/sh

Inside the container, run:

hostname
ps
ls
exit

This can be useful for inspection, but do not build a habit of manually fixing containers from the inside.

Step 13: Create a service

Create a service for the nginx deployment:

kubectl expose deployment nginx-troubleshooting-lab --port=80 --target-port=80 --type=ClusterIP

List services:

kubectl get services

You should see a service named nginx-troubleshooting-lab.

Step 14: Use port-forward for local testing

Port-forwarding lets you forward a local port on your machine to a pod or service in the cluster. The official reference describes kubectl port-forward as forwarding one or more local ports to a pod, and it can also use a resource type and name such as a deployment.

Run:

kubectl port-forward service/nginx-troubleshooting-lab 8080:80

Keep that PowerShell window open. Then open a browser and go to:

http://localhost:8080

You should see the nginx welcome page.

Press Ctrl+C in PowerShell to stop the port-forward session.

Step 15: Generate a little traffic and check logs again

After visiting the nginx page, get the pod name again:

kubectl get pods

Then check logs:

kubectl logs <pod-name>

You should now see nginx access log entries.

Step 16: Get YAML output

kubectl can show resources in YAML format:

kubectl get deployment nginx-troubleshooting-lab -o yaml

This is useful because Kubernetes resources are API objects. YAML output lets you see what Kubernetes currently knows about the resource.

The output will be long. For now, notice:

• metadata
• spec
• status

Step 17: Use kubectl explain

kubectl can also explain resource fields:

kubectl explain deployment
kubectl explain deployment.spec
kubectl explain pod.spec.containers

This is a helpful way to explore Kubernetes object structure without leaving the terminal.

Step 18: Clean up the lab resources

Delete the service:

kubectl delete service nginx-troubleshooting-lab

Delete the deployment:

kubectl delete deployment nginx-troubleshooting-lab

Confirm the resources are gone:

kubectl get deployments
kubectl get pods
kubectl get services

Basic troubleshooting flow

When something does not look right, use a simple inspection flow:

kubectl config current-context
kubectl get namespaces
kubectl get pods -A
kubectl get pods -o wide
kubectl describe pod <pod-name>
kubectl logs <pod-name>
kubectl get events --sort-by=.metadata.creationTimestamp

That sequence answers a lot of beginner troubleshooting questions:

• Am I pointed at the right cluster?
• Am I looking in the right namespace?
• Is the pod running?
• Which node is it on?
• What does Kubernetes say happened?
• What does the application log say?

Check your understanding

Use these questions to test whether the kubectl troubleshooting flow made sense.

1. What does kubectl communicate with?
2. Why should you check your current context before making changes?
3. What does kubectl get nodes show?
4. What does the -A flag do?
5. What is the difference between kubectl get and kubectl describe?
6. Why are events useful?
7. What does kubectl logs show?
8. What does kubectl exec let you do?
9. Why should exec not become your normal way to fix containers?
10. What does port-forwarding let you test?
11. Why is YAML output useful?
12. What are three things you should check when a pod is not working?