Deployments ohne Ausfall für Node-Apps mit Docker Compose · Teil 9 von 11 der Serie
Teil 9: Wenn ein Deployment schiefgeht
Sieh zu, wie eine kaputte Version scheitert, ohne dass ein einziger Besucher es merkt, bring dem Skript bei, sich ein gescheitertes Image zu merken, und bau einen Weg zurück: Ein Klick nennt ein älteres Image wieder production.
Deployments ohne Ausfall für Node-Apps mit Docker ComposeTeil 9 von 11
Auf dieser Seite
Quest-Ziele
- Eine Version, die nicht richtig starten kann, von einer unterscheiden, die läuft, aber falsch ist
- Das Skript davon abhalten, jede Minute dasselbe kaputte Image zu versuchen
- Den Health Check absichtlich kaputt machen und zusehen, wie die alte Version weiterläuft
- Zurückrollen, indem du den Tag production auf ein älteres Image setzt
- Wissen, was ein Rollback nicht zurückbringt
Früher oder später pushst du eine Version, die nicht hätte live gehen sollen. Davon gibt es zwei Sorten. Die erste kann nicht einmal richtig starten: Sie stürzt ab, oder sie läuft, erreicht aber ihre Datenbank nicht. Die fängt der Health Check ab. Die zweite startet einwandfrei, meldet, dass sie gesund ist, und tut dann das Falsche: ein kaputtes Formular, ein falscher Text, eine Seite, die seltsam aussieht. Die fängt keine Prüfung ab. Das tun Menschen.
In diesem Teil geht es um beide.
Eine Version, die nie gesund wird
Für die erste Sorte ist die meiste Arbeit schon getan. In Schritt 4 wartet das Skript darauf, dass der neue Container sich gesund meldet, und wenn er das nicht tut, entfernt das Skript ihn und behält den alten.
Ein Problem bleibt, und der Timer aus dem letzten Teil hat es geschaffen. Eine Minute später läuft das Skript wieder, stellt fest, dass production immer noch nicht das laufende Image ist, und versucht dasselbe kaputte Image noch einmal: starten, eine Minute warten, entfernen. Und wieder, jede Minute, bis jemand eine Korrektur pusht.
Das Skript soll sich also ein Image merken, das gescheitert ist. Dafür braucht es vier kleine Änderungen an deploy/deploy.sh. Erstens: Füg das hier nach der Prüfung ein, die mit Nothing new endet:
# An image that failed before is not tried again every minute.
if [ "$wanted" = "$(cat .failed 2> /dev/null || true)" ]; then
say "Still the image that failed, waiting for a new one"
exit 0
fi
fail() {
say "$1"
echo "$wanted" > .failed
exit 1
}Eine Datei namens .failed hält die ID des Images fest, das nicht funktioniert hat. Ist das Image, das die Registry anbietet, genau dieses, sagt das Skript das und endet. Der Teil hinter cat sorgt für Ruhe an den Tagen, an denen es keine solche Datei gibt. fail ist ein Helfer für alles, was ab hier schiefgehen kann: Er sagt, was passiert ist, notiert die ID des Images in der Datei und beendet das Skript mit einem Fehler.
Zweitens bekommt Schritt 2 ein neues Ende:
# 2. Bring the database up to date, with the new image's migrations.
say "New image found, updating the database"
docker compose run --rm -T web node src/migrate.js || fail "The database update failed, the old version keeps running"Die zwei Striche bedeuten „falls der Befehl davor gescheitert ist“: Eine Migration, die nicht klappt, läuft jetzt ebenfalls durch fail. Drittens: Ersetz in Schritt 4 den Block nach der Warteschleife:
if [ "$status" != healthy ]; then
docker logs --tail 20 "$new"
docker rm --force "$new" > /dev/null
fail "The new container did not get healthy, the old version keeps running"
fiUnd viertens: Füg kurz vor dem Ende eine Zeile nach der ein, die alte Images aufräumt:
docker image prune --force > /dev/null
rm -f .failedEin Deployment, das geklappt hat, vergisst den Fehlschlag davor. Das ist jetzt das ganze Skript:
#!/bin/sh
# Brings the newest image online without a gap: the new container starts beside the old
# one, has to prove it is healthy, gets the visitors, and only then the old one leaves.
set -eu
cd "$(dirname "$0")"
# Compose reports every step it takes. The log should hold only what matters.
export COMPOSE_PROGRESS=quiet
say() { echo "$(date +%H:%M:%S) $*"; }
# 1. Fetch the image the registry calls "production" and compare it with what is running.
docker compose pull --quiet web
image=$(grep "^IMAGE=" .env | cut -d = -f 2-):production
wanted=$(docker image inspect --format '{{.Id}}' "$image")
old=$(docker compose ps --quiet web)
running=""
if [ -n "$old" ]; then running=$(docker inspect --format '{{.Image}}' "$old"); fi
if [ "$wanted" = "$running" ]; then
say "Nothing new"
exit 0
fi
# An image that failed before is not tried again every minute.
if [ "$wanted" = "$(cat .failed 2> /dev/null || true)" ]; then
say "Still the image that failed, waiting for a new one"
exit 0
fi
fail() {
say "$1"
echo "$wanted" > .failed
exit 1
}
# 2. Bring the database up to date, with the new image's migrations.
say "New image found, updating the database"
docker compose run --rm -T web node src/migrate.js || fail "The database update failed, the old version keeps running"
# 3. Start a container from the new image beside the old one.
say "Starting the new container"
count=$(echo $old | wc -w)
docker compose up --detach --no-deps --no-recreate --scale web=$((count + 1)) web
new=$(docker compose ps --quiet web | grep --invert-match --fixed-strings "${old:-none}")
# 4. Wait until it reports healthy, for a minute at most.
status=starting
for attempt in $(seq 1 30); do
status=$(docker inspect --format '{{.State.Health.Status}}' "$new")
if [ "$status" = healthy ]; then break; fi
sleep 2
done
if [ "$status" != healthy ]; then
docker logs --tail 20 "$new"
docker rm --force "$new" > /dev/null
fail "The new container did not get healthy, the old version keeps running"
fi
# 5. Send the visitors to the new container.
name=$(docker inspect --format '{{.Name}}' "$new" | cut -c 2-)
echo "reverse_proxy $name:3000" > caddy/upstream.caddy
docker compose up --detach caddy
docker compose exec -T caddy caddy reload --config /etc/caddy/Caddyfile
say "Visitors now reach $name"
# 6. Let the old container finish its open requests, then remove it.
if [ -n "$old" ]; then
docker stop "$old" > /dev/null
docker rm "$old" > /dev/null
fi
docker image prune --force > /dev/null
rm -f .failed
say "Version $(docker exec "$new" printenv APP_VERSION | cut -c 1-7) is live"Kopier es auf den Server. Neu starten musst du nichts: Der Timer nimmt die neue Datei bei seiner nächsten Runde.
$ scp deploy/deploy.sh deploy@guestbook.example.com:guestbook/Ausprobieren
Mach die App absichtlich kaputt, und zwar so, dass der Health Check es merken muss. Ändere in src/db.js die Funktion ping so, dass sie eine Tabelle abfragt, die es nicht gibt:
export async function ping() {
await pool.query('select 1 from nowhere');
}Committe diese eine Datei und pushe:
$ git commit --message "Break the health check on purpose" src/db.js$ git push
Der Dateiname am Ende committet nur diese Datei. Das geänderte Skript bleibt draußen, denn das hier ist ein Commit, den du gleich wieder zurücknimmst.
Beobachte die Pipeline: Sie ist grün. Die Tests laufen durch, weil keiner deiner Tests mit einer Datenbank spricht, also wird das Image gebaut und production genannt. Tests sind das erste Sicherheitsnetz, und diese Version ist hindurchgefallen. Verfolge jetzt das Journal auf dem Server, mit dem Befehl aus dem letzten Teil:
Nov 17 10:50:00 guestbook systemd[839]: Starting guestbook-deploy.service - Deploy the newest guestbook image...Nov 17 10:50:00 guestbook deploy.sh[5512]: 10:50:00 New image found, updating the databaseNov 17 10:50:01 guestbook deploy.sh[5570]: Database is up to dateNov 17 10:50:02 guestbook deploy.sh[5512]: 10:50:02 Starting the new containerNov 17 10:51:03 guestbook deploy.sh[5731]: Guestbook listening on port 3000Nov 17 10:51:03 guestbook deploy.sh[5512]: 10:51:03 The new container did not get healthy, the old version keeps runningNov 17 10:51:03 guestbook systemd[839]: guestbook-deploy.service: Main process exited, code=exited, status=1/FAILURENov 17 10:51:03 guestbook systemd[839]: guestbook-deploy.service: Failed with result 'exit-code'.Nov 17 10:51:03 guestbook systemd[839]: Failed to start guestbook-deploy.service - Deploy the newest guestbook image.Nov 17 10:51:03 guestbook systemd[839]: Starting guestbook-deploy.service - Deploy the newest guestbook image...Nov 17 10:51:03 guestbook deploy.sh[5790]: 10:51:03 Still the image that failed, waiting for a new oneNov 17 10:51:03 guestbook systemd[839]: Finished guestbook-deploy.service - Deploy the newest guestbook image.
Lies es Zeile für Zeile. Das Skript findet das neue Image und startet einen Container daraus. Dann passiert eine Minute lang nichts: Das Skript fragt nach healthy, dreißigmal. Die Zeile Guestbook listening on port 3000 ist das Letzte, was der kaputte Container gesagt hat. Gestartet ist er, aber sein Health Check hat nie eine gute Antwort bekommen. Das Skript entfernt ihn und sagt, dass die alte Version weiterläuft, und systemd vermerkt, dass diese Runde mit einem Fehler geendet hat. Die nächste Runde des Timers war fällig, während das alles seine Minute dauerte, also läuft das Skript sofort noch einmal, sieht dasselbe Image, erkennt es und lässt es in Ruhe.
Und die Seite?
$ curl https://guestbook.example.com/health{"status":"ok","version":"e07b6d2"}
Immer noch die Version von vorher, immer noch gesund. Eine kaputte Version wurde gepusht, gebaut und dem Server angeboten, und kein Besucher ist ihr je begegnet.
Jetzt die Korrektur. git revert erzeugt einen neuen Commit, der den letzten rückgängig macht:
$ git revert --no-edit HEAD$ git push
Die Pipeline baut ein neues Image. Es hat eine andere ID als das in .failed, also deployt das Skript es wie gewohnt, als guestbook-web-4, und entfernt die Notiz.
Eine Version, die läuft, aber falsch ist
Die zweite Sorte ist schwieriger, weil für die Maschinen alles in Ordnung aussieht. Der Container ist gesund, der Tausch hat geklappt, und dann schreibt dir jemand, dass das Formular komisch aussieht.
Die schnellste Abhilfe ist, zu einer Version zurückzugehen, die funktioniert hat, und darauf hast du dich in Teil 4 vorbereitet, ohne es zu wissen: Die Registry hält noch jedes Image unter der ID seines Commits bereit. Zurückgehen heißt, einem dieser älteren Images wieder den Namen production zu geben. Der Server folgt diesem Namen und sonst nichts, also deployt er das alte Image wie jedes neue, ohne Lücke.
Angenommen, der freundlichere Platzhalter aus dem letzten Teil hat sich als Fehler herausgestellt, und du willst die Version davor zurück. Such die ID ihres Commits:
$ git log --format='%H %s' -57a1c3e94d0b2f58c6e1a9d3b7f4c2e8a5d0b6f19 Revert "Break the health check on purpose"2b9d4f8e6a0c3d7b1f5e9a2c4d8b0e6f3a7c1d95 Break the health check on purposee07b6d2c9f1a4e8b3d5c7a0f2e6b9d1c4a8f3e57 A friendlier placeholderc41f0a9b7e3d6c2f8a1b5e9d0c4f7a3e6b2d8c10 A shorter button8d3e5b7a1c9f04e62b7d5a3c8e1f6b09d4a2c7e5 Say whose guestbook it is
Die Version davor ist A shorter button, und die lange Reihe aus Buchstaben und Ziffern davor ist ihre vollständige Commit-ID. Auf GitHub fügst du sie gleich ein; auf GitLab reicht der Titel des Commits, um ihn zu finden. Jetzt bau den Weg zurück:
GitHub
Leg einen zweiten Workflow an, .github/workflows/rollback.yml:
name: Rollback
on:
workflow_dispatch:
inputs:
commit:
description: The full commit ID of the version to bring back
required: true
type: string
permissions:
packages: write
env:
IMAGE: ghcr.io/your-name/guestbook
COMMIT: ${{ inputs.commit }}
jobs:
rollback:
runs-on: ubuntu-latest
steps:
- name: Log in to the registry
run: echo "${{ secrets.GITHUB_TOKEN }}" | docker login ghcr.io --username ${{ github.actor }} --password-stdin
- name: Call the old image "production" again
run: |
docker pull "$IMAGE:$COMMIT"
docker tag "$IMAGE:$COMMIT" "$IMAGE:production"
docker push "$IMAGE:production"Ändere IMAGE auf deinen eigenen Namen, wie in Teil 4. Neu ist hier:
workflow_dispatchbedeutet, dass dieser Workflow nie von selbst startet. Er bekommt auf GitHub einen Button, undinputssetzt ein Textfeld daneben, für die Commit-ID.Es gibt nichts zu bauen und nichts zu testen, deshalb hat der eine Job nach dem Login drei Befehle: das Image dieses Commits holen, ihm zusätzlich den Namen
productiongeben und diesen Namen pushen.Was du in das Feld tippst, erreicht die Befehle über
env, als VariableCOMMIT, in Anführungszeichen. Text, den ein Mensch eingibt, wird nie direkt in einen Befehl eingesetzt: Jemand könnte einen eigenen Befehl in dieses Feld tippen.
GitLab
Ergänze in .gitlab-ci.yml oben eine dritte Stage:
stages:
- test
- build
- rollbackUnd füg diesen Job am Ende der Datei an:
back-to-this-version:
stage: rollback
image: docker:29-cli
services:
- docker:29-dind
variables:
DOCKER_TLS_CERTDIR: '/certs'
rules:
- if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
when: manual
allow_failure: true
script:
- echo "$CI_REGISTRY_PASSWORD" | docker login $CI_REGISTRY --username $CI_REGISTRY_USER --password-stdin
- docker pull $CI_REGISTRY_IMAGE:$CI_COMMIT_SHA
- docker tag $CI_REGISTRY_IMAGE:$CI_COMMIT_SHA $CI_REGISTRY_IMAGE:production
- docker push $CI_REGISTRY_IMAGE:productionNeu ist hier:
when: manualbedeutet, dass dieser Job nie von selbst startet. Jede Pipeline aufmainendet jetzt mit einem Job, der auf einen Klick wartet.allow_failure: truehält die Pipeline grün, während der Job wartet. Ohne die Zeile würde jede Pipeline als blockiert angezeigt.Es gibt nichts zu bauen und nichts zu testen, deshalb hat der Job nach dem Login drei Befehle: das Image des Commits dieser Pipeline holen, ihm zusätzlich den Namen
productiongeben und diesen Namen pushen.
Committe und pushe, zusammen mit dem geänderten Deploy-Skript:
$ git add .$ git commit --message "Remember failed images, and a way back [skip ci]"$ git push
Die Worte [skip ci] in einer Commit-Nachricht sagen GitHub und GitLab, dass sie für diesen Push keine Pipeline starten sollen. An der App hat sich nichts geändert, also gibt es nichts zu bauen und nichts zu deployen. Jetzt geh zurück:
GitHub
Öffne den Tab Actions deines Repositorys, wähl links in der Liste Rollback und drück auf Run workflow. Füg die vollständige Commit-ID von A shorter button in das Feld ein und starte ihn. Kurz darauf nennt die Registry dieses Image wieder production.
GitLab
Öffne Build → Pipelines und such die Pipeline des Commits, den du zurückhaben willst. Jede Pipeline, die ab jetzt läuft, hat die Stage rollback mit einem Play-Button an back-to-this-version: Drück ihn, und kurz darauf nennt die Registry dieses Image wieder production.
Die Pipelines, die du bisher hast, liefen, bevor es den Job gab, auch die von A shorter button, sie haben den Button also nicht. Öffne eine solche Pipeline und drück stattdessen den Retry-Button an ihrem Job build. Der baut denselben Commit noch einmal, ersetzt sein Image in der Registry durch den frischen Build und nennt es production: der längere Weg zum selben Ziel.
Dem Server muss niemand etwas sagen. Bei seinem nächsten Blick in die Registry stellt er fest, dass production nicht das ist, was läuft (Caddys zwei Zeilen sind hier weggelassen):
Nov 17 11:14:01 guestbook deploy.sh[6820]: 11:14:01 New image found, updating the databaseNov 17 11:14:02 guestbook deploy.sh[6820]: Database is up to dateNov 17 11:14:02 guestbook deploy.sh[6820]: 11:14:02 Starting the new containerNov 17 11:14:05 guestbook deploy.sh[6820]: 11:14:05 Visitors now reach guestbook-web-5Nov 17 11:14:05 guestbook deploy.sh[6820]: 11:14:05 Version c41f0a9 is live
Lade das Gästebuch neu: Der alte Platzhalter ist zurück, und in der Fußzeile steht c41f0a9. Für den Server war das ein Deployment wie jedes andere, mit Health Check, Tausch und einem freundlichen Abschied von dem Container, der gehen musste.
Eines ist noch zu tun. Dein Branch main enthält die neueren Commits samt dem Fehler, und der nächste Push baut das alles und schiebt production wieder nach vorn. Ein Rollback verschafft dir Zeit. Nutz sie, um den Code zu reparieren oder den Fehler mit git revert und seiner Commit-ID zurückzunehmen, und pushe, wenn es stimmt.
Was du jetzt hast
Drei Sicherheitsnetze, eines hinter dem anderen. Ein fehlschlagender Test stoppt die Pipeline, bevor es ein Image gibt. Eine Version, die nicht gesund wird, begegnet keinem Besucher und wird kein zweites Mal versucht. Und eine Version, die gesund, aber falsch ist, ist einen Klick davon entfernt, durch ihre Vorgängerin ersetzt zu werden.
Die Warnung oben nennt das Eine, das ein Deployment oder ein Rollback noch verderben kann: die Datenbank. Im nächsten Teil änderst du eine Tabelle, während das Gästebuch online bleibt, in drei kleinen Deployments.
Kommentare
Die Kommentare sind GitHub Discussions: Zum Schreiben mit GitHub anmelden.
Die Kommentare kommen über giscus von GitHub. Beim Laden gehen deine IP-Adresse an giscus.app und GitHub.