Kubernetes basics

In this tutorial you will run a small Kubernetes cluster on your own laptop, deploy a web server with three copies, expose it with a Service, scale it, update it without downtime, break it on purpose and watch Kubernetes repair it. Everything runs locally and costs nothing.

Prerequisites: Docker installed and running (see *Docker: images and containers*), kubectl installed, and either kind (Kubernetes in Docker) or Minikube. This lesson uses kind. The install pages on kubernetes.io and kind.sigs.k8s.io cover Windows, macOS and Linux. Check with kubectl version --client and kind version. You need about 4 GB of free RAM.

Docker runs one container on one machine. Real systems need more: run five copies for traffic, restart a container that crashes, move work to another machine when one dies, roll out a new version without downtime, and give all copies one stable address.

Kubernetes (often written K8s) is a system that does this for you. You tell it the state you want ("three copies of this image, always") and it keeps reality matching that wish. Think of a restaurant manager: you say "always keep three chefs at the counter" and when one goes home sick, the manager calls a replacement without being asked.

You do not need Kubernetes for a small project; Docker Compose or a managed platform is simpler. Learn it because many companies run on it and interviews ask about it.

Pods are mortal. Each Pod gets its own IP address that changes whenever it is replaced, so you never talk to a Pod directly. You create a Deployment (which creates and replaces Pods) and a Service (which gives them one steady name).

The cluster has a control plane (the brain: an API server you talk to with kubectl, a store of the desired state, a scheduler that picks nodes and controllers that fix differences) and worker nodes that run your Pods. In managed services such as Amazon EKS, Azure AKS and Google GKE, the provider runs the control plane for you.

Kubernetes is driven by YAML files called manifests. Create a file web.yaml. It has two objects separated by ---: a Deployment of three nginx Pods and a Service in front of them.

apiVersion: apps/v1
kind: Deployment
metadata:
  name: web
spec:
  replicas: 3
  selector:
    matchLabels:
      app: web
  template:
    metadata:
      labels:
        app: web
    spec:
      containers:
        - name: nginx
          image: nginx:1.27
          ports:
            - containerPort: 80
          resources:
            requests:
              cpu: 50m
              memory: 64Mi
            limits:
              memory: 128Mi
          readinessProbe:
            httpGet:
              path: /
              port: 80
            initialDelaySeconds: 2
            periodSeconds: 5
---
apiVersion: v1
kind: Service
metadata:
  name: web
spec:
  selector:
    app: web
  ports:
    - port: 80
      targetPort: 80

replicas: 3 is the desired count. The selector must match the Pod labels: that is how the Deployment knows which Pods are its own, and how the Service finds them. requests tell the scheduler how much to reserve; limits cap use. The readiness probe means a Pod receives traffic only once it answers on port 80.

kubectl apply -f web.yaml
kubectl get deployments
kubectl get pods
kubectl get service web

apply is declarative, like Terraform: run it again after editing the file and Kubernetes changes only what differs.

The Service has a cluster-internal IP, so your browser cannot reach it directly. For local testing use port-forward, which tunnels a port on your laptop to the Service.

kubectl port-forward service/web 8080:80

Leave this running. In another terminal run curl http://localhost:8080 (or open the URL in a browser). You should get the nginx welcome page. Press Ctrl+C in the first terminal to stop forwarding.

In real clusters you expose apps to the internet with a Service of type LoadBalancer (the cloud creates a public load balancer, which costs money) or with an Ingress (one entry point that routes by host name and path to many Services). Ingress is a good next topic once the basics feel comfortable.

kubectl scale deployment web --replicas=5
kubectl get pods

kubectl set image deployment/web nginx=nginx:1.27-alpine
kubectl rollout status deployment/web
kubectl rollout history deployment/web

scale changes the replica count immediately. set image changes the container image, which starts a rolling update: new Pods are started and old ones stopped gradually, and readiness probes make sure traffic only reaches healthy Pods, so users see no downtime.

In real projects you change the image in the YAML file and run kubectl apply -f again, so Git stays the source of truth. kubectl set image is fine for quick experiments. If an update goes wrong, undo it:

kubectl rollout undo deployment/web

Returns the Deployment to the previous revision.

Try a failure. Run kubectl set image deployment/web nginx=nginx:does-not-exist, then kubectl get pods. New Pods show ErrImagePull or ImagePullBackOff, but the old Pods keep serving because the rolling update waits for new ones to become ready. Run kubectl describe pod on a failing Pod to read the reason, then fix it with kubectl rollout undo deployment/web.

Do not bake settings into images. A ConfigMap holds plain settings and a Secret holds sensitive values; both can be passed to a container as environment variables. Example for the Brew & Bean API:

kubectl create configmap api-config --from-literal=SHOP_NAME="Brew & Bean" --from-literal=CLOSING_HOUR=22
kubectl create secret generic api-secret --from-literal=DB_PASSWORD=change-me

In the Deployment's container spec you would then add envFrom entries with configMapRef and secretRef naming api-config and api-secret.

kubectl delete -f web.yaml
kind delete cluster --name demo

Removes the app and then the whole local cluster.

Next topics: Ingress, persistent volumes for databases, Helm (a package manager for manifests), horizontal pod autoscaling, and a managed cluster on EKS, AKS or GKE. Managed clusters cost money even when idle (the nodes and sometimes a control plane fee), so see *Cloud costs, free tiers and avoiding surprise bills* first.

How this comes up in interviews: What is the difference between a Pod, a Deployment and a Service? What happens when a Pod crashes? How does a rolling update work? What is the difference between a liveness and a readiness probe? (liveness: restart me if I am stuck; readiness: do not send me traffic yet.) How do you debug a Pod stuck in CrashLoopBackOff? (kubectl logs --previous, then describe.)

You are a Kubernetes engineer helping a beginner.

My Pod shows the status [status, e.g. CrashLoopBackOff]. Here is the output of `kubectl describe pod [pod-name]` and `kubectl logs [pod-name] --previous`:

<describe>
[paste here]
</describe>

<logs>
[paste here]
</logs>

Explain in plain English what is wrong, list the three most likely causes in order, and give the exact kubectl commands to confirm each one.

What to expect: A good answer reads the Events section and the last log lines, gives commands you can run, and does not tell you to delete the cluster.