Skip to content

qtsone/learning / skills/tutor

tutor

Flagged

Turn this agent into a personal programming tutor with a versioned 0-to-expert curriculum (Go available; more languages coming). Use when the user wants to learn a programming language, start or resume lessons, get their exercise code graded, check learning progress, or contribute curriculum fixes — e.g. "/tutor go", "/tutor resume", "teach me Go", "continue my lessons", "grade my exercise".

FileKindSize
SKILL.mdskill md9.2 KB
curriculum/content/focus/cli-tooling/capstone/LESSON.mdmarkdown17.1 KB
curriculum/content/focus/cli-tooling/capstone/TUTOR.mdmarkdown5.4 KB
curriculum/content/focus/cli-tooling/capstone/exercise/app.goscript5.8 KB
curriculum/content/focus/cli-tooling/capstone/exercise/authors.goscript1.6 KB
curriculum/content/focus/cli-tooling/capstone/exercise/authors_test.goscript7.3 KB
curriculum/content/focus/cli-tooling/capstone/exercise/cli_test.goscript11.5 KB
curriculum/content/focus/cli-tooling/capstone/exercise/config_test.goscript11.5 KB
curriculum/content/focus/cli-tooling/capstone/exercise/go.modmanifest187 B
curriculum/content/focus/cli-tooling/capstone/exercise/go.summanifest900 B
curriculum/content/focus/cli-tooling/capstone/exercise/main.goscript2.0 KB
curriculum/content/focus/cli-tooling/capstone/exercise/render.goscript1.9 KB
curriculum/content/focus/cli-tooling/capstone/exercise/root.goscript2.4 KB
curriculum/content/focus/cli-tooling/capstone/exercise/scan.goscript2.5 KB
curriculum/content/focus/cli-tooling/capstone/exercise/scan_test.goscript4.0 KB
curriculum/content/focus/cli-tooling/capstone/exercise/signal_unix_test.goscript1.4 KB
curriculum/content/focus/cli-tooling/capstone/exercise/version.goscript942 B
curriculum/content/focus/cli-tooling/capstone/quiz.jsonconfig5.0 KB
curriculum/content/focus/cli-tooling/capstone/solution/app.goscript9.9 KB
curriculum/content/focus/cli-tooling/capstone/solution/authors.goscript2.9 KB
curriculum/content/focus/cli-tooling/capstone/solution/render.goscript2.6 KB
curriculum/content/focus/cli-tooling/capstone/solution/root.goscript4.7 KB
curriculum/content/focus/cli-tooling/capstone/solution/scan.goscript3.7 KB
curriculum/content/focus/cli-tooling/cobra/LESSON.mdmarkdown12.8 KB
curriculum/content/focus/cli-tooling/cobra/TUTOR.mdmarkdown5.9 KB
curriculum/content/focus/cli-tooling/cobra/exercise/app.goscript1.7 KB
curriculum/content/focus/cli-tooling/cobra/exercise/go.modmanifest193 B
curriculum/content/focus/cli-tooling/cobra/exercise/go.summanifest900 B
curriculum/content/focus/cli-tooling/cobra/exercise/main.goscript422 B
curriculum/content/focus/cli-tooling/cobra/exercise/notes_test.goscript9.8 KB
curriculum/content/focus/cli-tooling/cobra/exercise/root.goscript919 B
curriculum/content/focus/cli-tooling/cobra/exercise/store.goscript1.7 KB
curriculum/content/focus/cli-tooling/cobra/quiz.jsonconfig5.1 KB
curriculum/content/focus/cli-tooling/cobra/solution/app.goscript2.4 KB
curriculum/content/focus/cli-tooling/cobra/solution/root.goscript4.2 KB
curriculum/content/focus/cli-tooling/distribution/LESSON.mdmarkdown17.2 KB
curriculum/content/focus/cli-tooling/distribution/TUTOR.mdmarkdown7.0 KB
curriculum/content/focus/cli-tooling/distribution/exercise/check.shexecutablescript12.0 KB
curriculum/content/focus/cli-tooling/distribution/exercise/go.modmanifest35 B
curriculum/content/focus/cli-tooling/distribution/exercise/internal/buildinfo/buildinfo.goscript1.4 KB
curriculum/content/focus/cli-tooling/distribution/exercise/main.goscript1.2 KB
curriculum/content/focus/cli-tooling/distribution/quiz.jsonconfig5.0 KB
curriculum/content/focus/cli-tooling/distribution/solution/.goreleaser.yamlconfig2.1 KB
curriculum/content/focus/cli-tooling/distribution/solution/internal/buildinfo/buildinfo.goscript1.3 KB
curriculum/content/focus/cli-tooling/files-processes/LESSON.mdmarkdown18.8 KB
curriculum/content/focus/cli-tooling/files-processes/TUTOR.mdmarkdown7.8 KB
curriculum/content/focus/cli-tooling/files-processes/exercise/atomicfile.goscript772 B
curriculum/content/focus/cli-tooling/files-processes/exercise/atomicfile_test.goscript2.6 KB
curriculum/content/focus/cli-tooling/files-processes/exercise/exec.goscript3.8 KB
curriculum/content/focus/cli-tooling/files-processes/exercise/exec_test.goscript10.7 KB
curriculum/content/focus/cli-tooling/files-processes/exercise/go.modmanifest44 B
curriculum/content/focus/cli-tooling/files-processes/exercise/main.goscript1.9 KB
curriculum/content/focus/cli-tooling/files-processes/exercise/paths.goscript1.6 KB
curriculum/content/focus/cli-tooling/files-processes/exercise/paths_test.goscript3.1 KB
curriculum/content/focus/cli-tooling/files-processes/exercise/signal.goscript1.6 KB
curriculum/content/focus/cli-tooling/files-processes/exercise/signal_test.goscript1.6 KB
curriculum/content/focus/cli-tooling/files-processes/exercise/signal_unix_test.goscript2.4 KB
curriculum/content/focus/cli-tooling/files-processes/quiz.jsonconfig7.9 KB
curriculum/content/focus/cli-tooling/files-processes/solution/atomicfile.goscript2.1 KB
curriculum/content/focus/cli-tooling/files-processes/solution/exec.goscript5.4 KB
curriculum/content/focus/cli-tooling/files-processes/solution/paths.goscript2.2 KB
curriculum/content/focus/cli-tooling/files-processes/solution/signal.goscript2.1 KB
curriculum/content/focus/cli-tooling/flags-config/LESSON.mdmarkdown12.3 KB
curriculum/content/focus/cli-tooling/flags-config/TUTOR.mdmarkdown6.7 KB
curriculum/content/focus/cli-tooling/flags-config/exercise/config.goscript2.4 KB
curriculum/content/focus/cli-tooling/flags-config/exercise/config_test.goscript3.1 KB
curriculum/content/focus/cli-tooling/flags-config/exercise/flagvalue.goscript769 B
curriculum/content/focus/cli-tooling/flags-config/exercise/flagvalue_test.goscript1.9 KB
curriculum/content/focus/cli-tooling/flags-config/exercise/go.modmanifest41 B
curriculum/content/focus/cli-tooling/flags-config/exercise/loader.goscript5.5 KB
curriculum/content/focus/cli-tooling/flags-config/exercise/loader_test.goscript12.4 KB
curriculum/content/focus/cli-tooling/flags-config/exercise/main.goscript1.2 KB
curriculum/content/focus/cli-tooling/flags-config/quiz.jsonconfig5.3 KB
curriculum/content/focus/cli-tooling/flags-config/solution/config.goscript3.2 KB
curriculum/content/focus/cli-tooling/flags-config/solution/flagvalue.goscript957 B
curriculum/content/focus/cli-tooling/flags-config/solution/loader.goscript9.0 KB
curriculum/content/focus/cli-tooling/terminal-ux/LESSON.mdmarkdown14.8 KB
curriculum/content/focus/cli-tooling/terminal-ux/TUTOR.mdmarkdown6.2 KB
curriculum/content/focus/cli-tooling/terminal-ux/exercise/color.goscript1.6 KB
curriculum/content/focus/cli-tooling/terminal-ux/exercise/color_test.goscript2.3 KB
curriculum/content/focus/cli-tooling/terminal-ux/exercise/go.modmanifest40 B
curriculum/content/focus/cli-tooling/terminal-ux/exercise/main.goscript3.6 KB
curriculum/content/focus/cli-tooling/terminal-ux/exercise/progress.goscript1.9 KB
curriculum/content/focus/cli-tooling/terminal-ux/exercise/progress_test.goscript1.9 KB
curriculum/content/focus/cli-tooling/terminal-ux/exercise/prompt.goscript2.3 KB
curriculum/content/focus/cli-tooling/terminal-ux/exercise/prompt_test.goscript4.7 KB
curriculum/content/focus/cli-tooling/terminal-ux/exercise/render.goscript3.8 KB
curriculum/content/focus/cli-tooling/terminal-ux/exercise/render_test.goscript6.1 KB
curriculum/content/focus/cli-tooling/terminal-ux/quiz.jsonconfig5.9 KB
curriculum/content/focus/cli-tooling/terminal-ux/solution/color.goscript1.8 KB
curriculum/content/focus/cli-tooling/terminal-ux/solution/progress.goscript2.0 KB
curriculum/content/focus/cli-tooling/terminal-ux/solution/prompt.goscript2.2 KB
curriculum/content/focus/cli-tooling/terminal-ux/solution/render.goscript4.3 KB
curriculum/content/focus/containers/capstone/LESSON.mdmarkdown20.0 KB
curriculum/content/focus/containers/capstone/TUTOR.mdmarkdown6.7 KB
curriculum/content/focus/containers/capstone/exercise/.dockerignoreother190 B
curriculum/content/focus/containers/capstone/exercise/.github/workflows/release.ymlconfig2.4 KB
curriculum/content/focus/containers/capstone/exercise/Dockerfileother903 B
curriculum/content/focus/containers/capstone/exercise/RUNBOOK.mdmarkdown1.6 KB
curriculum/content/focus/containers/capstone/exercise/check.shscript62.6 KB
curriculum/content/focus/containers/capstone/exercise/deploy/base/deployment.yamlconfig2.8 KB
curriculum/content/focus/containers/capstone/exercise/deploy/base/kustomization.yamlconfig845 B
curriculum/content/focus/containers/capstone/exercise/deploy/base/service.yamlconfig316 B
curriculum/content/focus/containers/capstone/exercise/deploy/overlays/dev/kustomization.yamlconfig1.3 KB
curriculum/content/focus/containers/capstone/exercise/deploy/overlays/dev/resources-patch.yamlconfig906 B
curriculum/content/focus/containers/capstone/exercise/deploy/overlays/prod/kustomization.yamlconfig899 B
curriculum/content/focus/containers/capstone/exercise/deploy/overlays/prod/resources-patch.yamlconfig341 B
curriculum/content/focus/containers/capstone/exercise/go.modmanifest48 B
curriculum/content/focus/containers/capstone/exercise/main.goscript6.4 KB
curriculum/content/focus/containers/capstone/quiz.jsonconfig6.5 KB
curriculum/content/focus/containers/capstone/solution/.github/workflows/release.ymlconfig6.4 KB
curriculum/content/focus/containers/capstone/solution/Dockerfileother1.2 KB
curriculum/content/focus/containers/capstone/solution/RUNBOOK.mdmarkdown7.7 KB
curriculum/content/focus/containers/capstone/solution/deploy/overlays/prod/kustomization.yamlconfig1.4 KB
curriculum/content/focus/containers/capstone/solution/deploy/overlays/prod/resources-patch.yamlconfig1.1 KB
curriculum/content/focus/containers/compose/LESSON.mdmarkdown13.5 KB
curriculum/content/focus/containers/compose/TUTOR.mdmarkdown5.2 KB
curriculum/content/focus/containers/compose/exercise/.env.exampleother348 B
curriculum/content/focus/containers/compose/exercise/app/Dockerfileother962 B
curriculum/content/focus/containers/compose/exercise/app/go.modmanifest40 B
curriculum/content/focus/containers/compose/exercise/app/main.goscript2.2 KB
curriculum/content/focus/containers/compose/exercise/check.shscript24.5 KB
curriculum/content/focus/containers/compose/exercise/compose.yamlconfig877 B
curriculum/content/focus/containers/compose/quiz.jsonconfig4.5 KB
curriculum/content/focus/containers/compose/solution/.envconfig203 B
curriculum/content/focus/containers/compose/solution/compose.yamlconfig1.6 KB
curriculum/content/focus/containers/deploying-go/LESSON.mdmarkdown21.1 KB
curriculum/content/focus/containers/deploying-go/TUTOR.mdmarkdown6.5 KB
curriculum/content/focus/containers/deploying-go/exercise/.dockerignoreother150 B
curriculum/content/focus/containers/deploying-go/exercise/Dockerfileother851 B
curriculum/content/focus/containers/deploying-go/exercise/SHUTDOWN.mdmarkdown1.4 KB
curriculum/content/focus/containers/deploying-go/exercise/check.shscript43.5 KB
curriculum/content/focus/containers/deploying-go/exercise/configmap.yamlconfig526 B
curriculum/content/focus/containers/deploying-go/exercise/deployment.yamlconfig2.5 KB
curriculum/content/focus/containers/deploying-go/exercise/go.modmanifest41 B
curriculum/content/focus/containers/deploying-go/exercise/main.goscript6.1 KB
curriculum/content/focus/containers/deploying-go/exercise/service.yamlconfig347 B
curriculum/content/focus/containers/deploying-go/exercise/shutdown_test.goscript3.3 KB
curriculum/content/focus/containers/deploying-go/quiz.jsonconfig6.5 KB
curriculum/content/focus/containers/deploying-go/solution/SHUTDOWN.mdmarkdown5.4 KB
curriculum/content/focus/containers/deploying-go/solution/configmap.yamlconfig541 B
curriculum/content/focus/containers/deploying-go/solution/deployment.yamlconfig4.0 KB
curriculum/content/focus/containers/deploying-go/solution/main.goscript6.1 KB
curriculum/content/focus/containers/docker-fundamentals/LESSON.mdmarkdown14.4 KB
curriculum/content/focus/containers/docker-fundamentals/TUTOR.mdmarkdown5.4 KB
curriculum/content/focus/containers/docker-fundamentals/exercise/Dockerfileother261 B
curriculum/content/focus/containers/docker-fundamentals/exercise/NOTES.mdmarkdown1.4 KB
curriculum/content/focus/containers/docker-fundamentals/exercise/check.shscript10.7 KB
curriculum/content/focus/containers/docker-fundamentals/exercise/go.modmanifest38 B
curriculum/content/focus/containers/docker-fundamentals/exercise/local.envconfig218 B
curriculum/content/focus/containers/docker-fundamentals/exercise/main.goscript780 B
curriculum/content/focus/containers/docker-fundamentals/exercise/scratch/notes.mdmarkdown153 B
curriculum/content/focus/containers/docker-fundamentals/quiz.jsonconfig5.5 KB
curriculum/content/focus/containers/docker-fundamentals/solution/.dockerignoreother230 B
curriculum/content/focus/containers/docker-fundamentals/solution/Dockerfileother504 B
curriculum/content/focus/containers/docker-fundamentals/solution/NOTES.mdmarkdown3.8 KB
curriculum/content/focus/containers/dockerizing-go/LESSON.mdmarkdown14.0 KB
curriculum/content/focus/containers/dockerizing-go/TUTOR.mdmarkdown5.4 KB
curriculum/content/focus/containers/dockerizing-go/exercise/.dockerignoreother143 B
curriculum/content/focus/containers/dockerizing-go/exercise/Dockerfile.naiveother512 B
curriculum/content/focus/containers/dockerizing-go/exercise/NOTES.mdmarkdown1.1 KB
curriculum/content/focus/containers/dockerizing-go/exercise/check.shscript14.2 KB
curriculum/content/focus/containers/dockerizing-go/exercise/go.modmanifest43 B
curriculum/content/focus/containers/dockerizing-go/exercise/go.summanifest0 B
curriculum/content/focus/containers/dockerizing-go/exercise/main.goscript1.7 KB
curriculum/content/focus/containers/dockerizing-go/quiz.jsonconfig4.5 KB
curriculum/content/focus/containers/dockerizing-go/solution/Dockerfileother755 B
curriculum/content/focus/containers/dockerizing-go/solution/NOTES.mdmarkdown2.7 KB
curriculum/content/focus/containers/helm-kustomize/LESSON.mdmarkdown19.1 KB
curriculum/content/focus/containers/helm-kustomize/TUTOR.mdmarkdown9.5 KB
curriculum/content/focus/containers/helm-kustomize/exercise/NOTES.mdmarkdown1.5 KB
curriculum/content/focus/containers/helm-kustomize/exercise/chart/Chart.yamlconfig518 B
curriculum/content/focus/containers/helm-kustomize/exercise/chart/templates/_helpers.tplother1.8 KB
curriculum/content/focus/containers/helm-kustomize/exercise/chart/templates/configmap.yamlconfig392 B
curriculum/content/focus/containers/helm-kustomize/exercise/chart/templates/deployment.yamlconfig3.2 KB
curriculum/content/focus/containers/helm-kustomize/exercise/chart/templates/service.yamlconfig512 B
curriculum/content/focus/containers/helm-kustomize/exercise/chart/values.yamlconfig1.4 KB
curriculum/content/focus/containers/helm-kustomize/exercise/check.shscript55.4 KB
curriculum/content/focus/containers/helm-kustomize/exercise/kustomize/base/deployment.yamlconfig2.1 KB
curriculum/content/focus/containers/helm-kustomize/exercise/kustomize/base/kustomization.yamlconfig798 B
curriculum/content/focus/containers/helm-kustomize/exercise/kustomize/base/service.yamlconfig347 B
curriculum/content/focus/containers/helm-kustomize/exercise/kustomize/overlays/dev/kustomization.yamlconfig616 B
curriculum/content/focus/containers/helm-kustomize/exercise/kustomize/overlays/dev/resources-patch.yamlconfig506 B
curriculum/content/focus/containers/helm-kustomize/exercise/kustomize/overlays/prod/kustomization.yamlconfig477 B
curriculum/content/focus/containers/helm-kustomize/exercise/kustomize/overlays/prod/resources-patch.yamlconfig614 B
curriculum/content/focus/containers/helm-kustomize/quiz.jsonconfig7.4 KB
curriculum/content/focus/containers/helm-kustomize/solution/NOTES.mdmarkdown3.3 KB
curriculum/content/focus/containers/helm-kustomize/solution/chart/Chart.yamlconfig366 B
curriculum/content/focus/containers/helm-kustomize/solution/chart/templates/configmap.yamlconfig547 B
curriculum/content/focus/containers/helm-kustomize/solution/chart/templates/deployment.yamlconfig2.5 KB
curriculum/content/focus/containers/helm-kustomize/solution/chart/values.yamlconfig1.2 KB
curriculum/content/focus/containers/helm-kustomize/solution/kustomize/base/kustomization.yamlconfig915 B
curriculum/content/focus/containers/helm-kustomize/solution/kustomize/overlays/dev/kustomization.yamlconfig820 B
curriculum/content/focus/containers/helm-kustomize/solution/kustomize/overlays/dev/resources-patch.yamlconfig515 B
curriculum/content/focus/containers/helm-kustomize/solution/kustomize/overlays/prod/kustomization.yamlconfig267 B
curriculum/content/focus/containers/helm-kustomize/solution/kustomize/overlays/prod/resources-patch.yamlconfig649 B
curriculum/content/focus/containers/kubernetes-config/LESSON.mdmarkdown19.4 KB
curriculum/content/focus/containers/kubernetes-config/TUTOR.mdmarkdown6.3 KB
curriculum/content/focus/containers/kubernetes-config/exercise/NOTES.mdmarkdown1.3 KB
curriculum/content/focus/containers/kubernetes-config/exercise/app/Dockerfileother1.0 KB

curriculum/content/focus/containers/deploying-go/LESSON.md

View on GitHub
# Deploying Go on Kubernetes

> `focus.containers.deploying-go` · ~2.5-3.5h · Stage: Focus: Containers II

## Objectives

By the end of this lesson you can:

- Implement complete manifests — Deployment, Service, ConfigMap, probes,
  resources — for your own Go service.
- Implement graceful shutdown in Go: catch SIGTERM, drain in-flight requests
  with `http.Server.Shutdown`, and finish inside
  `terminationGracePeriodSeconds`.
- Explain the pod termination sequence (endpoint removal, SIGTERM, grace
  period, SIGKILL) and why ignoring SIGTERM drops requests.
- Implement distinct readiness and liveness endpoints in your service and
  justify what each should and should not check.
- Perform a zero-downtime rolling update and verify no requests fail,
  explaining how `maxSurge`/`maxUnavailable` and readiness gates make that
  possible.

You want a local cluster for this, and it costs a build and one command. From
inside `exercise/`:

```sh
docker build -t timesvc:1.1.0 .          # release 1.1.0, the tag the manifests pin
kind create cluster                      # ~1 minute, and kubectl now points at it
kind load docker-image timesvc:1.1.0     # kind keeps its own image store
kubectl create namespace timesvc         # unless it survived the last lesson
```

(`minikube start`, `k3d cluster create` and Docker Desktop's built-in
Kubernetes work just as well.) The exercise is graded by reading the files you
write, so you can finish it with no cluster, no kubectl and no daemon —
`check.sh` says which checks it skipped. But watching a rollout drop requests,
fixing it, and watching it stop is the lesson.

Rebuild and re-load after every change to `main.go`: the tag stays `1.1.0`, so
the cluster runs the old bits until you do, and `kubectl rollout restart
deployment/timesvc -n timesvc` then picks up the new ones.

## Your process is disposable, and that is the deal

The last two lessons described a desired state. This one is about the part of
the contract that runs in *your* code, because there is one thing Kubernetes
cannot do for you: stop your process politely.

And it will stop it — far more often than "when we deploy". A rolling update,
a node drained for a kernel patch, a scale-down, an eviction because a
neighbour is using too much memory, an autoscaler consolidating three
half-empty nodes into two. The twelve-factor name for the property you need is
**disposability**: start fast, stop cleanly, lose nothing on the way out.

The mechanism is a Unix signal. The kubelet sends **SIGTERM** to PID 1 in your
container and starts a clock; when the clock runs out it sends **SIGKILL**,
which no process can catch, block or handle. Go's default disposition for
SIGTERM is to terminate immediately, so a service that installs no handler
dies at the first byte of the request it was serving. (This is also why your
`ENTRYPOINT` is in exec form: with shell form PID 1 would be `/bin/sh`, which
does not forward signals, and your code would never see SIGTERM at all.)

## The termination sequence, exactly

Something deletes the pod — `kubectl delete pod`, a rolling update, a node
drain. What actually happens is not what most people assume:

1. The API server sets `deletionTimestamp` on the pod, which now shows as
   `Terminating`. **The grace-period clock starts now.**
2. Two chains of events start **in parallel**, and nothing synchronises them:

   **(a) The control plane.** The endpoints controller notices the pod is
   terminating, marks it not-ready in the Service's EndpointSlice, and every
   `kube-proxy` in the cluster — plus your ingress controller, plus any
   service mesh — has to observe that change and rewrite its forwarding rules.
   That propagation is eventually consistent and takes anywhere from
   milliseconds to seconds depending on cluster size.

   **(b) The kubelet on that node.** It runs the container's `preStop` hook if
   there is one, waits for it to finish, and *then* sends SIGTERM to PID 1.

3. Your process handles SIGTERM: stops advertising readiness, stops accepting
   new connections, finishes the requests it already accepted, exits.
4. If the container is still running when `terminationGracePeriodSeconds`
   expires — counted from step 1, including the preStop hook — the kubelet
   sends SIGKILL. Whatever was in flight is gone.
5. The pod object is removed from the API.

Read step 2 again. Nobody tells the kubelet "the dataplane has finished
forgetting this pod, you may now send SIGTERM". The two chains simply run.

## Why a perfectly healthy pod still drops requests

Now the failure mode writes itself. Chain (b) is fast — the kubelet is local,
SIGTERM arrives in milliseconds. Chain (a) is slower and unbounded. So your
server closes its listener while a `kube-proxy` somewhere is still forwarding
brand-new connections to your pod's address, and those callers get
`connection refused` or a reset: failures on requests that were never served,
arriving in a burst exactly when you deploy, indistinguishable from a real
outage to whoever is calling you.

The fix is to make the fast chain wait for the slow one, and it has two parts.

**Fail readiness first.** The moment shutdown begins, `/readyz` answers 503.
Anything that polls readiness — an ingress controller, a cloud load balancer
with its own health checks, a mesh sidecar — takes you out of rotation on its
own schedule.

**Then delay SIGTERM with a preStop hook.** Readiness alone does not cover the
deletion path, because the kubelet does not wait for readiness to be observed
either. So you buy time bluntly:

```yaml
lifecycle:
  preStop:
    sleep:
      seconds: 10
```

The *hook* sleeps; your process keeps serving normally while the endpoint
removal propagates, and only afterwards does SIGTERM arrive. That is the whole
trick, and it is why almost every production Deployment you will read has an
apparently pointless sleep in it.

That `sleep:` handler is native to Kubernetes (added in 1.29, on by default
since 1.30) and needs nothing inside the image. The older spelling,
`exec: command: ["/bin/sh", "-c", "sleep 10"]`, fails on the distroless image
you built two lessons ago — no shell, no `/bin/sleep`. On an older cluster
that is a real constraint on your base image choice.

**The ordering rule, in one sentence:** the pod must stop being a routing
target *before* it stops accepting connections. Everything above is machinery
for that one sentence.

## Draining in Go

The Go side is small, and every line is load-bearing:

```go
ctx, stop := signal.NotifyContext(context.Background(), syscall.SIGINT, syscall.SIGTERM)
defer stop()

// ... serve in a goroutine ...

<-ctx.Done()          // SIGTERM arrived

a.ready.Store(false)  // 1. stop advertising: /readyz now answers 503
stopCtx, cancel := context.WithTimeout(context.Background(), shutdownTimeout)
defer cancel()
err := srv.Shutdown(stopCtx)   // 2. stop accepting, finish what is in flight
```

- `signal.NotifyContext` turns a signal into a cancelled context — the
  vocabulary the rest of your program already speaks. It also restores the
  default behaviour on the *second* signal, so an impatient operator pressing
  Ctrl-C twice still gets out.
- **`Shutdown` is not `Close`.** `Close` slams every connection shut, requests
  being served right now included. `Shutdown` closes the listeners and idle
  keep-alive connections, then waits for active requests. The difference is a
  burst of failed requests at every deploy.
- The shutdown context needs a deadline, bounded *below* the grace period:
  without one a single stuck handler holds the drain open until SIGKILL and
  takes everything nearly finished down with it.
- `srv.Serve` returns `http.ErrServerClosed` as soon as shutdown begins — what
  success looks like. Treat it as an error and your pod exits non-zero and is
  counted as a crash.
- `Shutdown` does not wait for **hijacked** connections (WebSockets, raw
  streams); close those yourself, e.g. from `srv.RegisterOnShutdown`.
  Background goroutines hang off the same context, and `main` waits for them.

## Budgeting the grace period

Three numbers have to fit together, and this is the arithmetic to write down
in a comment for whoever inherits the file:

```
preStop sleep  +  the server's shutdown timeout  +  margin  <=  terminationGracePeriodSeconds
      10s      +               20s               +   15s    <=              45s
```

The mistake people make is thinking the preStop hook runs *before* the grace
period. It does not — the clock starts at deletion, so the hook spends the
same budget the drain needs. Get this wrong and your service does everything
right and still gets SIGKILLed mid-drain, with no log line explaining why,
which reads like a crash rather than a deploy.

`terminationGracePeriodSeconds` defaults to 30. Set it explicitly anyway: 30
is a fine number and a terrible decision, because nobody reading the file can
tell whether anyone checked it against the drain.

## Liveness during a drain

You wired all three probes in the previous lesson. Deployment adds two things
they must *not* do.

**Liveness must keep passing for the whole drain.** Point it at the same
endpoint as readiness and the shutdown sequence turns comic: readiness flips
to 503, the liveness probe reads that same 503, the kubelet concludes the
container is dead and restarts it in the middle of finishing real requests.
That is why your service has two endpoints that look identical and mean
different things — `/healthz` is 200 for as long as the process can serve at
all, `/readyz` reports whether it wants new work.

**Liveness must not check dependencies.** A liveness probe that pings the
database turns a five-minute database blip into a cluster-wide restart storm:
every pod fails liveness at once, every pod restarts, all of them come back
with cold pools and empty caches and hammer the database that was already
struggling. A restart cannot fix somebody else's outage. Dependency checks
belong in readiness, where the consequence is "send me no traffic for now".

## GOMAXPROCS and the CPU limit

Now the two Go-specific traps, both the same shape: the runtime tunes itself
from what it can see, and inside a container what it can see is wrong.

`GOMAXPROCS` sets how many goroutines can execute simultaneously — the number
of Ps in the scheduler from the S5 runtime lesson. Through Go 1.24, the
runtime picks it from the CPU affinity mask: the *node's* cores. Your
container's `limits.cpu: 1` is a cgroup bandwidth quota — 100ms of CPU per
100ms period — and it is invisible to that calculation. On a 64-core node that
means 64 Ps sharing one core's worth of quota:

- The scheduler runs 64 goroutines at once, blows the quota partway through
  the period, and the kernel **throttles the whole process** until the next
  period. Your p99 grows a shelf exactly one period wide.
- The GC dedicates about 25% of `GOMAXPROCS` to mark workers — 16 of them —
  competing for that same single core's budget.
- Every P carries per-P caches, so you pay memory for parallelism you cannot
  use.

Nothing crashes. It is slow in a way that profiling *inside* the process
struggles to explain, because the process cannot see the throttling.

Go 1.25 fixed the default on Linux: the runtime reads the cgroup CPU limit and
takes the minimum of the affinity mask and that limit rounded up (floor of 2),
re-checking periodically in case it changes. But it is gated on the `go`
directive in `go.mod` being 1.25 or later — the standard GODEBUG compatibility
mechanism — so a module still declaring `go 1.22`, like the exercise, gets the
old behaviour even on a brand-new toolchain. Three honest options:

1. **Set it in the manifest**, next to the limit it has to agree with:

   ```yaml
   env:
     - name: GOMAXPROCS
       valueFrom:
         resourceFieldRef:
           resource: limits.cpu     # rounds up: 1500m becomes 2
   ```

   The downward API keeps the two from drifting apart when someone raises the
   limit six months from now.
2. **Import `go.uber.org/automaxprocs`** — a blank import that reads the
   cgroup at startup, the library everyone used before 1.25 — or move the
   module to `go 1.25`+ and let the runtime do it.

The exercise asks for option 1: it works on every Go version, and it is the
one visible to whoever reads the manifest.

## GOMEMLIMIT and the memory limit

The same story with a nastier ending. The collector's default target is a
*ratio*: with `GOGC=100` the heap may grow to twice the live heap before a
collection. Nothing in that formula knows about `limits.memory`, so a Go
service under load grows past the cgroup limit and the kernel's OOM killer
ends the process — exit code 137, `OOMKilled` in `kubectl describe`, no panic,
no stack trace, no shutdown, in-flight requests simply gone.

`GOMEMLIMIT` gives the runtime the number it was missing. It is a **soft**
limit: as runtime-managed memory approaches it, the GC runs more often and
returns memory to the OS more aggressively, trading CPU for staying alive. The
cgroup limit stays hard and kernel-enforced, so the soft one sits *below* it:

```yaml
resources:
  limits:
    memory: 128Mi
env:
  - name: GOMEMLIMIT
    value: "110MiB"
```

Three details that bite:

- **The suffix.** Kubernetes writes `128Mi`; the Go runtime wants `128MiB`
  (`B`, `KiB`, `MiB`, `GiB`, `TiB`). A value it cannot parse makes the runtime
  refuse to start.
- **The headroom is not optional.** `GOMEMLIMIT` covers the heap and other
  runtime-managed memory, but explicitly *excludes* the mapping of your own
  binary and anything the OS holds on your behalf. 80-90% of the container
  limit is the usual landing zone.
- **`GOGC=off` with `GOMEMLIMIT` is a real strategy and a real risk** — if the
  live heap genuinely exceeds the limit, the GC spins forever chasing a target
  it cannot reach. Leave `GOGC` alone until profiles say otherwise.

## Config and logs are part of the deployment

**Configuration comes from the environment.** Your process reads `PORT`,
`LOG_LEVEL` and `SHUTDOWN_TIMEOUT` at startup and never again. Env vars from
`envFrom` are snapshotted at container creation, so editing the ConfigMap does
not change a running pod — you roll the Deployment, which produces new pods
with the new values *and* a revision you can roll back to. (Mounted config
updates in place instead; env vars are choosing restart-to-change.)

**Logs go to stdout as structured lines.** The container's stdout *is* the
logging interface: the kubelet captures it, `kubectl logs` reads it, the
cluster's collector ships it. Your `slog` JSON handler from the observability
lesson is already right; a log file inside the container is invisible to all
of that and dies with the pod.

## Rolling updates that nobody notices

A rolling update is the termination sequence above, run once per pod, while
new pods start alongside. You already set the strategy in the core lesson:

```yaml
strategy:
  type: RollingUpdate
  rollingUpdate:
    maxSurge: 1          # may run one pod above the replica count
    maxUnavailable: 0    # may never run below it
minReadySeconds: 5       # ready for 5s before it counts as available
```

What is worth adding now is *why* it works. `maxUnavailable: 0` means capacity
is never removed before a replacement is ready — and "ready" is your readiness
probe, so the whole strategy is only as good as that endpoint. Each old pod
then leaves through the drain you just built, which is the other half: a
perfect strategy over a process that ignores SIGTERM still drops requests, one
burst per pod. (`maxSurge: 0` with `maxUnavailable: 0` is the deadlock —
allowed neither to add a pod nor to remove one, the rollout never starts.
`minReadySeconds` covers the pod that passes readiness and falls over two
seconds later.)

The vocabulary you already have does the rest:

```sh
kubectl apply -f . -n timesvc
kubectl rollout status deployment/timesvc -n timesvc   # blocks; non-zero on failure
kubectl rollout undo deployment/timesvc -n timesvc     # back to the previous revision
```

And to *verify* zero downtime rather than believe in it, hold a request loop
against the Service while you roll — from inside the cluster, since it is a
ClusterIP:

```sh
kubectl run probe --rm -it -n timesvc --image=curlimages/curl --restart=Never -- \
  sh -c 'while true; do curl -sS -o /dev/null -w "%{http_code}\n" http://timesvc/now; done'
```

A wall of `200`s is the result you want. A `000` or a `503` is the race in this
lesson, and it is worth deliberately breaking your manifest — remove the
preStop hook, roll again — to watch it appear.

## Exercise

Open [`exercise/`](exercise/). You get `timesvc` back with its lifecycle
removed, and your manifests roughly as they stood at the end of the Kubernetes
Configuration lesson — trimmed to ConfigMap, Deployment and Service, in the
`timesvc` namespace. They schedule, they serve, they pass their probes, and
they drop requests every time a pod moves.

- `main.go` — four `TODO`s: readiness, liveness, the drain, and hearing
  SIGTERM at all. `shutdown_test.go` is their specification; read it.
- `configmap.yaml`, `deployment.yaml`, `service.yaml` — a `TODO` at every place
  this lesson touches.
- `SHUTDOWN.md` — four questions to answer in your own words.
- `Dockerfile` — the 1.1.0 build, as you wrote it two lessons ago; ungraded
  here, and the reason the tag the manifests pin is one command away.
- `check.sh` — the referee.

Acceptance criteria (1-3 and 8-15 are the work; 4-7 are already true and must
stay true):

1. The service turns SIGTERM (and SIGINT) into a cancelled context.
2. Shutdown withdraws readiness **first** — the flip appears before the
   `Shutdown` call in your source — then calls `srv.Shutdown` with a context
   bounded by `SHUTDOWN_TIMEOUT`, and does not treat `http.ErrServerClosed`
   as a failure.
3. `/readyz` answers 503 while draining; `/healthz` answers 200 for the whole
   drain and reads no readiness state and no dependency. Keep it named
   `healthz` (method or plain function): that name is how the referee finds it.
4. The manifests declare a ConfigMap, a Deployment (`apps/v1`) and a Service
   (`v1`), and the Service's selector matches the pod template's labels.
5. The container image is pinned to a real tag or digest — never `latest`.
6. `replicas` is at least 2, with `strategy.type: RollingUpdate`,
   `maxUnavailable: 0` and `maxSurge` at least 1.
7. The readiness probe hits `/readyz`; the liveness probe hits `/healthz`; a
   startup probe budgets at least 30 seconds
   (`failureThreshold × periodSeconds`). Every probe port resolves to a
   declared `containerPort` — by name or by number.
8. `terminationGracePeriodSeconds` is set explicitly and is greater than zero.
9. A `preStop` hook sleeps at least 5 seconds (the native `sleep:` handler, or
   an `exec` that sleeps).
10. The three numbers add up: `preStop + SHUTDOWN_TIMEOUT + 5s margin <=
    terminationGracePeriodSeconds`.
11. The ConfigMap supplies `PORT`, `LOG_LEVEL` and `SHUTDOWN_TIMEOUT` (a valid
    Go duration) and the container pulls them in — `envFrom.configMapRef` or
    per-key `configMapKeyRef`.
12. `resources` declares both `requests` and `limits` for cpu and memory, with
    each limit at least its request.
13. `GOMAXPROCS` is set from the CPU limit — a literal equal to the limit
    rounded up to whole cores, or `resourceFieldRef` on `limits.cpu`.
14. `GOMEMLIMIT` is set as a literal in Go's syntax, at least 50% and strictly
    less than `limits.memory`.
15. `SHUTDOWN.md` answers all four questions, names the sequence (SIGTERM,
    `terminationGracePeriodSeconds`, SIGKILL, preStop, endpoints), and states
    the ordering requirement explicitly in one sentence.

Run the referee from inside `exercise/`:

```sh
bash check.sh
```

`check.sh` reads every `.yaml` file in the folder with its own small YAML
reader, because PyYAML is not guaranteed on your machine. Keep the manifests
inside the subset it understands — also the subset every `kubectl` example
uses: **spaces only, never a tab; two spaces per level; a space after every
colon and after every `- `; plain block mappings (flow style `[a, b]` /
`{a: b}` is fine for short values); no anchors (`&`), aliases (`*`) or merge
keys (`<<:`).** A sequence may sit at its key's indentation or one level in,
and several objects may share one file if you separate them with a line
containing only `---`. If the reader ever rejects legal YAML, that is an
exercise bug, not yours — tell your tutor.

The grade is static: your manifests, your Go source and `SHUTDOWN.md`, with no
cluster, no kubectl, no Docker and no network. A Go toolchain unlocks
`shutdown_test.go`; `kubectl` unlocks a client-side dry run, and a reachable
cluster a server-side one. Anything missing is `skip`, never `FAIL`.

## Further reading

- [Kubernetes — Pod lifecycle: termination](https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle/#pod-termination)
  and [Container lifecycle hooks](https://kubernetes.io/docs/concepts/containers/container-lifecycle-hooks/)
- [pkg.go.dev — `http.Server.Shutdown`](https://pkg.go.dev/net/http#Server.Shutdown)
  and [`signal.NotifyContext`](https://pkg.go.dev/os/signal#NotifyContext)
- [go.dev — A Guide to the Go Garbage Collector](https://go.dev/doc/gc-guide)
  — the `GOMEMLIMIT` sections, including the death-spiral warning.
- [Kubernetes — Deployment rolling updates](https://kubernetes.io/docs/concepts/workloads/controllers/deployment/#rolling-update-deployment)
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 322kUpdated Claude CodeCodexVerifiedInstall