Kubernetes basics

Reading a Deployment and its Service

Manifests are YAML, like Compose files. Here are the two that run the shop's API:

import yaml

manifest = """
apiVersion: apps/v1
kind: Deployment
metadata:
  name: shop-api
spec:
  replicas: 3
  selector:
    matchLabels: {app: shop-api}
  template:
    metadata:
      labels: {app: shop-api, tier: backend}
    spec:
      containers:
        - name: api
          image: shop-api:1.4
          ports: [{containerPort: 8000}]
          readinessProbe:
            httpGet: {path: /healthz, port: 8000}
          resources:
            requests: {cpu: 250m, memory: 256Mi}
            limits: {memory: 512Mi}
---
apiVersion: v1
kind: Service
metadata:
  name: shop-api
spec:
  selector: {app: shop-api}
  ports: [{port: 80, targetPort: 8000}]
"""

deployment, service = yaml.safe_load_all(manifest)
pod = deployment["spec"]["template"]
container = pod["spec"]["containers"][0]
print(deployment["kind"], deployment["spec"]["replicas"], "replicas of", container["image"])
print("pods are labeled", pod["metadata"]["labels"])
print("the Service sends port", service["spec"]["ports"][0]["port"], "to pods matching", service["spec"]["selector"])

The connections are all labels: small key-value tags. The Deployment's template stamps every pod it makes with app: shop-api, its selector says "the pods I manage are the ones labeled app: shop-api", and the Service's selector picks the same pods to send traffic to. Nothing refers to a pod by name, because pods come and go. Three more fields matter in every review:

• The readiness probe is a check Kubernetes calls on each pod; until it passes, the Service sends that pod no traffic. (A liveness probe, separately, restarts a container that has hung.)
• Requests reserve CPU and memory for scheduling a pod onto a node (250m is a quarter of a CPU), and the memory limit is where the container gets killed and restarted if it uses more.
• The --- line separates two documents in one file, which is why the code uses safe_load_all.

Settings come from ConfigMaps and Secrets rather than being baked into the image, so one image runs in every environment. A container's env can say valueFrom: {secretKeyRef: {name: shop, key: db-password}}, and the cluster fills in the value when the pod starts. That keeps passwords out of the manifest, which lives in git, and lets an operator rotate a password without rebuilding anything (pods read environment variables when they start, so they need a restart to see the new value).

def reconcile(desired, running):
    start = max(0, desired - len(running))
    stop = running[desired:] if len(running) > desired else []
    return start, stop

running = ["api-a", "api-b", "api-c"]
running.remove("api-b")            # a node fails and takes this pod with it
print(reconcile(3, running))

def matches(selector, labels):
    return selector == labels


def picked(selector, pods):
    return []


pods = {
    "api-1": {"app": "shop-api", "tier": "backend", "version": "1.4"},
    "api-2": {"app": "shop-api", "tier": "backend", "version": "1.5"},
    "web-1": {"app": "shop-web", "tier": "frontend"},
}
print(picked({"app": "shop-api"}, pods))

Rolling updates without downtime

Change the image to shop-api:1.5 and the Deployment replaces its pods gradually, a rolling update, governed by two numbers:

• maxSurge: how many pods above the replica count may exist during the update (extra capacity, briefly).
• maxUnavailable: how many pods below the replica count may be missing or not ready.

With 3 replicas, a surge of 1 and no unavailability allowed, the cluster starts one new pod (4 running), waits for its readiness probe, stops one old pod (back to 3), and repeats. Traffic never drops below 3 ready pods. A bigger surge is faster but needs spare room in the cluster; allowing unavailability is faster still but runs with less capacity for a while. Both at zero is impossible: there'd be no way to start a new pod or stop an old one.

If the new version's readiness probe never passes, the rollout stalls with the old pods still serving, which is the safety net that makes probes so important, and kubectl rollout undo goes back to the previous version.

Mistakes a manifest review catches

Many Kubernetes incidents trace back to a few lines that a careful review, or a checker, would have caught:

• An image with no tag, or the tag latest: two pods can end up running different code, and you can't roll back to "the previous latest".
• No readiness probe: new pods get traffic before they can answer, so every rollout causes a burst of errors.
• No memory limit: one leaking pod can starve everything else on its node.
• One replica: a crash, a failed machine or a node drained for maintenance takes the service down until the pod is replaced.
• A password written as a plain value in the manifest, which lives in git, instead of a reference to a Secret.

Day to day you talk to a cluster with kubectl. kubectl apply -f api.yaml sends the desired state; kubectl get pods lists what's running and whether each pod is ready; kubectl rollout status deployment/shop-api watches an update; kubectl describe pod <name> explains why a pod won't start (a failing probe, an image that can't be pulled, no node with enough memory); and kubectl logs <name> shows what the app printed. When a rollout goes wrong, kubectl rollout undo deployment/shop-api returns to the previous version while you investigate. apply and rollout undo change the desired state and get, describe and logs only read; none of them starts a pod itself. The controllers do that.