Reindexing ohne Downtime mit Alias-Swapping durchfuehren

1. Warum Reindexing in Elasticsearch ueberhaupt noetig ist

Ein Elasticsearch-Mapping ist nach der Indexerstellung fuer die meisten Aenderungen faktisch eingefroren: ein bestehendes Feld von text auf keyword umzustellen, eine Analyzer-Konfiguration zu wechseln oder die Shard-Anzahl anzupassen ist ohne Reindexing nicht moeglich. Der einzige Weg, ein grundlegend geaendertes Mapping wirksam zu machen, ist ein neuer Index mit dem gewuenschten Mapping und ein anschliessendes Kopieren aller Dokumente aus dem alten in den neuen Index.

Ohne einen strukturierten Prozess fuer dieses Reindexing bedeutet jede Mapping-Aenderung eine Downtime: die Applikation muss angehalten werden, Daten werden migriert, und erst danach wird der Traffic wieder freigegeben. Bei Systemen mit kontinuierlichem Schreibverkehr, etwa einer Produktsuche im E-Commerce oder einem Log-Aggregator, ist das inakzeptabel. Ein Wartungsfenster von mehreren Stunden fuer eine Mapping-Aenderung ist in produktiven Umgebungen selten vertretbar.

Die Loesung fuer Reindexing ohne Downtime basiert auf einer einfachen Idee: Clients sprechen nie direkt einen physischen Index an, sondern immer einen Alias. Der Alias zeigt zunaechst auf den alten Index, waehrend im Hintergrund ein neuer Index mit korrektem Mapping befuellt wird. Erst wenn die Migration vollstaendig validiert ist, wird der Alias in einer einzigen atomaren Operation auf den neuen Index umgehaengt, ohne dass eine Anwendung ihre Konfiguration aendern muss.

2. Die _reindex API im Detail

Die _reindex API kopiert Dokumente von einem Quell-Index in einen Ziel-Index, komplett innerhalb des Clusters, ohne dass Daten den Server verlassen. Der Endpunkt akzeptiert einen source-Block mit optionaler Query zur Filterung, einen dest-Block mit dem Zielindex, und optional ein script zur Transformation jedes Dokuments waehrend der Kopie. Fuer das reine Migrations-Reindexing ohne Transformation genuegt die minimale Form mit nur source.index und dest.index.

Wichtig fuer produktive Nutzung ist der Parameter wait_for_completion. Standardmaessig blockiert die _reindex-Anfrage, bis alle Dokumente kopiert sind, was bei grossen Indizes zu Timeouts fuehrt. Mit wait_for_completion=false gibt die API sofort eine Task-ID zurueck, deren Fortschritt ueber die Task-API abgefragt werden kann. Dieses asynchrone Muster ist bei jedem Reindexing mit mehr als wenigen tausend Dokumenten die richtige Wahl.

POST _reindex?wait_for_completion=false
{
  "source": {
    "index": "products_v1",
    "size": 1000
  },
  "dest": {
    "index": "products_v2",
    "op_type": "create"
  },
  "conflicts": "proceed"
}

Der Parameter op_type: create verhindert, dass bereits existierende Dokumente im Ziel-Index ueberschrieben werden, was bei einem wiederholten Lauf desselben Reindexing-Jobs nach einem Abbruch relevant wird. conflicts: proceed sorgt dafuer, dass Versionskonflikte einzelner Dokumente den gesamten Job nicht abbrechen, sondern lediglich gezaehlt und im Ergebnis gemeldet werden.

3. Write-Alias und Read-Alias als Grundmuster

Das zentrale Architekturmuster fuer Reindexing ohne Downtime ist, dass Applikationen niemals direkt gegen einen physischen Indexnamen wie products_v1 schreiben oder lesen, sondern ausschliesslich gegen einen stabilen Alias wie products. Beim Anlegen des ersten Index wird der Alias sofort mitgesetzt, sodass von Anfang an eine Indirektionsebene existiert. Diese Indirektion ist die Voraussetzung dafuer, dass ein spaeteres Reindexing ueberhaupt ohne Client-Aenderung moeglich ist.

In vielen Setups reicht ein einzelner Alias fuer Lesen und Schreiben, in Systemen mit hoher Schreiblast trennt man haeufig einen dedizierten Write-Alias von einem oder mehreren Read-Aliases, um waehrend der Migrationsphase Lesezugriffe gezielt gegen den alten oder neuen Index zu steuern. Das folgende Beispiel zeigt das grundlegende Alias-Setup direkt bei der Indexerstellung.

PUT products_v1
{
  "aliases": {
    "products": { },
    "products_write": { "is_write_index": true }
  },
  "mappings": {
    "properties": {
      "sku": { "type": "keyword" },
      "name": { "type": "text" }
    }
  }
}

Jede Schreiboperation der Applikation richtet sich gegen products_write, jede Leseoperation gegen products. Diese Trennung erlaubt es spaeter, den Lese-Alias schrittweise umzuschalten, waehrend der Write-Alias erst nach vollstaendiger Validierung wechselt, was das Risiko eines fehlerhaften Reindexing-Vorgangs deutlich reduziert.

4. Der atomare Alias-Swap

Der entscheidende Schritt jedes Reindexing-ohne-Downtime-Vorgangs ist der Alias-Swap ueber den _aliases-Endpunkt mit den Aktionen remove und add in einem einzigen Request. Elasticsearch fuehrt beide Aktionen atomar aus, es existiert zu keinem Zeitpunkt ein Zustand, in dem der Alias auf keinen oder auf beide Indizes gleichzeitig zeigt. Das unterscheidet den Alias-Swap fundamental von zwei separaten Requests, zwischen denen theoretisch Anfragen ins Leere laufen koennten.

POST _aliases
{
  "actions": [
    { "remove": { "index": "products_v1", "alias": "products" } },
    { "add":    { "index": "products_v2", "alias": "products" } },
    { "remove": { "index": "products_v1", "alias": "products_write" } },
    { "add":    { "index": "products_v2", "alias": "products_write", "is_write_index": true } }
  ]
}

Nach diesem Swap sehen alle Clients, die gegen den Alias products arbeiten, sofort den neuen Index, ohne dass eine Konfigurationsdatei geaendert oder ein Deployment ausgeloest werden muss. Der alte Index products_v1 bleibt zunaechst bestehen und kann als Fallback dienen, falls nach dem Swap unerwartete Probleme mit dem neuen Mapping auftauchen. Erst nach einer Beobachtungsphase, typischerweise mehrere Tage, wird der alte Index endgueltig geloescht.

5. Reindexing mit Transformation und Ingest-Pipelines

Reines Kopieren reicht selten aus, oft muss waehrend des Reindexing auch die Datenstruktur transformiert werden, etwa um ein Feld umzubenennen, einen Wert zu normalisieren oder mehrere Felder zusammenzufuehren. Die _reindex API unterstuetzt dafuer ein script-Objekt mit Painless-Code, das fuer jedes Dokument vor dem Schreiben in den Ziel-Index ausgefuehrt wird. Alternativ laesst sich eine Ingest-Pipeline referenzieren, was sich besonders eignet, wenn dieselbe Transformationslogik auch fuer neu eintreffende Dokumente ausserhalb des Reindexing-Vorgangs gelten soll.

POST _reindex
{
  "source": { "index": "products_v1" },
  "dest": { "index": "products_v2" },
  "script": {
    "lang": "painless",
    "source": "ctx._source.sku = ctx._source.remove('legacy_sku'); ctx._source.price_cents = (int)(ctx._source.price * 100)"
  }
}

Bei komplexeren Transformationen empfiehlt es sich, die Ingest-Pipeline getrennt zu testen, bevor sie in ein produktives Reindexing eingebunden wird. Ein Fehler im Painless-Script fuehrt dazu, dass einzelne Dokumente scheitern, wobei das Verhalten je nach conflicts-Einstellung entweder den ganzen Job stoppt oder die fehlerhaften Dokumente ueberspringt und im Ergebnis-Report als Failures auflistet.

6. Throttling, Batch-Groesse und Slicing

Ein unkontrolliertes Reindexing mit voller Geschwindigkeit kann einen produktiven Cluster spuerbar belasten, weil es CPU, I/O und Heap fuer regulaere Suchanfragen konkurriert. Der Parameter requests_per_second begrenzt die Rate, mit der Batches verarbeitet werden, und erlaubt es, das Reindexing gezielt zu drosseln, sodass produktiver Traffic priorisiert bleibt. Der Parameter size im source-Block steuert die Batch-Groesse pro Scroll-Anfrage.

Fuer grosse Indizes mit vielen Shards beschleunigt slices das Reindexing erheblich, indem der Job in mehrere parallele Teilaufgaben aufgeteilt wird, die jeweils einen Teil der Quell-Shards bearbeiten. Mit "slices": "auto" ermittelt Elasticsearch die Anzahl automatisch anhand der Shard-Zahl des Quell-Index. Diese Parallelisierung reduziert die Gesamtdauer bei grossen Datenmengen deutlich, erhoeht aber gleichzeitig die Systemlast, weshalb Slicing und Throttling meist zusammen konfiguriert werden.

# Throttled, parallelized reindex with progress polling
curl -s -X POST "https://es.mironsoft.de:9200/_reindex?wait_for_completion=false" \
  -H "Content-Type: application/json" -d '{
    "source": { "index": "products_v1", "size": 500 },
    "dest": { "index": "products_v2" },
    "slices": "auto"
  }'
# Response contains a task id, e.g. "task": "node1:123456"

curl -s "https://es.mironsoft.de:9200/_tasks/node1:123456" | jq '.task.status'

7. Validierung vor dem Swap

Bevor der Alias-Swap ausgefuehrt wird, muss der neue Index sorgfaeltig validiert werden, denn nach dem Swap sehen alle Clients sofort die neuen Daten. Der einfachste Check ist ein Dokumentenzahl-Vergleich zwischen Quelle und Ziel ueber GET products_v1/_count und GET products_v2/_count. Weichen die Zahlen ohne erwartete conflicts voneinander ab, deutet das auf ein unvollstaendiges Reindexing hin, das vor dem Swap untersucht werden muss.

Ueber Stichproben-Vergleiche hinaus lohnt es sich, gezielte Testabfragen gegen den neuen Index laufen zu lassen, die typische Applikationsanfragen simulieren, etwa Aggregationen ueber neu gemappte Felder oder Volltextsuchen mit dem geaenderten Analyzer. Ein Vergleich der Ergebnisstruktur zwischen altem und neuem Index deckt Mapping-Fehler auf, die ein reiner Count-Vergleich nicht erkennt, etwa wenn ein Feld zwar denselben Namen, aber einen anderen Datentyp erhalten hat und dadurch Aggregationen anders gruppieren.

8. Rollback-Strategie bei fehlgeschlagenem Reindexing

Weil der Alias-Swap atomar und sofort wirksam ist, muss fuer den Fall eines fehlerhaften neuen Mappings eine ebenso schnelle Rollback-Option existieren. Der grosse Vorteil des Alias-Patterns ist, dass ein Rollback lediglich ein zweiter _aliases-Request in umgekehrter Richtung ist: der Alias wird vom neuen Index zurueck auf den alten Index gehaengt, ohne dass der alte Index zwischenzeitlich geloescht wurde. Solange products_v1 noch existiert, ist ein Rollback binnen Millisekunden moeglich.

Kritischer wird es, wenn zwischen Swap und Rollback bereits neue Schreiboperationen gegen den neuen Index gelaufen sind. Diese Dokumente muessten nach einem Rollback zusaetzlich in den alten Index nachgezogen werden, was den Rollback erheblich verkompliziert. Aus diesem Grund empfiehlt sich eine kurze Beobachtungsphase mit reduziertem Schreibverkehr direkt nach dem Swap, sowie ein Monitoring, das ungewoehnliche Fehlerraten sofort meldet, damit ein Reindexing-Rollback so frueh wie moeglich ausgeloest werden kann.

9. Reindexing bei laufendem Schreibverkehr

Die groesste Herausforderung bei Reindexing ohne Downtime ist ein Index, der waehrend der Migration weiterhin Schreibvorgaenge erhaelt. Die _reindex API kopiert einen Snapshot zum Startzeitpunkt, Dokumente, die danach im Quell-Index geschrieben werden, landen nicht automatisch im Ziel-Index. Die uebliche Loesung ist ein zweiphasiger Ansatz: zuerst ein initiales _reindex ueber den gesamten Bestand, danach ein oder mehrere Delta-Reindex-Laeufe mit einer Query, die nur Dokumente seit dem letzten Lauf erfasst, etwa gefiltert nach einem updated_at-Zeitstempel.

Fuer sehr schreibintensive Systeme ist Dual-Write eine robustere Alternative: die Applikation schreibt waehrend der Migrationsphase parallel in beide Indizes, sodass beide stets synchron bleiben, bevor der Lese-Alias umgeschaltet wird. Dual-Write erfordert Aenderungen im Applikationscode, eliminiert aber das Risiko verpasster Delta-Dokumente vollstaendig und ist die bevorzugte Strategie bei Systemen mit strengen Konsistenzanforderungen.

10. Zusammenfassung

Reindexing ohne Downtime ist kein Sonderfeature, sondern eine notwendige Konsequenz aus der Tatsache, dass Elasticsearch-Mappings nach der Indexerstellung weitgehend unveraenderlich sind. Die _reindex API kopiert Dokumente effizient in einen neu gemappten Index, waehrend das Write-Alias/Read-Alias-Pattern sicherstellt, dass Clients nie einen physischen Indexnamen kennen muessen. Der atomare Alias-Swap ueber _aliases mit remove und add in einem Request macht den Wechsel auf das neue Mapping fuer Nutzer unsichtbar.

Fuer produktive Systeme mit kontinuierlichem Schreibverkehr braucht es zusaetzlich eine Strategie fuer Delta-Daten, sei es ueber Zeitstempel-basierte Nachlaeufe oder Dual-Write waehrend der Migrationsphase. Validierung vor dem Swap und die Moeglichkeit eines sofortigen Rollbacks durch Zuruecksetzen des Alias sind die zwei Sicherheitsnetze, die ein Reindexing-Vorhaben von einem riskanten Ad-hoc-Eingriff zu einem planbaren, wiederholbaren Prozess machen.

11. FAQ: Reindexing ohne Downtime