Rolling Upgrades ohne Ausfallzeit durchfuehren

1. Warum ein Rolling Upgrade der Standardweg ist

Ein Rolling Upgrade aktualisiert einen Elasticsearch-Cluster Node fuer Node, sodass zu jedem Zeitpunkt genuegend Nodes online bleiben, um Leseanfragen und Schreibvorgaenge weiter zu bedienen. Die Alternative, ein Full-Cluster-Restart, bei dem alle Nodes gleichzeitig gestoppt, aktualisiert und wieder gestartet werden, erfordert eine geplante Downtime und ist nur noch in seltenen Faellen noetig, etwa bei bestimmten grossen Versionssprüngen mit inkompatiblen Datenformaten. Fuer den weit ueberwiegenden Teil der Versionsupdates ist ein Rolling Upgrade der Standardweg, weil er Verfuegbarkeit und Aktualitaet miteinander vereint.

Der Kern des Verfahrens ist simpel formuliert, aber im Detail anspruchsvoll: Ein Node wird aus der Beantwortung neuer Anfragen genommen, sauber heruntergefahren, mit der neuen Version neu gestartet und muss dem Cluster wieder erfolgreich beitreten, bevor der naechste Node an der Reihe ist. Waehrend dieses Vorgangs uebernehmen die verbleibenden Replikat-Shards auf den anderen Nodes die Anfragen, die sonst der gerade aktualisierte Node bedient haette. Ohne ausreichende Replikation, also mit number_of_replicas: 0, funktioniert ein echtes Zero-Downtime-Rolling Upgrade nicht, weil ein Primary-Shard auf dem gestoppten Node fuer diese Zeit schlicht nicht erreichbar ist.

Dieser Artikel beschreibt den vollstaendigen Ablauf eines Rolling Upgrade von der Versionspruefung ueber die Shard-Allocation bis zur Automatisierung, inklusive der Sonderfaelle bei Master-Nodes und den haeufigsten Fehlerbildern, die in der Praxis auftreten.

2. Versionskompatibilitaet: was zwischen welchen Versionen erlaubt ist

Elasticsearch erlaubt einen Rolling Upgrade nur innerhalb klar definierter Kompatibilitaetsgrenzen. Innerhalb derselben Major-Version, etwa von 8.10 auf 8.15, ist ein Rolling Upgrade immer moeglich, solange keine Version uebersprungen wird, die als nicht direkt kompatibel markiert ist. Beim Wechsel zwischen zwei Major-Versionen, etwa von 7.x auf 8.x, gilt zusaetzlich die Regel, dass zuerst auf die letzte Minor-Version der alten Major-Version aktualisiert werden muss, bevor der Sprung auf die neue Major-Version beginnt. Diese letzte Minor-Version enthaelt in der Regel die noetigen Kompatibilitaetsbruecken und Deprecation-Warnungen fuer den naechsten grossen Schritt.

Ein direkter Sprung ueber mehr als eine Major-Version hinweg, etwa von 6.x direkt auf 8.x, wird von Elasticsearch nicht unterstuetzt und erfordert entweder mehrere aufeinanderfolgende Upgrade-Zyklen oder einen vollstaendigen Reindex in einen neuen Cluster. Vor jedem groesseren Rolling Upgrade lohnt sich deshalb der Blick in die offizielle Kompatibilitaetsmatrix der jeweiligen Version, weil sich die genauen Regeln von Version zu Version leicht unterscheiden koennen, insbesondere bei tiefgreifenden internen Aenderungen wie dem Wegfall von Mapping-Types zwischen 6.x und 7.x.

Bei OpenSearch gelten aehnliche Prinzipien innerhalb der eigenen Versionslinie, wobei die Divergenz seit dem Fork von Elasticsearch bedeutet, dass ein direkter Rolling Upgrade-Pfad zwischen den beiden Systemen grundsaetzlich nicht existiert. Ein Wechsel von Elasticsearch zu OpenSearch oder umgekehrt ist immer eine Migration mit Reindex, kein Rolling Upgrade im eigentlichen Sinn.

# Check current cluster version and node versions before starting
curl -s "https://localhost:9200/" -u elastic:changeme | jq '.version.number'
curl -s "https://localhost:9200/_cat/nodes?v&h=name,version,node.role" -u elastic:changeme

# Elasticsearch upgrade path rule for major version jumps:
# 7.x -> must first reach the latest 7.17.x minor release
# 7.17.x -> then rolling upgrade to 8.x is supported
# Direct 6.x -> 8.x is NOT supported, requires intermediate steps

3. Vorbereitung: Backup, Health-Check und Deprecation-Log

Vor jedem Rolling Upgrade steht ein vollstaendiger Snapshot des Clusters an erster Stelle. Auch wenn ein Rolling Upgrade in der Regel keine Daten veraendert, schuetzt ein frischer Snapshot vor unerwarteten Problemen, etwa einem fehlerhaften Plugin, das nach dem Upgrade nicht mehr kompatibel ist. Ergaenzend sollte der Cluster-Health-Status vor dem Start zwingend green sein, denn ein Rolling Upgrade, das auf einem bereits instabilen Cluster mit yellow oder red Status beginnt, erhoeht das Risiko eines Datenverlusts erheblich, wenn zusaetzlich ein Node fehlt.

Das Deprecation-Log, abrufbar ueber die Deprecation-API, zeigt alle Funktionen, Einstellungen und Query-Syntax-Formen, die in der Zielversion entfernt oder veraendert wurden und im aktuellen Cluster noch verwendet werden. Wer dieses Log vor einem Rolling Upgrade ignoriert, riskiert, dass Anwendungen nach dem Upgrade ploetzlich Fehler werfen, weil eine genutzte API-Form nicht mehr existiert. Ein sauberer Vorbereitungsschritt prueft jede gemeldete Deprecation, passt betroffene Queries und Mappings an und fuehrt das Rolling Upgrade erst danach durch.

# Full cluster health check before starting
curl -s "https://localhost:9200/_cluster/health?pretty" -u elastic:changeme

# Deprecation warnings relevant for the target version
curl -s "https://localhost:9200/_migration/deprecations?pretty" -u elastic:changeme

# Manual snapshot right before the upgrade window
curl -s -X PUT "https://localhost:9200/_snapshot/s3_backup_repo/pre-upgrade-2026-07-24?wait_for_completion=true" \
  -u elastic:changeme

4. Shard-Allocation vor dem Node-Stopp deaktivieren

Der wichtigste Einzelschritt in jedem Rolling Upgrade ist, die Shard-Allocation kurz vor dem Stoppen eines Nodes zu deaktivieren. Ohne diesen Schritt beginnt der Cluster sofort, sobald ein Node den Cluster verlaesst, die fehlenden Shards auf den verbleibenden Nodes neu zu verteilen und zu replizieren. Bei einem kurzen, geplanten Neustart im Rahmen eines Rolling Upgrade ist diese Neuverteilung unnoetig, sie kostet massiv Netzwerkbandbreite und I/O, nur um Minuten spaeter wieder rueckgaengig gemacht zu werden, sobald der Node zurueckkommt.

Die Einstellung cluster.routing.allocation.enable auf den Wert primaries gesetzt erlaubt weiterhin die Allokation von Primary-Shards, unterbindet aber die Neuverteilung von Replikat-Shards waehrend der kurzen Downtime des einzelnen Nodes. Das ist der entscheidende Kompromiss: Der Cluster bleibt voll funktionsfaehig, verschwendet aber keine Ressourcen fuer eine Neuverteilung, die ohnehin gleich wieder aufgehoben wird. Zusaetzlich empfiehlt sich vor dem Stoppen ein POST _flush/synced beziehungsweise bei neueren Versionen ein regulaerer Flush, damit der Node beim Wiederbeitritt moeglichst wenige Translog-Operationen nachholen muss.

// Step 1: disable replica shard reallocation before stopping a node
PUT /_cluster/settings
{
  "persistent": {
    "cluster.routing.allocation.enable": "primaries"
  }
}

// Step 2: flush to speed up recovery after restart
POST /_flush

// Step 3: stop Elasticsearch on the target node via the service manager
// systemctl stop elasticsearch

5. Der einzelne Node-Upgrade-Schritt im Detail

Nachdem der Node sauber gestoppt wurde, folgt die eigentliche Aktualisierung: Paketupdate ueber den Systempaketmanager, Container-Image-Wechsel oder Austausch der Binaries, abhaengig vom Deployment-Modell. Wichtig ist, dabei die Konfigurationsdateien nicht versehentlich zu ueberschreiben und Plugins, sofern verwendet, in derselben Versionsstufe wie der Elasticsearch-Core zu aktualisieren, da inkompatible Plugin-Versionen den Node-Start verhindern koennen. Nach der Aktualisierung wird der Node neu gestartet und muss dem Cluster automatisch wieder beitreten.

Der kritische Wartepunkt in diesem Schritt ist, den Node erst dann als erfolgreich aktualisiert zu betrachten, wenn er im Cluster-State wieder als aktiver Node auftaucht und alle ihm zugewiesenen Shards den Status STARTED erreicht haben. Ein zu frueher Wechsel zum naechsten Node, bevor der aktuelle wirklich vollstaendig synchronisiert ist, kann bei einem gleichzeitigen weiteren Ausfall zu einem Datenverlust-Risiko fuehren, weil dann zeitweise nicht genuegend Kopien eines Shards im Cluster vorhanden waeren.

# After restarting the upgraded node, wait until it rejoins successfully
curl -s "https://localhost:9200/_cat/nodes?v&h=name,version,node.role" -u elastic:changeme

# Confirm all shards on the node are STARTED, not INITIALIZING or RELOCATING
curl -s "https://localhost:9200/_cat/shards?v" -u elastic:changeme | grep <node-name>

# Wait for cluster health to return to green before touching the next node
curl -s "https://localhost:9200/_cluster/health?wait_for_status=green&timeout=5m" -u elastic:changeme

6. Allocation reaktivieren und auf Green warten

Sobald ein Node vollstaendig zurueck im Cluster ist, wird cluster.routing.allocation.enable auf all zurueckgesetzt, damit die normale Allocation-Logik wieder greift und der Cluster gegebenenfalls verbliebene Reparaturarbeiten an der Shard-Verteilung selbst uebernimmt. Erst danach beginnt der Health-Status realistisch gegen green zu konvergieren, denn solange die Allocation auf primaries beschraenkt ist, bleiben eventuell fehlende Replica-Shards dauerhaft im Status UNASSIGNED.

Ein haeufiger Fehler an dieser Stelle ist, direkt zum naechsten Node uebergehen, ohne die Allocation wieder zu aktivieren. Der Cluster erscheint dann faelschlich stabil, weil primaries weiterhin funktioniert, aber die Replikat-Abdeckung sinkt mit jedem weiteren Node im Rolling Upgrade, ohne dass ein offensichtlicher Fehler auftritt, bis irgendwann zu wenige Kopien eines Shards vorhanden sind. Die konsequente Sequenz aus Deaktivieren, Node upgraden, Reaktivieren, auf Green warten, ist deshalb pro Node ohne Ausnahme einzuhalten.

7. Besonderheiten bei Master- und Coordinating-Nodes

Master-eligible Nodes verdienen bei einem Rolling Upgrade besondere Aufmerksamkeit, weil der Cluster stets ein Quorum an Master-Nodes braucht, um Cluster-State-Aenderungen abzustimmen. Bei einer typischen Konfiguration mit drei dedizierten Master-Nodes toleriert der Cluster den Ausfall eines einzelnen Master-Nodes waehrend dessen Upgrade, ohne die Fähigkeit zu verlieren, einen neuen aktiven Master zu waehlen. Werden Master-Nodes nacheinander upgegradet, ohne zwischendurch auf ein stabiles Quorum zu warten, riskiert der Cluster, temporaer keinen aktiven Master mehr waehlen zu koennen, was Schreiboperationen blockiert.

Der aktuell aktive Master-Node sollte in der Upgrade-Reihenfolge bewusst als letzter der Master-eligible Nodes behandelt werden, damit nicht unnoetig mehrfach ein neuer Master gewaehlt werden muss. Coordinating-only-Nodes ohne Datenrolle sind hingegen unkritisch, weil sie keine Shards halten und ein Neustart lediglich kurzfristig eingehende Client-Verbindungen unterbricht, die von Load Balancern in der Regel automatisch auf die verbleibenden Coordinating-Nodes umgeleitet werden.

8. Automatisierung des Ablaufs in CI/CD

Ein manuell durchgefuehrtes Rolling Upgrade ist bei drei Nodes noch handhabbar, wird aber bei zwanzig oder mehr Nodes schnell fehleranfaellig, wenn jeder Schritt von Hand ausgefuehrt wird. Konfigurationsmanagement-Tools wie Ansible oder eigene Orchestrierungs-Skripte automatisieren den kompletten Ablauf: Health-Check pruefen, Allocation deaktivieren, Node aktualisieren, auf erfolgreichen Wiederbeitritt warten, Allocation reaktivieren, auf Green warten, erst dann zum naechsten Node uebergehen. Diese Abfolge laesst sich als idempotentes Playbook formulieren, das bei jedem Fehlschlag automatisch abbricht, statt fehlerhaft fortzufahren.

In Kubernetes-Umgebungen mit dem Elastic Cloud on Kubernetes Operator oder aehnlichen Operatoren fuer OpenSearch uebernimmt der Operator einen Grossteil dieser Logik automatisch, inklusive der Steuerung von Pod-Disruption-Budgets, die verhindern, dass zu viele Nodes gleichzeitig neu gestartet werden. Auch hier gilt: Vor dem Auto-Upgrade sollte die Versionskompatibilitaet manuell geprueft werden, weil der Operator zwar den Ablauf orchestriert, aber nicht automatisch pruefen kann, ob die Ziel-Version fuer den aktuellen Cluster-Zustand unterstuetzt wird.

# Simplified Ansible task sequence for one node in a rolling upgrade
- name: Disable shard allocation before stopping the node
  uri:
    url: "https://{{ es_host }}:9200/_cluster/settings"
    method: PUT
    body_format: json
    body:
      persistent:
        cluster.routing.allocation.enable: primaries

- name: Stop Elasticsearch service on the target node
  systemd:
    name: elasticsearch
    state: stopped

- name: Upgrade Elasticsearch package to the target version
  apt:
    name: "elasticsearch={{ target_version }}"
    state: present

- name: Start Elasticsearch service again
  systemd:
    name: elasticsearch
    state: started

- name: Wait until cluster health returns to green
  uri:
    url: "https://{{ es_host }}:9200/_cluster/health?wait_for_status=green&timeout=5m"
  register: health_check
  until: health_check.json.status == "green"
  retries: 30
  delay: 10

- name: Re-enable shard allocation for the whole cluster
  uri:
    url: "https://{{ es_host }}:9200/_cluster/settings"
    method: PUT
    body_format: json
    body:
      persistent:
        cluster.routing.allocation.enable: all

9. Typische Fehlerbilder waehrend eines Rolling Upgrade

Das haeufigste Problem ist ein Node, der nach dem Neustart nicht wieder dem Cluster beitritt, meist wegen einer inkompatiblen Plugin-Version, eines Zertifikatsfehlers nach einer parallel durchgefuehrten Sicherheits-Konfigurationsaenderung, oder weil discovery.seed_hosts nach einer Netzwerkaenderung nicht mehr korrekt aufgeloest wird. In diesem Fall bleibt der Node isoliert, waehrend der restliche Cluster mit reduzierter Kapazitaet weiterlaeuft. Die Logs des betroffenen Nodes zeigen fast immer die konkrete Ursache direkt beim Startvorgang.

Ein zweites klassisches Problem ist ein Cluster, der nach mehreren Node-Upgrades im Status yellow haengen bleibt, weil vergessen wurde, die Shard-Allocation nach einem Schritt wieder zu reaktivieren. Die Diagnose ist einfach: GET _cluster/settings zeigt sofort, ob cluster.routing.allocation.enable noch auf primaries steht. Ein drittes Fehlerbild betrifft Split-Brain-aehnliche Situationen bei Master-Nodes, wenn zu viele Master-eligible Nodes gleichzeitig upgegradet werden und das Quorum kurzzeitig unterschritten wird, was durch die im vorherigen Abschnitt beschriebene sequenzielle Vorgehensweise zuverlaessig vermieden wird.

10. Zusammenfassung

Ein Rolling Upgrade bringt einen produktiven Elasticsearch- oder OpenSearch-Cluster ohne geplante Ausfallzeit auf eine neue Version, wenn die Reihenfolge konsequent eingehalten wird: Vorbereitung mit Snapshot und Health-Check, Shard-Allocation vor jedem Node-Stopp auf primaries setzen, Node aktualisieren, auf vollstaendigen Wiederbeitritt warten, Allocation reaktivieren und erst bei Green zum naechsten Node uebergehen. Master-eligible Nodes brauchen zusaetzliche Aufmerksamkeit fuer das Quorum, waehrend Coordinating-Nodes unkritisch sind.

Die Versionskompatibilitaetsregeln bestimmen, wie viele Zwischenschritte ein Rolling Upgrade braucht, insbesondere bei Major-Version-Spruengen, die immer ueber die letzte Minor-Version der alten Reihe fuehren muessen. Wer diesen Ablauf automatisiert und regelmaessig durchfuehrt, statt Upgrades ueber Jahre aufzuschieben, reduziert das Risiko grosser, riskanter Versionssprünge und haelt den Cluster durchgehend auf einem unterstuetzten, sicherheitsgepatchten Stand.

11. FAQ: Rolling Upgrades ohne Ausfallzeit