Skip to main content
RunBook Academy

← All checklists in Docker & Containers

Before deploymentUpgrade

Checklist: Container runtime upgrade readiness

21 items ·15 critical ·6 warn ·0 info

When to run this

Before every engine, containerd or runc upgrade on a host carrying production workloads — including the ones that arrive as part of a routine OS patch cycle, which is how most runtime upgrades actually happen. Budget 30 minutes for the checks and capture the output; a third of the items exist so that you have a “before” to compare against afterwards.

How to run it

Set the stack directory first, and run everything as root or via sudo — dockerd --validate, the journal query and the package checks all need it:

STACK_DIR=/srv/stacks/platform

The package items assume Debian or Ubuntu. On RHEL-family hosts the equivalents are dnf list --showduplicates docker-ce, dnf versionlock list, and ls /var/cache/dnf/*/packages/docker-ce-*.rpm.

Capture the output of current-version-recorded, storage-driver-recorded and post-upgrade-compare into the change record. The first two are your rollback target and the third is the only honest verification that the upgrade did what you expected.

Reading the results

Seven items print only when something is wrong: live-restore-state-known, no-unhealthy-before, no-restarting-before, restart-policies-set, volumes-backed-up, compose-files-committed and daemon-log-clean. Silence is the pass.

Three items have no command at all — live-restore-limits-understood, canary-first, drain-plan — because nothing on the host can prove them. They are the items most likely to be the reason an upgrade goes badly, so they need a named person’s sign-off rather than a green tick.

Evidence and sign-off

  • Engine / containerd / runc before: ______________________
  • Storage driver before: ______________ after: ______________
  • Live restore: ______ Canary host and date: ______________
  • Operator: _________________ Date: ___________
  • Reviewer: ________________ Date: ___________

Critical15 items

  1. docker version --format 'engine={{.Server.Version}} api={{.Server.APIVersion}}'; containerd --version; runc --version
  2. jq -e . /etc/docker/daemon.json >/dev/null
  3. dockerd --validate --config-file /etc/docker/daemon.json
  4. docker info --format '{{.LiveRestoreEnabled}}' | grep -qx true || echo "live-restore OFF: every container stops when dockerd restarts"
  6. docker ps --filter 'health=unhealthy' --format '{{.Names}}'
  7. docker ps --filter 'status=restarting' --format '{{.Names}}'
  8. docker ps -q | xargs -r docker inspect --format '{{.Name}} {{.HostConfig.RestartPolicy.Name}}' | awk '$2=="no" || $2==""'
  9. ls -1 /var/cache/apt/archives/docker-ce_*.deb /var/cache/apt/archives/containerd.io_*.deb 2>/dev/null
  10. docker info --format 'driver={{.Driver}} root={{.DockerRootDir}}'
  11. comm -23 <(docker volume ls -q | sort) <(sort /etc/backup/volumes.include)
  12. git -C "$STACK_DIR" status --porcelain
  15. docker info --format 'driver={{.Driver}} cgroups={{.CgroupVersion}} live-restore={{.LiveRestoreEnabled}} containers={{.Containers}} running={{.ContainersRunning}}'

Warning6 items

  1. apt-cache madison docker-ce | head -5
  2. apt-mark showhold | grep -E 'docker-ce|containerd|runc'
  3. docker info --format '{{.CgroupVersion}} {{.CgroupDriver}}' | grep -qx "2 systemd" || docker info --format 'cgroups={{.CgroupVersion}} driver={{.CgroupDriver}}'
  4. uname -r; ls -1t /boot/vmlinuz-* | head -1
  5. journalctl -u docker --since -24h -p err --no-pager | grep -v "^-- No entries --$"