DevOps-Tools & Best Practices meistern - DevOps Knowledge Hub DevOps-Tools & Best Practices meistern - DevOps Knowledge Hub

Fehlerbehebung für den Elasticsearch-Cluster-Status: Eine Schritt-für-Schritt-Anleitung

Haben Sie einen gelben oder roten Elasticsearch-Cluster? Diagnostizieren Sie nicht zugewiesene Shards, Speicherdruck, Knotenausfälle und sichere Wiederherstellungsoptionen.

Fehlerbehebung für den Elasticsearch-Cluster-Status: Eine Schritt-für-Schritt-Anleitung

Ein gelber oder roter Elasticsearch-Cluster ist kein mysteriöser Zustand. Er bedeutet normalerweise, dass Elasticsearch einen oder mehrere Shards nicht dort platzieren kann, wo es sie haben möchte. Die Aufgabe besteht darin, herauszufinden, welcher Shard feststeckt, warum die Zuweisung blockiert ist und ob die richtige Lösung darin besteht, zu warten, Ressourcen freizugeben, einen Knoten zurückzubringen, aus einem Snapshot wiederherzustellen oder bewusst Datenverlust zu akzeptieren.

Ich behandle den Cluster-Status als Triage-Signal, nicht als Diagnose selbst. Grün bedeutet, dass jeder primäre und replizierte Shard zugewiesen ist. Gelb bedeutet, dass alle primären Shards zugewiesen sind, sodass Suchen und Schreiben in der Regel fortgesetzt werden können, aber mindestens ein Replikat fehlt. Rot bedeutet, dass mindestens ein primärer Shard nicht zugewiesen ist, sodass ein Teil mindestens eines Index nicht verfügbar ist. Rot ist der Zustand, der sofort Anwendungslese- oder -schreibvorgänge unterbrechen kann.

Beginnen Sie mit der einfachen Ansicht:

GET /_cluster/health?pretty
GET /_cat/health?v

Achten Sie auf status, number_of_nodes, active_primary_shards, unassigned_shards, initializing_shards und relocating_shards. Wenn Sie nach einem Knotenneustart initialisierende oder verlagernde Shards sehen, erholt sich der Cluster möglicherweise bereits. Ändern Sie keine Zuweisungseinstellungen, bevor Sie wissen, ob Elasticsearch einfach nur arbeitet.

Listen Sie dann die nicht zugewiesenen Shards auf:

GET /_cat/shards?v&h=index,shard,prirep,state,node,unassigned.reason&s=state,index,shard

Die Spalte prirep ist wichtig. Ein p-Shard ist primär. Ein roter Cluster hat immer mindestens einen nicht zugewiesenen primären Shard. Ein r-Shard ist ein Replikat. Ein gelber Cluster hat normalerweise nur nicht zugewiesene Replikate.

Die nützlichste API in dieser Situation ist die Zuweisungserklärung:

GET /_cluster/allocation/explain?pretty

Für einen bestimmten Shard geben Sie ihn explizit an:

GET /_cluster/allocation/explain?pretty
{
  "index": "logs-2026.05.24",
  "shard": 0,
  "primary": false
}

Lesen Sie die Antwort can_allocate und die Entscheidungen auf Knotenebene. Elasticsearch teilt Ihnen normalerweise genau mit, welche Regel die Zuweisung blockiert hat: Datenträger-Wasserzeichen, Zuweisungsfilterung, Same-Shard-Regeln, verzögerte Zuweisung nachdem ein Knoten verlassen wurde, fehlende primäre Daten, inkompatible Versionen oder ein Rollenkonflikt des Knotens.

Wenn der Cluster Gelb Ist

Gelb ist bei kleinen Clustern üblich. Der klassische Fall ist ein Ein-Knoten-Entwicklungscluster mit number_of_replicas: 1. Elasticsearch kann ein Replikat nicht auf demselben Knoten wie sein Primärshard platzieren, daher bleibt das Replikat für immer nicht zugewiesen. Das ist in einer Laptop-Umgebung kein Notfall. Es ist ein Konfigurationskonflikt.

Überprüfen Sie die Replikatanzahl:

GET /my-index/_settings?filter_path=*.settings.index.number_of_replicas

Setzen Sie für einen Ein-Knoten-Nicht-Produktionscluster die Replikate auf Null:

PUT /my-index/_settings
{
  "index": {
    "number_of_replicas": 0
  }
}

Verstecken Sie das Problem in der Produktion nicht, indem Sie Replikate reduzieren, es sei denn, Sie akzeptieren bewusst weniger Redundanz. Wenn der Index ein Replikat haben soll, benötigen Sie mindestens zwei berechtigte Datenknoten. Wenn er zwei Replikate hat, benötigen Sie mindestens drei berechtigte Datenknoten. Die Tiering kann dies weniger offensichtlich machen: Ein Warm-Index-Replikat kann nicht auf einen Hot-Only-Knoten zugewiesen werden, wenn die Zuweisungsregeln Warm-Knoten erfordern.

Speicherdruck ist die nächste häufige Ursache für Gelb. Überprüfen Sie die Datenträgernutzung der Knoten:

GET /_cat/allocation?v
GET /_cat/nodes?v&h=name,roles,disk.used_percent,disk.avail,heap.percent,cpu,load_1m

Elasticsearch verwendet Datenträger-Wasserzeichen, um ein Überfüllen von Knoten zu vermeiden. Die Standardwerte variieren je nach Version und Konfiguration. Überprüfen Sie daher die tatsächlichen Clustereinstellungen:

GET /_cluster/settings?include_defaults=true&flat_settings=true&filter_path=**cluster.routing.allocation.disk.watermark**

Wenn ein Knoten über dem hohen Wasserzeichen liegt, vermeidet Elasticsearch, dort weitere Shards zuzuweisen. Wenn es das Flutstufen-Wasserzeichen erreicht, kann Elasticsearch betroffene Indizes in einen schreibgeschützten Zustand versetzen, um den Knoten zu schützen. Die dauerhafte Lösung besteht darin, alte Daten zu löschen, Daten auf mehr Knoten zu verschieben, den Datenträger zu vergrößern, überdimensionierte Shard-Anzahlen zu reduzieren oder die ILM-Aufbewahrung anzupassen. Das vorübergehende Anheben der Wasserzeichen kann Zeit verschaffen, sollte aber nicht Ihr erster Schritt sein.

Eine praktische Bereinigungssequenz sieht so aus:

GET /_cat/indices?v&s=store.size:desc
GET /_cat/shards?v&s=store:desc

Finden Sie große alte Indizes, überprüfen Sie die Aufbewahrungserwartungen mit dem verantwortlichen Team, erstellen Sie bei Bedarf einen Snapshot und löschen Sie dann nur Daten, die Sie entfernen dürfen:

DELETE /old-logs-2025.12.*

Nachdem Speicherplatz freigegeben wurde, kann die Zuweisung automatisch fortgesetzt werden. Wenn nicht, führen Sie die Zuweisungserklärung erneut aus. Der alte Grund ist möglicherweise noch in Ihrem Kopf zwischengespeichert, aber der Cluster wird jetzt möglicherweise durch eine andere Regel blockiert.

Zuweisungsfilterung ist eine weitere häufige Ursache für Gelb, insbesondere nach Hardware-Migrationen. Möglicherweise hat jemand einen Index so eingestellt, dass er ein Knotenattribut erfordert, das nicht mehr existiert:

GET /my-index/_settings?flat_settings=true&filter_path=*.settings.index.routing.allocation*
GET /_cluster/settings?flat_settings=true&filter_path=**routing.allocation**

Wenn die Regel falsch ist, entfernen oder aktualisieren Sie sie:

PUT /my-index/_settings
{
  "index.routing.allocation.require.box_type": null,
  "index.routing.allocation.include._name": null,
  "index.routing.allocation.exclude._name": null
}

Verwenden Sie die genauen Schlüssel, die Ihre Einstellungen anzeigen. Fügen Sie keinen breiten Reset in die Produktion ein, ohne ihn zu lesen; Zuweisungsregeln sind manchmal aus gutem Grund vorhanden, z. B. um bestimmte Daten auf einer Compliance-kontrollierten Ebene zu halten.

Wenn der Cluster Rot Ist

Rot verdient langsamere Hände und bessere Notizen. Die erste Frage ist, ob der fehlende primäre Shard irgendwo eine wiederherstellbare Kopie hat.

Listen Sie nicht zugewiesene primäre Shards auf:

GET /_cat/shards?v&h=index,shard,prirep,state,unassigned.reason | grep ' p UNASSIGNED'

Überprüfen Sie dann, welche Knoten vorhanden sind:

GET /_cat/nodes?v&h=name,ip,roles,master,uptime,heap.percent,disk.avail

Wenn ein Knoten fehlt, besteht der beste Wiederherstellungspfad oft darin, diesen Knoten zurückzubringen. Überprüfen Sie den Dienst, die Datenträgermontierung, das Host-Netzwerk, die Zertifikate und die Protokolle auf dem fehlenden Knoten. Ein Knoten, der den Zugriff auf seinen Datenpfad verloren hat, kann als anderer leerer Knoten starten, was nicht hilft, den primären Shard wiederherzustellen.

Auf dem Elasticsearch-Knoten zeigen die Protokolle normalerweise den tatsächlichen Fehler früher als die APIs. Achten Sie auf Nachrichten über Shard-Sperrfehler, beschädigte Indexdateien, Master-Erkennung, TLS-Handshake-Fehler, schreibgeschützte Dateisysteme oder Rollenänderungen des Knotens. Ein häufiger realer Fehler ist ein Neustart eines Knotens, nachdem ein Datenträger unter einem anderen Pfad neu eingehängt wurde. Elasticsearch startet, aber der Datenpfad ist leer, sodass dem Cluster immer noch die benötigte Shard-Kopie fehlt.

Führen Sie die Zuweisungserklärung für den primären Shard aus:

GET /_cluster/allocation/explain?pretty
{
  "index": "orders-2026.05.24",
  "shard": 2,
  "primary": true
}

Wenn die Erklärung besagt, dass keine gültige Shard-Kopie gefunden werden kann, stoppen Sie und überprüfen Sie Snapshots, bevor Sie etwas Destruktives tun:

GET /_snapshot/_all
GET /_snapshot/my-repository/_all?verbose=false

Die Wiederherstellung eines Snapshots ist normalerweise sicherer als die Zuweisung eines leeren primären Shards. Ein leerer primärer Shard erstellt einen neuen leeren Shard für diese Shard-ID. Es ist kein Reparaturvorgang. Es teilt Elasticsearch mit: "Ich akzeptiere, dass die alten Daten für diesen Shard verloren sind."

Der letzte Ausweg-Befehl sieht so aus:

POST /_cluster/reroute
{
  "commands": [
    {
      "allocate_empty_primary": {
        "index": "orders-2026.05.24",
        "shard": 2,
        "node": "es-data-03",
        "accept_data_loss": true
      }
    }
  ]
}

Verwenden Sie es nur, nachdem Sie bestätigt haben, dass es keine nutzbare Knotenkopie und keinen wiederherstellbaren Snapshot gibt. Notieren Sie bei einem Vorfall, wer diese Wahl genehmigt hat und welcher Index und Shard betroffen waren. Die zukünftige Fehlerbehebung ist viel einfacher, wenn die Entscheidung über den Datenverlust explizit ist.

Fälle, die wie Zuweisungsprobleme aussehen, aber eigentlich Clusterprobleme sind

Manchmal sind Shards nicht zugewiesen, weil der Cluster keine stabile Mitgliedschaft aufrechterhalten kann. Wenn master-fähige Knoten nicht miteinander kommunizieren können, kann sich der gewählte Master wiederholt ändern, und die Zuweisung wird chaotisch oder pausiert. Überprüfen Sie die Master-Stabilität:

GET /_cat/master?v
GET /_cat/nodes?v&h=name,roles,master,ip

Wenn sich der Master häufig ändert, überprüfen Sie die Netzwerkzuverlässigkeit, DNS, Knotenzertifikate und Erkennungseinstellungen. Für moderne Elasticsearch-Cluster ist cluster.initial_master_nodes für die anfängliche Cluster-Bootstrapping gedacht, nicht als Einstellung, die man für immer als allgemeine Erkennungskrücke belässt. discovery.seed_hosts sollte auf geeignete Seed-Hosts verweisen, und alle Knoten müssen denselben Clusternamen und kompatible Sicherheitseinstellungen verwenden.

Hoher JVM-Druck kann ebenfalls Zuweisungssymptome verursachen. Ein Datenknoten, der in langen Garbage-Collection-Pausen steckt, kann den Cluster aus Sicht des Masters verlassen und wieder beitreten. Dies kann nicht zugewiesene Shards erzeugen, obwohl der Computer nie vollständig abgestürzt ist.

Überprüfen Sie Heap- und Garbage-Collection-Protokolle:

GET /_cat/nodes?v&h=name,heap.percent,ram.percent,cpu,load_1m,node.role
GET /_nodes/stats/jvm?filter_path=nodes.*.jvm.mem,nodes.*.jvm.gc

Wenn der Heap konstant hoch ist, erhöhen Sie ihn nicht blind. Elasticsearch funktioniert im Allgemeinen am besten, wenn der Heap genügend Speicher für den Dateisystem-Cache übrig lässt. Achten Sie auf überdimensionierte Aggregationen, starke Felddatennutzung, zu viele Shards, aggressives Indizieren oder Abfragen, die bessere Zuordnungen benötigen.

Die Shard-Anzahl kann die stille Ursache für viele Gesundheitsprobleme sein. Ein Cluster mit vielen winzigen Shards verbringt zu viel Zeit damit, Metadaten zu verfolgen und Shards zu verschieben. Verwenden Sie:

GET /_cat/indices?v&h=index,pri,rep,docs.count,store.size,pri.store.size&s=pri:desc
GET /_cluster/stats?filter_path=indices.shards,indices.count,nodes.count

Wenn jeder tägliche Protokollindex viele primäre Shards, aber wenig Daten hat, korrigieren Sie die Indexvorlage für zukünftige Indizes. Ziehen Sie dann Shrink-, Rollover- oder Reindex-Pläne für vorhandene Daten in Betracht.

Eine Praktische Triage-Reihenfolge

Wenn jemand sagt "Elasticsearch ist rot", verwende ich diese Reihenfolge:

  1. Bestätigen Sie den Status mit _cluster/health.
  2. Listen Sie nicht zugewiesene Shards mit _cat/shards auf.
  3. Trennen Sie primäre Fehler von Replikatfehlern.
  4. Führen Sie _cluster/allocation/explain für einen repräsentativen Shard aus.
  5. Überprüfen Sie, ob alle erwarteten Knoten vorhanden sind.
  6. Überprüfen Sie Datenträger-Wasserzeichen und Zuweisungsregeln.
  7. Versuchen Sie bei roten Primärshards, den fehlenden Knoten wiederherzustellen oder aus einem Snapshot wiederherzustellen, bevor Sie eine leere primäre Zuweisung in Betracht ziehen.
  8. Nachdem der Cluster grün geworden ist, finden Sie die Ursache, die ihn ursprünglich ungesund gemacht hat.

Dieser letzte Schritt ist wichtig. Ein Cluster kann grün werden, nachdem Sie Datenträger hinzugefügt, einen Knoten neu gestartet oder Replikate reduziert haben, aber derselbe Vorfall wird zurückkehren, wenn die ILM-Aufbewahrung falsch ist, die Shard-Anzahlen zu hoch sind, Knoten unterdimensioniert sind oder ein Bereitstellungsprozess weiterhin Knotenattribute ändert.

Die Fehlerbehebung des Cluster-Status besteht weniger darin, sich einen magischen Befehl zu merken, sondern darin, sich zu weigern, zu raten. Elasticsearch legt die Zuweisungsentscheidung offen. Lesen Sie sie, überprüfen Sie sie anhand der Knoten- und Indexeinstellungen und wählen Sie die kleinste Lösung, die dem tatsächlichen Blocker entspricht.

Nachdem der Cluster Wieder Grün Ist

Schließen Sie den Vorfall nicht einfach, weil sich die Farbe geändert hat. Grün bedeutet nur, dass Shards jetzt zugewiesen sind. Es beweist nicht, dass der Cluster gesund genug für den nächsten Verkehrsspitze, Datenträgerwachstumszyklus oder Knotenneustart ist. Ich halte es gerne für eine kurze Nachbereitungsnotiz fest, während die Details noch frisch sind: welche Indizes betroffen waren, welche Knoten beteiligt waren, welche Zuweisungsregel die Wiederherstellung blockiert hat und welcher Befehl oder welche Infrastrukturänderung das Problem behoben hat.

Überprüfen Sie, ob die Lösung ein neues Risiko geschaffen hat. Wenn Sie Replikate reduziert haben, um Gelb in Grün zu verwandeln, notieren Sie, dass der Index jetzt weniger Redundanz hat. Wenn Sie Datenträger-Wasserzeichen erhöht haben, fügen Sie eine Erinnerung hinzu, sie nach dem Hinzufügen von Kapazität wieder zu senken. Wenn Sie einen Snapshot wiederhergestellt haben, überprüfen Sie, ob der wiederhergestellte Index die erwarteten Aliase und Schreibeinstellungen hat, bevor Anwendungen normale Schreibvorgänge fortsetzen.

Einige schnelle Überprüfungen helfen, unerledigte Arbeiten zu erkennen:

GET /_cat/recovery?v&active_only=true
GET /_cat/pending_tasks?v
GET /_cat/aliases?v
GET /_cluster/health?wait_for_status=green&timeout=30s

pending_tasks sollte nicht ewig wachsen. Die Wiederherstellung sollte sich schließlich leeren. Aliase sind wichtig, da die Wiederherstellung eines Index unter einem anderen Namen dazu führen kann, dass die Anwendung auf das alte defekte Ziel schreibt oder nur einen Teil der beabsichtigten Daten liest.

Überprüfen Sie auch Schreibsperren nach Datenträgervorfällen:

GET /*/_settings?filter_path=*.settings.index.blocks*

Wenn Elasticsearch eine Flutstufen-Sperre gesetzt hat, entfernen Sie sie erst, nachdem der Datenträgerdruck behoben ist:

PUT /my-index/_settings
{
  "index.blocks.read_only_allow_delete": null
}

Die nützlichste Präventionsarbeit ist normalerweise langweilig: funktionierende Snapshots, getestete Wiederherstellungen, realistische ILM-Aufbewahrung, ausreichend Datenträgerspielraum und Shard-Anzahlen, die der Größe des Clusters entsprechen. Ein Cluster mit zuverlässigen Snapshots und vernünftiger Shard-Größe ist weitaus einfacher wiederherzustellen als ein Cluster mit cleveren Notfallbefehlen und keinem Wiederherstellungspfad.

Was Man Während Gesundheitsvorfällen Nicht Tun Sollte

Starten Sie nicht alle Knoten auf einmal neu. Es ist verlockend, wenn der Cluster ungesund aussieht, aber ein rollierender, beobachteter Ansatz ist sicherer. Das Neustarten gesunder Knoten kann Shard-Kopien entfernen, die Elasticsearch für die Wiederherstellung benötigt. Wenn Sie neu starten müssen, tun Sie dies einen Knoten nach dem anderen und warten Sie zwischen den Schritten auf die Stabilisierung des Clusters.

Deaktivieren Sie nicht die Zuweisung und vergessen Sie es. Vorübergehende Zuweisungsänderungen sind während der Wartung üblich, aber eine vergessene Einstellung kann Replikate lange nach dem Ende des Wartungsfensters nicht zugewiesen lassen. Überprüfen Sie immer sowohl persistente als auch transiente Einstellungen:

GET /_cluster/settings?flat_settings=true&include_defaults=false

Löschen Sie keine Indizes nur basierend auf der Größe. Große Indizes können geschäftskritisch sein. Kleine Indizes können sicher entfernt werden. Binden Sie die Bereinigung an Aufbewahrungsrichtlinien, Snapshots und Anwendungsbesitzer. In einem echten Ausfall ist die schnellste sichere Bereinigung normalerweise das Löschen bekannter abgelaufener Protokoll- oder Metrikindizes, nicht das Raten aus einer sortierten Größentabelle.

Gehen Sie nicht davon aus, dass Kibana und Elasticsearch dieselbe Sprache für das Problem verwenden. Kibana kann einen breiten roten Status anzeigen, während Elasticsearch-APIs den genauen nicht zugewiesenen Shard zeigen. Verwenden Sie die Benutzeroberfläche für die Sichtbarkeit, aber die APIs für die Entscheidung.