GitLab über mehrere Versionen upgraden, ohne die Datenbank zu zerlegen

Ein GitLab von einer Hauptversion auf die übernächste zu heben ist kein docker pull mit neuem Tag. Zwischen den Versionen liegen Datenbank-Migrationen, die aufeinander aufbauen, und wer sie überspringt, hinterlässt eine halb migrierte Datenbank. GitLab schreibt darum Required Stops vor, und die muss man respektieren.

Required Stops sind keine Empfehlung

GitLab legt fest, über welche Zwischenversionen man zwingend muss. Von 17 auf 18 heißt das nicht „direkt“, sondern: erst auf die vorgeschriebene letzte 17er, dort hochfahren, die Migrationen vollständig durchlaufen lassen, prüfen, dann auf die erste 18er, und so weiter. Jede Stufe ist ein eigener, abgeschlossener Schritt. Wer zwei Stufen auf einmal nimmt, riskiert genau die Migrationslücke, die hinterher keiner mehr sauber repariert. Welche Versionen als Pflicht-Stopp gelten, steht in der GitLab-Doku zu den Upgrade-Pfaden und lässt sich damit vorab sauber ablesen.

Die ganze Kette vorher planen

Bevor die erste Stufe startet, plane ich den kompletten Weg durch. Nach dem Upgrade ist vor dem Upgrade: Der Sprung auf die nächste Hauptversion verlangte bereits eine bestimmte Minor-Version der aktuellen UND einen Datenbank-Sprung darunter (Postgres eine Version weiter). Solche Ketten plant man vorher anhand der Upgrade-Matrix, statt mitten im Wartungsfenster festzustellen, dass noch ein Zwischenschritt fehlt. So weiß ich vor dem Wartungsfenster, wie viele Stufen es sind und wo ein Datenbank-Schritt dazwischenhängt.

Vor jeder Stufe sichern, und das Backup prüfen

Vor jeder Stufe wird gesichert, das ist die Regel, und GitLab liefert dafür eigene Backup- und Restore-Werkzeuge. Bei mir lief dieses Backup zunächst ins Leere, weil der konfigurierte Pfad (/backups) nicht der war, den das Werkzeug erwartete (/backup). Eine einzige Zeichen-Differenz, und das „Backup vor dem Upgrade“ war schlicht keins. Die Lehre ist unbequem: Es reicht nicht, ein Backup anzustoßen. Man muss prüfen, dass die Datei wirklich geschrieben wurde und eine plausible Größe hat, bevor man das Upgrade startet.

Rollback heißt Kalt-Snapshot

Geht eine Stufe schief, ist das einzige verlässliche Zurück ein Snapshot des Daten-Volumes im heruntergefahrenen Zustand. Ein Backup aus dem laufenden Betrieb kann inkonsistent sein, weil die Datenbank während der Sicherung weiterschreibt. Mein Ablauf pro Stufe war deshalb: Dienst herunterfahren, Volume snapshotten, hochfahren, migrieren. Der Snapshot ist die Versicherung, die man hoffentlich nie braucht. Wie ein regulärer Rückweg aussieht, wenn eine Stufe klemmt, beschreibt GitLab unter Troubleshooting und Rollback.

Ehrlich: Upgrades sind Wartung, kein Event

Der eigentliche Fehler passiert lange vor dem Wartungsfenster: selten upgraden. Wer zwei Jahre wartet, sammelt Required Stops an und macht aus einer Routine einen riskanten Kraftakt. Kleine, häufige Schritte sind unspektakulär und sicher. Der große Sprung ist spektakulär und gefährlich.

Sie betreiben Software, die regelmäßig und sicher aktualisiert werden muss? Ich plane und fahre solche Upgrades mit geprüftem Backup und klarem Rollback, im Wartungsfenster statt im Blindflug. Mehr unter Monitoring & Wartung, das Erstgespräch ist unverbindlich.