Wazuh Indexer im Single-Node dauerhaft „yellow“: Replica-Shards, Index-Templates und .sst-Wachstum sauber beheben

von

Einleitung

Ein dauerhaft gelber Cluster-Status im Wazuh Indexer wirkt auf den ersten Blick wie ein „Kosmetikproblem“. In Single-Node-Installationen ist „yellow“ aber fast immer ein Symptom unpassender Replica-Konfigurationen – und kann reale Nebenwirkungen haben: blockierte Shard-Allokationen, verzögerte/ausbleibende Index-Aktualisierung und wachsender Plattenverbrauch durch shardbezogene Daten im Indexer-Datenpfad. Genau dieses Muster tritt häufig bei systemnahen Indizes wie .opendistro-* oder .opensearch-* sowie bei zeitbasierten Wazuh-Indizes auf.

Ausgangslage / Problemstellung

Symptome:

  • Wazuh Indexer (Single-Node, alle Komponenten auf einer VM) bleibt permanent in yellow.
  • Ursache ist ein oder mehrere Indizes mit number_of_replicas: 1 (Replica-Shards können auf einem einzelnen Node nicht zugewiesen werden).
  • ILM/ISM-Ansätze greifen nicht wie erwartet, weil täglich neue Indizes entstehen (Namensmuster je Datum).
  • Im Datenpfad des Indexers (hier: wazuh-vulnerabilities) sammeln sich .sst-Dateien an und belegen zunehmend Speicher; gleichzeitig wirken Vulnerability-Daten „stale“ bzw. Updates bleiben hinterher.

Umgebung:

  • Standalone Wazuh: Manager, Indexer und Dashboard auf einer VM / einem Indexer-Node.
  • Betroffen sind vor allem system-/pluginbezogene Indizes (.opendistro-*, teils .opensearch-*) und je nach Setup auch Wazuh-Zeitindizes (Alerts/Archives).

Technische Analyse

Warum „yellow“ bei Single-Node fast immer Replica-bedingt ist

OpenSearch (und damit der Wazuh Indexer) markiert den Cluster als yellow, wenn Primär-Shards zugewiesen sind, aber Replica-Shards unassigned bleiben. In einem Single-Node-Cluster ist das der Normalfall, sobald irgendein Index number_of_replicas >= 1 hat: Es gibt keinen zweiten Node, auf den repliziert werden könnte. Das Verhalten ist erwartbar und wird auch in Troubleshooting-Guides als Standardursache genannt.

Warum „manuelles Setzen“ nicht dauerhaft hält

Das Setzen von index.number_of_replicas und index.auto_expand_replicas über die API ist eine dynamische Index-Einstellung. Sie wird auf existierende Indizes angewendet, aber neu erstellte Indizes übernehmen ihre Startwerte aus Index-Templates (und ggf. aus system-/pluginseitigen Default-Templates). Wenn Templates (oder Plugin-Mechanismen) Replica-Werte definieren, „gewinnen“ diese bei jeder Neuerstellung – z. B. nach Upgrades, Re-Creations oder bei täglich rollierenden Indizes.
OpenSearch dokumentiert explizit, dass bei mehreren Templates das Template mit der höchsten Priorität die Settings/Mappings bestimmt.

Was hat das mit .sst-Dateien und Storage zu tun?

.sst-Dateien sind typischerweise Segment-/Storage-Artefakte von Storage-Engines (häufig LSM-basiert). Im Indexer-Kontext wachsen Datenpfade vor allem dann überraschend, wenn:

  • Shards nicht sauber alloziert/umgezogen werden können (unassigned Replica),
  • Indizes nicht wie vorgesehen weitergeschrieben/rotiert/aufgeräumt werden,
  • Lifecycle-Mechanismen (ISM/ILM) nicht greifen, weil neue Indizes mit falschen Defaults starten oder Policies nicht korrekt matchen.

Wichtig dabei: Niemals Dateien im Indexer-Datenverzeichnis manuell löschen, auch wenn sie „alt“ wirken – Cleanup muss über Index-APIs (Index löschen, Policy anwenden, Retention korrekt konfigurieren) erfolgen, sonst drohen Indexkorruption und Datenverlust.

Lösung / Best Practices

Ziel ist eine zweistufige Reparatur:

  1. Ist-Zustand korrigieren (existierende Indizes reparieren → Cluster wird grün)
  2. Zukunft absichern (Templates so setzen, dass neue Indizes automatisch replicas=0 bekommen)

1) Existierende System-Indizes auf 0 Replicas setzen

Die schnellste Stabilisierung ist das Update der betroffenen Indexmuster via Update-Settings-API. Diese API ist dafür vorgesehen und kann dynamische Index-Settings zur Laufzeit ändern.

Beispiel (Zertifikatsauth direkt auf dem Indexer-Node), um alle .opendistro-*-Indizes zu korrigieren und auto_expand_replicas auszuschalten:

curl --cacert /etc/wazuh-indexer/certs/root-ca.pem \
     --cert   /etc/wazuh-indexer/certs/admin.pem \
     --key    /etc/wazuh-indexer/certs/admin-key.pem \
     -XPUT "https://127.0.0.1:9200/.opendistro-*/_settings" \
     -H 'Content-Type: application/json' \
     -d '{
           "index": {
             "number_of_replicas": 0,
             "auto_expand_replicas": false
           }
         }'

Optional (aber in der Praxis oft sinnvoll), wenn auch .opensearch-* Indizes Replicas haben:

curl --cacert /etc/wazuh-indexer/certs/root-ca.pem \
     --cert   /etc/wazuh-indexer/certs/admin.pem \
     --key    /etc/wazuh-indexer/certs/admin-key.pem \
     -XPUT "https://127.0.0.1:9200/.opensearch-*/_settings" \
     -H 'Content-Type: application/json' \
     -d '{
           "index": {
             "number_of_replicas": 0,
             "auto_expand_replicas": false
           }
         }'

Warum Zertifikatsauth?
In Wazuh-Setups ist der Zugriff aus Dashboard/DevTools häufig durch RBAC eingeschränkt. Ein Request vom Indexer selbst mit Admin-Zertifikat umgeht typische Rollen-/Tenant-Fallen, wenn die Rechte nicht sauber delegiert sind.

Validierung nach dem Fix:

  • Cluster-Status: GET /_cluster/health?pretty
  • Unassigned Shards: GET /_cat/shards?v
  • Einstellungen prüfen: GET /.opendistro-*/_settings?filter_path=*.settings.index.number_of_replicas,*.settings.index.auto_expand_replicas

2) Nachhaltig: Index-Templates für neue Indizes korrekt setzen

Damit du das nicht nach jedem Upgrade oder nach Index-Neuerstellung wiederholen musst, brauchst du einen Mechanismus, der bei Index-Creation greift. Das ist der Job von Index-Templates. OpenSearch beschreibt klar, dass bei mehreren Templates die höchste Priorität bestimmt, was beim Anlegen eines Index übernommen wird.

Vorgehen in der Praxis:

  1. Vorhandene Templates anzeigen:
    • GET /_index_template (Composable Templates)
    • ggf. zusätzlich Legacy: GET /_template
  2. Prüfen, welche Templates auf .opendistro-*, .opensearch-* und ggf. wazuh-* matchen.
  3. Ein eigenes Composable Template mit höherer Priority erstellen, das für dein Single-Node-Setup replicas: 0 und auto_expand_replicas: false setzt.

Beispiel für ein Composable Template (bewusst nur Settings, keine Mappings), das .opendistro-* abdeckt:

curl --cacert /etc/wazuh-indexer/certs/root-ca.pem \
     --cert   /etc/wazuh-indexer/certs/admin.pem \
     --key    /etc/wazuh-indexer/certs/admin-key.pem \
     -XPUT "https://127.0.0.1:9200/_index_template/single-node-system-indices" \
     -H 'Content-Type: application/json' \
     -d '{
           "index_patterns": [".opendistro-*", ".opensearch-*"],
           "priority": 500,
           "template": {
             "settings": {
               "number_of_replicas": 0,
               "auto_expand_replicas": false
             }
           }
         }'

Hinweise:

  • Die konkrete priority muss nur höher sein als konkurrierende Templates.
  • Für Wazuh-Datenindizes (z. B. wazuh-alerts-*, wazuh-archives-*) solltest du vorsichtig sein: Wazuh bringt eigene Templates/Mappings mit. Wenn du dort eingreifst, dann idealerweise nur Settings ergänzen und die Wazuh-Mappings nicht überschreiben. Wazuh dokumentiert das Thema „Index patterns“ und das Anpassen/Erweitern der Standardmuster.

3) Upgrade-Fall: Warum das Problem nach Updates wieder auftaucht

Nach manchen Upgrades oder Index-Rekreationen werden systemnahe Indizes neu erstellt. Dann greifen wieder Default-Templates/Plugin-Defaults, und Replicas stehen plötzlich wieder auf 1. Dieses Verhalten ist auch außerhalb von Wazuh in OpenSearch-Umgebungen ein bekannter Klassiker (z. B. .opendistro-job-scheduler-lock).

Betriebssichere Absicherung:

  • Template-Lösung (oben) ist die sauberste Variante.
  • Zusätzlich kann ein „Post-Upgrade“-Runbook helfen: Nach Update einmal /_cluster/health, /_cat/indices, Settings-Checks und ggf. Korrektur-Calls ausführen (automatisierbar via Script + systemd timer/cron).

Lessons Learned / Best Practices

  • Single-Node = Replicas 0: Für produktive Single-Node-Systeme ist number_of_replicas: 0 für alle relevanten Indizes die Normalform. Yellow ist hier fast nie „harmlos“, sondern ein Wartungs-Signal.
  • auto_expand_replicas bewusst deaktivieren: Sonst können sich Replicas bei Änderungen der Node-Anzahl oder durch Defaults wieder einschalten; OpenSearch erklärt die Logik und Parameter dieses Settings.
  • Dynamische Settings sind keine Template-Strategie: PUT /<index>/_settings stabilisiert den Ist-Zustand, verhindert aber nicht, dass neue Tagesindizes wieder mit Replica=1 entstehen.
  • Templates mit Prioritäten verstehen: In OpenSearch setzen sich Templates mit höherer Priority durch. Das ist der Hebel, um „täglich neu entstehende“ Indizes automatisch korrekt zu initialisieren.
  • Kein manuelles Löschen im Datenverzeichnis: Storage-Probleme müssen über Retention (Index löschen), Policy-Steuerung (ISM) und korrekte Shard-Zuweisung gelöst werden – nicht per Dateisystem-Operation.

Fazit

Ein gelber Wazuh-Indexer-Cluster in einer Single-Node-VM ist in der Praxis fast immer eine Replica-Frage: Unassigned Replica-Shards halten den Status dauerhaft auf yellow und können Folgeprobleme wie verzögerte Indexpflege und Storage-Wachstum verstärken. Die robuste Lösung besteht aus (1) sofortiger Korrektur bestehender .opendistro-*/.opensearch-*-Indizes via Update-Settings-API und (2) einer dauerhaften Template-Strategie mit ausreichender Priority, damit neue Indizes automatisch mit replicas=0 und deaktiviertem auto_expand_replicas starten.

Mehr zu Wazuh …
https://wazuh.com/?utm_source=ambassadors&utm_medium=referral&utm_campaign=ambassadors+program

Mehr zum Wazuh Ambassador Program …
https://wazuh.com/ambassadors-program/?utm_source=ambassadors&utm_medium=referral&utm_campaign=ambassadors+program

https://wazuh.slack.com/archives/C07BZJY86G3/p1771112784921359