Kubernetes Fix, Crash & Optimization Guide

Kubernetes is a container orchestrator that automates deployment, scaling, and management of containerized applications across a cluster of nodes. Developers and SREs use it to run resilient services, while local tools like minikube, kind, and k3s bring a cluster to a laptop.

Install / First Setup

• kubectl: install the CLI that matches your cluster's minor version (±1 skew is supported). On macOS brew install kubectl; on Linux via the official kubernetes-apt or download the binary from dl.k8s.io.
• Local cluster: minikube start (virtualized/containerized node), kind create cluster (Docker-based nodes), or k3s server for a lightweight single-binary cluster.
• Connect: point kubectl at a cluster by placing a kubeconfig at ~/.kube/config or setting KUBECONFIG=/path/to/config.
• Verify: kubectl cluster-info and kubectl get nodes.

Common Issues & Fixes

The connection to the server was refused

Cause: no current kubeconfig context, or the API server / local cluster isn't running. Fix: check kubectl config current-context. For local clusters start them (e.g. minikube start). Confirm the cluster is up before running commands.

Context / cluster not found or wrong cluster

Cause: multiple kubeconfigs or a stale current context. Fix: list contexts with kubectl config get-contexts, then switch with kubectl config use-context <name>. Set KUBECONFIG explicitly if you juggle several files.

Pod stuck in CrashLoopBackOff

Cause: the container exits repeatedly — usually an app error, missing env/config, or a bad startup probe. Fix: inspect with kubectl logs <pod> and kubectl describe pod <pod> for the last exit code and events. Fix the application or its manifest (env, image tag, probe thresholds), then kubectl rollout restart deployment <name>.

ImagePullBackOff / ErrImagePull

Cause: wrong image tag, private registry without pull secret, or registry unreachable. Fix: verify the tag exists; create a imagePullSecret and reference it in the pod spec (or in the ServiceAccount); check network egress from the node.

Node NotReady / pods Pending forever

Cause: node ran out of CPU/memory, taints, or kubelet not reporting. Fix: kubectl describe node <node> and kubectl get events --sort-by=.lastTimestamp. Add resource requests/limits so the scheduler can place pods, or scale the node pool.

Performance & Optimization

• Set resource requests and limits: every workload should declare resources.requests and resources.limits for CPU and memory so the scheduler packs pods efficiently and the kubelet can throttle/evict predictably.
• Low-End / local laptop: cap the local cluster (minikube --cpus/--memory, kind node memory, k3s default) to ~2–4 GB; run only the namespaces you need.
• Mid-range: 4–8 GB for a few services; enable the metrics-server so kubectl top works for right-sizing.
• Workstation / production node: size nodes with headroom for system pods; use HorizontalPodAutoscaler on CPU/memory or custom metrics; prefer fewer large nodes or many small nodes deliberately based on bin-packing vs. blast-radius tradeoffs.
• Image efficiency: use distroless/slim base images and imagePullPolicy: IfNotPresent in dev to avoid redundant pulls.

Version & Compatibility Notes

• kubectl supports a ±1 minor-version skew from the API server. Running a much newer or older kubectl can surface odd errors — consult official release notes and match versions.
• Kubernetes has a roughly quarterly minor release cadence with a defined support window; EOL versions stop receiving patches. Verify your platform's supported version before upgrading.
• API deprecations (e.g. moved or removed resource fields) appear per release — consult official docs when upgrading.

FAQ

Q: What's the difference between kubectl and a local cluster tool like minikube? A: kubectl is the client that talks to any Kubernetes API server. minikube, kind, and k3s are tools that actually create a cluster (a node running the control plane) that kubectl then connects to via kubeconfig.

Q: How do I see why a pod keeps crashing? A: Run kubectl logs <pod> (add --previous for the crashed container) and kubectl describe pod <pod> to read exit codes and Events. Then fix the app or its manifest and restart the deployment.

Q: How much RAM does a local Kubernetes cluster need? A: A minimal single-node setup can run in 2–4 GB, but several services with real workloads comfortably need 8 GB+. Use the memory flags of your local tool to cap consumption.

Q: kubectl says "context not found" — what now? A: Your kubeconfig has no current context. Run kubectl config get-contexts, pick one, and kubectl config use-context <name>. If the list is empty, point KUBECONFIG at the correct file or merge contexts.

Q: Should I set CPU limits on every pod? A: Set CPU requests reliably so the scheduler can place pods; CPU limits cause throttling under bursty load and are often left unset in production while memory limits are kept to protect the node.

Q: How do I clean up a stuck namespace in Terminating state? A: A namespace stuck Terminating usually has finalizers blocking deletion. Inspect with kubectl get namespace <ns> -o json and remove the offending finalizers, or investigate the API resources still referenced. Proceed carefully in shared clusters.

Related Guides

• Docker Fix & Optimization Guide
• Helm Fix & Optimization Guide
• Podman Fix & Optimization Guide

Accuracy Note

Commands and paths reflect common, real-world setups as of 2026-08. Always verify against your installed version and OS. When in doubt, consult the official Kubernetes documentation.