Kubernetes: The Clear Path

A minimalistic guide to learning Kubernetes. Follow these steps sequentially to move from zero to cluster operator.

Step 01

Environment Setup

Running a cluster requires docker, kubectl, and kind. Use the local setup script to audit your machine.

# Run the local setup script
chmod +x ./setup_k8s.sh
./setup_k8s.sh

Once finished, verify your installation with: kind version and kubectl version --client.

Step 02

The Mental Model

Kubernetes is a reconciliation loop. You declare what you want (Desired State), and Kubernetes works to make it happen (Actual State).

The Brain (Control Plane)

API Server: The front door for all commands.
etcd: The database that stores the cluster's truth.
Scheduler: Decides which node gets which work.

The Muscle (Worker Nodes)

Kubelet: The agent that runs containers on the node.
Kube-Proxy: Handles the networking and routing.

Step 03

Core Resources

These are the building blocks you will use 90% of the time.

Resource	Purpose
`Pod`	The smallest unit; one or more containers.
`Deployment`	Manages Pods (scaling, rolling updates).
`Service`	A stable IP/DNS name to reach your Pods.
`Namespace`	A logical boundary to isolate projects.
`ConfigMap`	Injects configuration into your app.

Step 04

Practical Labs

Work through these drills on your local machine to build muscle memory.

Lab 1: Bootstrap & Deploy

10 min

Create a cluster and run your first application.

kind create cluster --name lab
kubectl create deployment web --image=nginx:alpine
kubectl expose deployment web --port=80 --type=ClusterIP
kubectl port-forward svc/web 8080:80

Result: Visit localhost:8080 in your browser to see Nginx.

Lab 2: Scale & Heal

5 min

Watch Kubernetes maintain your desired state.

kubectl scale deployment web --replicas=3
kubectl get pods
# Kill a pod and watch it restart:
kubectl delete pod [pod-name]
kubectl get pods -w

Lab 3: Rollout & Rollback

10 min

Update your application version safely.

kubectl set image deployment web nginx=nginx:1.27
kubectl rollout status deployment web
# Undo a mistake:
kubectl rollout undo deployment web

Step 05

How to Troubleshoot

When things break, follow the standard flow: Get → Describe → Logs → Exec.

CrashLoopBackOff

App starts then fails. Check kubectl logs [pod] for app-level errors or probe failures.

ImagePullBackOff

Incorrect tag or private registry auth issue. Run kubectl describe pod to see pull events.

Pending (No Nodes)

No resources available or taints/selectors mismatch. Check describe pod events for scheduling errors.

OOMKilled

Container exceeded its memory limit. Review resources.limits vs actual app usage.

Service not reachable

Verify label selectors: kubectl get endpoints should list Pod IPs. No endpoints = no traffic.

DNS resolution failure

Debug from inside: kubectl exec -it [pod] -- nslookup my-service. Checks CoreDNS health.

Ingress 404/503

404: Path/Host mismatch. 503: Backend Service or Pods are unhealthy. Check Ingress controller logs.

PVC stuck in Pending

No matching StorageClass or provisioner is down. Run kubectl describe pvc [name].

Mount errors

Volume is already used by another node (RWO) or path doesn't exist. Check node logs / events.

Node Pressure (Eviction)

Node is out of disk or memory. K8s will evict low-priority Pods. kubectl get nodes shows status.

RBAC Forbidden

ServiceAccount lacks permissions. Debug with kubectl auth can-i [verb] [resource].

Zombie Pods

Pods stuck in Terminating. Force delete with --grace-period=0 --force (use with caution).

HPA not scaling

Missing resource requests or Metrics Server not installed. Run kubectl get hpa to see status.

Resource Quota reached

Namespace limits hit. New Pods will be denied by the API. Check kubectl get quota.

Step 06

Command Reference

Command	Impact	What it does
`kind create cluster`	Local	Creates a local cluster.
`kubectl get pods`	Control	Lists all pods in the current namespace.
`kubectl get nodes`	Control	Shows cluster health and node status.
`kubectl describe pod [name]`	Control	Deep dive into pod events and status.
`kubectl logs [name]`	Data	Streams container logs.
`kubectl exec -it [name] -- sh`	Data	Opens a shell inside a container.
`kubectl apply -f [file.yaml]`	Control	Apply a configuration file.
`kubectl delete -f [file.yaml]`	Control	Remove resources defined in a file.