Lesson 09 — Kubernetes Fundamentals

From a single VM to a cluster: pods, deployments, services, configmaps, secrets — on your laptop.

The Module-4 shift

“You’re not learning K8s to use K8s. You’re learning K8s because production wants more than one box.”

Why Kubernetes

• Declarative state: you describe it, the cluster reconciles it.
• Built-in service discovery: every Service gets a stable DNS name in-cluster.
• Rolling updates without scripts: change an image tag; K8s handles the rest.
• Restart-on-failure for free: liveness probes and restart policies handle crashes.
• Resource isolation per pod: CPU/memory limits prevent noisy neighbours.
• Horizontal scale via one number: edit replicas: N and apply.
• A primitive your team already deploys against: the whole industry converged on it.

The four objects you actually use day one

Pod manifest

apiVersion: v1
kind: Pod
metadata:
  name: api
  labels: {app: shortener-api}
spec:
  containers:
  - name: api
    image: ghcr.io/you/shortener-api:0.4.0
    ports: [{containerPort: 8080}]

In practice you almost never write Pods directly — Deployments do it for you.

Deployment manifest

apiVersion: apps/v1
kind: Deployment
metadata: {name: shortener-api}
spec:
  replicas: 2
  selector: {matchLabels: {app: shortener-api}}
  template:
    metadata: {labels: {app: shortener-api}}
    spec:
      containers:
      - name: api
        image: ghcr.io/you/shortener-api:0.4.0
        ports: [{containerPort: 8080}]

selector.matchLabels must match template.metadata.labels — silent breakage if it doesn’t.

Service manifest

apiVersion: v1
kind: Service
metadata: {name: shortener-api}
spec:
  selector: {app: shortener-api}
  ports: [{port: 80, targetPort: 8080}]

In-cluster DNS resolves shortener-api to this Service’s virtual IP — the worker pod calls http://shortener-api/.

ConfigMap + Secret

apiVersion: v1
kind: ConfigMap
metadata: {name: shortener-config}
data:
  LOG_LEVEL: info
  WORKER_INTERVAL_S: "30"
---
apiVersion: v1
kind: Secret
metadata: {name: shortener-db}
type: Opaque
stringData:
  DATABASE_URL: postgres://shortener:s3cr3t@postgres:5432/shortener

stringData lets you write plaintext (the cluster encodes it). For real secrets use external-secrets or sealed-secrets — covered later.

Probes — liveness vs readiness

livenessProbe:
  httpGet: {path: /healthz, port: 8080}
  initialDelaySeconds: 10
  periodSeconds: 10
readinessProbe:
  httpGet: {path: /ready, port: 8080}
  periodSeconds: 5

kind — Kubernetes on your laptop

brew install kind kubectl
kind create cluster --name shortener
kubectl cluster-info --context kind-shortener

kind runs the control plane + nodes inside Docker containers; no cloud account required.

Apply, watch, debug

kubectl apply -f k8s/
kubectl get pods -w
kubectl logs deploy/shortener-api
kubectl describe pod <name>
kubectl port-forward svc/shortener-api 8080:80

apply is idempotent, describe is your first-stop for failures, logs and port-forward cover 80% of day-one debugging.

What we’ll build today

• Create sample-app/k8s/ with a Namespace + Deployment + Service for the API.
• A Deployment for the worker.
• A ConfigMap for app config; a Secret for the DB URL.
• A Postgres StatefulSet (one-replica, ephemeral PVC) for the in-cluster DB.
• Readiness + liveness probes on both the API and worker.
• Deploy the lot to a kind cluster and curl the API through kubectl port-forward.

Common gotchas

• Image not found → forgot to kind load docker-image (kind doesn’t pull local images by default unless you push to a registry).
• Pod stuck in CrashLoopBackOff → kubectl logs and kubectl describe first.
• Probes failing → kubectl exec into the pod and curl the probe endpoint directly.
• Service has no endpoints → label selector mismatch. Check kubectl describe svc <name> for the Endpoints: line.

Recap & what’s next

• Four objects cover 80% of day-one work: Deployment, Service, ConfigMap, Secret.
• kind lets you exercise the full K8s surface on a laptop.
• Probes are non-optional: liveness for crash detection, readiness for traffic gating.