Kubernetes Beginner Guide

1) What Kubernetes Actually Is

Kubernetes (K8s) is an orchestrator. It takes a desired state you declare — “I want three copies of this app on port 80” — and makes the cluster match it.

Useful mental model:

• Declarative: describe the end state, not the sequence.
• Distributed: control plane manages worker nodes; they can be VMs, bare metal, or laptops.
• Self-healing: crashed pods are replaced by default.
• Extensible: CRDs, operators, and sidecars let you teach K8s new tricks.

If Docker is “run one process on one machine”, Kubernetes is “run many processes across many machines safely”.

2) Core Objects You Must Know

Rule of thumb: in most beginner YAML, you’ll write a Deployment + Service + (optionally) ConfigMap/Secret.

3) The kubectl Cheat Codes

kubectl cluster-info         # sanity check: are we connected?
kubectl get nodes            # worker machines
kubectl get pods -A          # every pod in every namespace
kubectl get svc -A          # services
kubectl describe pod <name> # why is this pod sad?
kubectl logs <pod-name>      # app stdout/stderr
kubectl apply -f file.yaml   # create/update resources
kubectl delete -f file.yaml  # remove resources
kubectl get events --sort-by='.lastTimestamp'  # what's happening right now

Flags you’ll use constantly: -n <namespace>, -l app=myapp, --all-namespaces or -A, -o yaml, -o wide.

4) Start Local — Don’t Touch the Cloud Yet

Two common local options:

• k3s: lightweight, single-node, great for learning and Raspberry Pi.
• kind: Kubernetes in Docker; excellent for CI and fast iteration.

Quickstart: kind (recommended for first day)

kind create cluster
kind get clusters
kubectl cluster-info --context kind-kind

kind ships kubectl context automatically.

Quickstart: k3s

curl -sfL https://get.k3s.io | sh -
mkdir -p ~/.kube
sudo k3s kubectl config view --raw > ~/.kube/config
chmod 600 ~/.kube/config

kubectl should work on its own after this.

5) Your First Real Workload

Minimal Deployment + Service example for an NGINX web server.

deploy.yaml

apiVersion: apps/v1
kind: Deployment
metadata:
  name: hello-web
  namespace: default
spec:
  replicas: 2
  selector:
    matchLabels:
      app: hello-web
  template:
    metadata:
      labels:
        app: hello-web
    spec:
      containers:
      - name: nginx
        image: nginx:1.27
        ports:
        - containerPort: 80
        resources:
          requests:
            cpu: "100m"
            memory: "64Mi"
          limits:
            cpu: "250m"
            memory: "128Mi"

svc.yaml

apiVersion: v1
kind: Service
metadata:
  name: hello-web
  namespace: default
spec:
  type: ClusterIP
  selector:
    app: hello-web
  ports:
  - port: 80
    targetPort: 80

Apply:

kubectl apply -f deploy.yaml -f svc.yaml
kubectl get pods -l app=hello-web
kubectl rollout status deployment/hello-web

Test it:

kubectl run -it --rm shell --image=busybox:1.36 --restart=Never -- wget -O- hello-web

6) The Big Gotchas Beginners Hit

1. “kubectl says Deployed but it’s still not working.” Check events, describe, and logs first.
2. Omitting labels or mismatched selectors. That’s the #1 YAML mistake.
3. Forgetting ports and protocols. Services route by port, not path (Ingress does path routing).
4. image PullPolicy. Always pin the image digest or tag; set imagePullPolicy: IfNotPresent when local / kind / k3s caches.
5. Running multi-container pods without knowing why. That’s for sidecars and shared volumes — not for separate apps.

7) Day-1 Operations You Actually Need

kubectl config current-context   # where am I connected?
kubectl config use-context <name> # switch
kubectl get pods -A              # spot crashed pods quickly
kubectl describe pod <name>      # first troubleshooting step
kubectl logs <pod> -c <container> # multi-container logs
kubectl rollout restart deployment/<name>
kubectl top node / kubectl top pod  # needs metrics-server

8) Storage in 30 Seconds

• Use ConfigMap for config.
• Use Secret for credentials.
• Use emptyDir when a container just needs scratch space.
• Use hostPath only on single-node clusters (kind, k3s) — never in production multi-node.
• Use PersistentVolumeClaim for real storage (databases, uploads).

Database pods in production should almost always have a PVC with a real StorageClass behind it. For local testing, emptyDir is fine.

9) Ingress vs Service

A Service is internal load balancing. An Ingress is an HTTP(S) router/load balancer at the cluster edge (virtual-host + path-based routing).

For learning: use a Service first. Add Ingress (traefik/nginx ingress controller) when you need hostnames and TLS.

10) Key Third-Party Tools in the Ecosystem

Don’t install all of these day one. Learn with plain YAML first so kubectl doesn’t feel like magic.

11) Real Learning Roadmap

1. Write and deploy one Deployment + Service by hand.
2. Add a ConfigMap, expose an env var, confuse yourself, fix it.
3. Add a Secret (base64 is not encryption — internalize this early).
4. Add a readinessProbe; watch rolling behavior.
5. Run two namespaces; practice kubens.
6. Install an Ingress controller and route traffic by hostname.
7. Add HPA and watch scaling.

12) Mental Model for Scaling

Kubernetes scales:

• Pod level — multiple pods behind a Service.
• Node level — add workers or increase instance size.
• Cluster level — multiple clusters per workload (e.g. staging/prod) instead of one giant cluster.

13) Security Checklist for Your First Cluster

• Enable RBAC (on by default in modern distributions).
• Never run containers as root unless absolutely required.
• Set readOnlyRootFilesystem: true, drop capabilities, and run as non-root.
• Use NetworkPolicy to least-privilege pod communication.
• Avoid hostNetwork: true, hostPID: true, and privileged: true.

14) Common Troubleshooting Order

1. Is the pod Running?
2. If CrashLoopBackOff — kubectl logs and kubectl describe.
3. If ImagePullBackOff — tag, policy, and registry auth.
4. If not reachable — is it the port, selector, or network?
5. If Ingress not working — check controller and annotations.

15) One-Line Summary

Kubernetes lets you describe distributed systems reliably, then enforces that description automatically across machines — replacing shell scripts with policy.

16) Recommended Reads

• Kubernetes.io/docs/concepts (read concepts, not every page)
• “Kubernetes Up & Running” by Kelsey Hightower
• k8s docs task pages (kubectl run/apply/expose) are underrated

If you want, I can next create hands-on labs from this guide — for example: “Lab 1 — deploy a stateless web app”, or turn this into a printable one-pager for your home lab.