Index-Templates und Component-Templates strukturiert einsetzen

1. Welches Problem Index-Templates wirklich loesen

Ein Index-Template ist eine gespeicherte Vorlage, die Settings, Mappings und Aliases automatisch auf jeden neuen Index anwendet, dessen Name zu einem definierten Muster passt. Ohne diese Automatisierung muss jedes Team, das taeglich rotierende Indizes wie logs-app-2026.07.24 anlegt, das Mapping manuell pflegen oder in Applikationscode duplizieren. Sobald ein Feld vergessen oder ein Datentyp falsch gesetzt wird, driften Indizes desselben logischen Datenstroms auseinander, und Aggregationen ueber mehrere Indizes liefern inkonsistente oder fehlerhafte Ergebnisse.

Das zweite Problem, das ein Index-Template loest, ist Wiederverwendbarkeit. In produktiven Clustern gibt es oft Dutzende Indexmuster mit teilweise identischen Basis-Settings wie Replikatanzahl, Refresh-Intervall oder Analyzer-Definitionen. Ohne zentrale Verwaltung wird jede dieser Konfigurationen mehrfach kopiert, und eine spaetere Anpassung, etwa eine geaenderte Shard-Anzahl fuer bessere Performance, muss in jedem einzelnen Template nachgezogen werden. Component-Templates loesen dieses Duplizierungsproblem, indem sie Bausteine definieren, die mehrere Index-Templates gemeinsam referenzieren.

In der Praxis zeigt sich der Wert eines strukturierten Index-Templates vor allem bei Time-Series-Daten: Logging-Pipelines, Metrik-Sammler und E-Commerce-Bestellhistorien erzeugen kontinuierlich neue Indizes. Jeder dieser Indizes muss exakt dasselbe Mapping haben, damit Kibana-Dashboards, Alerting-Regeln und Reporting-Queries ueber Indexgrenzen hinweg funktionieren. Ein zentral gepflegtes Template macht diese Konsistenz zur Systemeigenschaft statt zur manuellen Disziplin einzelner Entwickler.

2. Composable Index-Templates: Aufbau und Syntax

Seit Elasticsearch 7.8 ersetzen composable Index-Templates die alten Legacy-Templates vollstaendig, und OpenSearch folgt derselben API-Struktur. Ein composable Template besteht aus index_patterns, einem optionalen template-Block mit Settings und Mappings sowie einer Liste referenzierter Component-Templates. Die index_patterns unterstuetzen Wildcards wie logs-app-*, sodass jeder neu erzeugte Index mit passendem Namen die Vorlage automatisch erbt, ohne dass eine Anwendung die Mapping-Definition selbst mitschicken muss.

Der entscheidende strukturelle Unterschied zu Legacy-Templates ist, dass composable Index-Templates explizit zwischen der eigenen Definition und referenzierten Component-Templates trennen. Das template-Feld im Index-Template selbst enthaelt nur die Einstellungen, die spezifisch fuer dieses eine Muster gelten, waehrend gemeinsame Bausteine ueber composed_of eingebunden werden. Das folgende Beispiel zeigt ein vollstaendiges Index-Template fuer Applikationslogs mit eigenen Settings und zwei referenzierten Component-Templates.

PUT _index_template/logs-app-template
{
  "index_patterns": ["logs-app-*"],
  "priority": 200,
  "composed_of": ["logs-mappings", "logs-settings"],
  "template": {
    "settings": {
      "number_of_shards": 1,
      "number_of_replicas": 1,
      "index.lifecycle.name": "logs-app-policy"
    }
  },
  "_meta": {
    "description": "Index-Template fuer alle Applikationslogs",
    "owner": "platform-team",
    "managed_by": "terraform"
  }
}

Das Feld _meta wird von Elasticsearch nicht ausgewertet, ist aber fuer die Governance eines Index-Templates unverzichtbar: hier lassen sich Verantwortlichkeiten, Versionsnummern und der Ursprung der Konfiguration dokumentieren, sodass ein Team beim Debugging sofort erkennt, welches System das Template verwaltet und wer bei Aenderungen kontaktiert werden muss.

3. Component-Templates als wiederverwendbare Bausteine

Ein Component-Template enthaelt ausschliesslich Settings oder Mappings, aber niemals eigene index_patterns, denn es wird nie direkt auf einen Index angewendet, sondern immer ueber ein Index-Template referenziert. Diese Trennung erlaubt es, gemeinsame Bausteine wie einen Standard-Analyzer, ein Basis-Mapping fuer Metadatenfelder oder eine Standard-Replikat-Konfiguration einmal zu definieren und in beliebig vielen Index-Templates wiederzuverwenden. Aendert sich die Anforderung, etwa eine zusaetzliche Stopwortliste im Analyzer, genuegt eine einzige Aenderung am Component-Template.

In der Praxis lohnt sich eine klare Trennung zwischen Mapping-Component-Templates und Settings-Component-Templates, weil sich beide unabhaengig voneinander weiterentwickeln. Ein Mapping-Component-Template fuer Log-Daten definiert typischerweise Felder wie @timestamp, log.level und service.name, die in jedem Log-Index vorkommen, waehrend ein separates Settings-Component-Template Shard-Anzahl und Codec-Kompression regelt. Diese Modularitaet reduziert die Groesse jedes einzelnen Component-Templates und macht Reviews bei Aenderungen deutlich uebersichtlicher.

PUT _component_template/logs-mappings
{
  "template": {
    "mappings": {
      "dynamic": "strict",
      "properties": {
        "@timestamp": { "type": "date" },
        "log.level":  { "type": "keyword" },
        "service.name": { "type": "keyword" },
        "message":    { "type": "text", "analyzer": "standard" },
        "trace.id":   { "type": "keyword" }
      }
    }
  },
  "_meta": { "description": "Basis-Mapping fuer alle Log-Indizes" }
}

PUT _component_template/logs-settings
{
  "template": {
    "settings": {
      "index.codec": "best_compression",
      "index.refresh_interval": "30s"
    }
  }
}

Der Parameter "dynamic": "strict" im Mapping-Component-Template ist bewusst gesetzt: Er verhindert, dass unbekannte Felder unkontrolliert das Mapping erweitern, und zwingt jede neue Feldanforderung durch eine explizite Aenderung am Component-Template. Das macht die Mapping-Evolution nachvollziehbar und schuetzt gleichzeitig vor unbeabsichtigter Mapping-Explosion, die bei rein dynamischem Mapping schnell entstehen kann.

4. Priority-Ordering und Template-Aufloesung

Wenn mehrere Index-Templates auf denselben Indexnamen passen koennten, entscheidet ausschliesslich das Feld priority, welches Template gewinnt: Elasticsearch waehlt bei der Indexerstellung genau ein Index-Template mit der hoechsten Priority aus allen passenden Kandidaten aus, es findet keine Mischung mehrerer Index-Templates statt. Das unterscheidet sich fundamental von Component-Templates, deren Inhalte innerhalb eines gewaehlten Index-Templates additiv gemergt werden, in der Reihenfolge, in der sie in composed_of aufgelistet sind.

Eine bewaehrte Konvention ist, generische Templates mit niedriger Priority (etwa 100) fuer breite Muster wie logs-* zu definieren und spezifischere Templates mit hoeherer Priority (etwa 200 oder 300) fuer engere Muster wie logs-app-checkout-*. So erbt ein Checkout-Log-Index automatisch das spezifischere Mapping, waehrend alle anderen Log-Indizes auf das generische Fallback-Template zurueckfallen. Fehlt die priority komplett, wird implizit 0 angenommen, was bei mehreren konkurrierenden Templates schnell zu unvorhersehbarem Verhalten fuehrt.

Innerhalb eines gewaehlten Index-Templates werden die referenzierten Component-Templates in der Reihenfolge ihrer Auflistung gemergt, wobei spaetere Eintraege in composed_of frueh definierte Felder ueberschreiben koennen. Das explizite template-Feld im Index-Template selbst hat dabei immer die hoechste Prioritaet und ueberschreibt Werte aus allen Component-Templates. Diese deterministische Merge-Reihenfolge ist der Grund, warum ein sauber strukturiertes Index-Template vorhersagbares Verhalten garantiert, selbst wenn ein Cluster hunderte Templates verwaltet.

5. Dynamic Templates innerhalb der Mapping-Ebene

Neben Index-Templates, die vor der Indexerstellung greifen, gibt es Dynamic Templates, die innerhalb eines bereits existierenden Mappings definiert werden und regeln, wie neue, bisher unbekannte Felder typisiert werden. Ein Dynamic Template innerhalb eines Index-Templates reagiert auf Namensmuster oder erkannte Werttypen und weist automatisch den passenden Elasticsearch-Datentyp zu, etwa alle Felder mit dem Suffix _ip als ip-Typ statt als generisches text.

Der praktische Nutzen liegt darin, dass ein einzelnes Mapping-Component-Template flexibel auf variable Feldstrukturen reagieren kann, ohne fuer jedes moegliche Feld eine explizite Definition zu benoetigen. Das ist besonders relevant bei Log-Daten mit strukturierten JSON-Payloads, deren genaue Feldmenge sich zwischen Services unterscheidet. Gleichzeitig verhindert die Kombination aus "dynamic": "strict" auf oberster Ebene und gezielten Dynamic Templates fuer bekannte Muster, dass völlig beliebige Felder unkontrolliert ins Mapping gelangen.

PUT _component_template/logs-mappings
{
  "template": {
    "mappings": {
      "dynamic_templates": [
        {
          "ip_fields": {
            "match": "*_ip",
            "mapping": { "type": "ip" }
          }
        },
        {
          "strings_as_keyword": {
            "match_mapping_type": "string",
            "match": "*.id",
            "mapping": { "type": "keyword" }
          }
        }
      ],
      "properties": {
        "@timestamp": { "type": "date" }
      }
    }
  }
}

6. Versionierung und Migration von Templates

Ein oft unterschaetztes Detail bei der Pflege von Index-Templates ist die Versionierung. Sowohl Index-Templates als auch Component-Templates unterstuetzen ein numerisches version-Feld, das nicht in die Mapping-Logik einfliesst, aber als Nachweis genutzt wird, welche Konfiguration aktuell aktiv ist. Automatisierungs-Tools wie Terraform oder eigene Deployment-Skripte pruefen dieses Feld, um festzustellen, ob eine Aktualisierung noetig ist, ohne den vollstaendigen Template-Inhalt vergleichen zu muessen.

Bei Aenderungen an einem bestehenden Component-Template muss beruecksichtigt werden, dass die Aenderung nur fuer neu erstellte Indizes wirksam wird, bestehende Indizes behalten ihr urspruengliches Mapping. Das bedeutet, dass eine Migration in zwei Schritten ablaeuft: zuerst wird das Template aktualisiert, danach muessen bestehende Indizes ueber Reindexing oder ein Rollover in die neue Struktur ueberfuehrt werden. Wer diesen zweiten Schritt vergisst, hat inkonsistente Mappings innerhalb desselben logischen Datenstroms, obwohl das Template korrekt aktualisiert wurde.

7. Templates fuer Time-Series-Daten und Data Streams

Fuer Time-Series-Workloads wie Logs und Metriken bieten Data Streams die konsequente Weiterentwicklung des klassischen Index-Rotationsmusters, und sie setzen zwingend ein Index-Template mit aktiviertem data_stream-Block voraus. Ein Data Stream verwaltet intern mehrere Backing-Indizes, rotiert sie automatisch nach Groesse oder Alter und praesentiert nach aussen einen einzigen logischen Namen fuer Schreib- und Leseoperationen. Das Index-Template, das einen Data Stream steuert, muss zwingend ein @timestamp-Feld vom Typ date im Mapping enthalten.

Der Vorteil gegenueber manueller Index-Rotation mit taeglichen Indexnamen ist, dass Applikationen nie den konkreten Backing-Index kennen muessen, sondern immer gegen den Data-Stream-Namen schreiben. Das Index-Template regelt zentral, wie oft rotiert wird und welches ILM-Policy fuer Rollover und Loeschung zustaendig ist, waehrend Component-Templates weiterhin die Mapping-Bausteine liefern. Diese Kombination macht Time-Series-Indexierung deutlich robuster als selbst gebaute taegliche Index-Skripte.

PUT _index_template/logs-app-datastream
{
  "index_patterns": ["logs-app-*"],
  "data_stream": {},
  "priority": 200,
  "composed_of": ["logs-mappings", "logs-settings"],
  "template": {
    "settings": { "index.lifecycle.name": "logs-app-policy" }
  }
}

8. Testing und Validierung mit der Simulate-API

Bevor ein neues oder geaendertes Index-Template in Produktion geht, sollte es gegen die Simulate-API getestet werden. Der Endpunkt _index_template/_simulate_index/<name> berechnet, welches finale Mapping und welche Settings ein Index mit diesem Namen tatsaechlich erhalten wuerde, ohne den Index wirklich anzulegen. Das deckt Konflikte zwischen konkurrierenden Templates auf, bevor sie in Produktion zu unerwarteten Mappings fuehren.

Ebenso wichtig ist der Endpunkt _index_template/_simulate, mit dem ein noch gar nicht gespeichertes Template-Objekt getestet werden kann, bevor es ueberhaupt per PUT angelegt wird. In CI-Pipelines wird dieser Schritt typischerweise vor jedem Deployment automatisiert ausgefuehrt, sodass ein fehlerhaftes Index-Template nie ungetestet in die Produktionsumgebung gelangt.

# Simulate resolution against an already registered template
curl -s -X POST "https://es.mironsoft.de:9200/_index_template/_simulate_index/logs-app-checkout-2026.07.24" \
  -H "Content-Type: application/json" | jq '.template.mappings'

# Simulate a not-yet-saved template definition before applying it
curl -s -X POST "https://es.mironsoft.de:9200/_index_template/_simulate" \
  -H "Content-Type: application/json" \
  -d @new-template-candidate.json | jq '.template'

9. Governance: Templates in CI/CD-Pipelines

In Teams mit mehreren Entwicklern wird ein manuell per Kibana-Konsole gepflegtes Index-Template schnell zur Fehlerquelle, weil Aenderungen nicht nachvollziehbar sind und niemand die aktuelle Wahrheit kennt. Die bewaehrte Loesung ist, alle Index-Templates und Component-Templates als Code in einem Repository zu versionieren, etwa als Terraform-Ressourcen oder als JSON-Dateien, die ueber ein Deployment-Skript angewendet werden. Jede Aenderung durchlaeuft dann Code-Review, wird gegen die Simulate-API getestet und erst danach per CI-Pipeline auf den Cluster angewendet.

Zur Nachvollziehbarkeit gehoert auch, dass das _meta-Feld jedes Component-Templates den Git-Commit-Hash oder die Pipeline-Run-ID enthaelt, aus der es deployt wurde. Das erlaubt es, bei einem Mapping-Problem in Produktion sofort zurueckzuverfolgen, welche Aenderung die aktuelle Konfiguration erzeugt hat, ohne die Historie manuell in Kibana zu rekonstruieren. Diese Governance-Disziplin skaliert deutlich besser als Ad-hoc-Anpassungen ueber die Konsole, insbesondere wenn mehrere Teams denselben Cluster mit unterschiedlichen Indexmustern teilen.

Ein zusaetzlicher Vorteil dieser Praxis: Der Vergleich zweier Templates, etwa zwischen Staging und Produktion, wird zu einem einfachen Diff zweier JSON-Dateien im Repository statt zu einer muehsamen manuellen Gegenueberstellung ueber die REST-API. Wer Index-Templates konsequent als Code behandelt, reduziert Konfigurationsdrift zwischen Umgebungen fast auf null.

10. Zusammenfassung

Composable Index-Templates und wiederverwendbare Component-Templates loesen das grundlegende Problem der Mapping-Konsistenz ueber Time-Series-Indizes hinweg. Ein Index-Template definiert, welches Muster welche Settings, Mappings und Data-Stream-Konfiguration erhaelt, waehrend Component-Templates die eigentlichen Bausteine liefern und mehrfach wiederverwendet werden koennen. Die Priority-Ordering entscheidet deterministisch, welches Index-Template bei mehreren passenden Kandidaten gewinnt, waehrend referenzierte Component-Templates additiv gemergt werden.

Wer Index-Templates konsequent als Code versioniert, gegen die Simulate-API testet und ueber CI-Pipelines ausrollt, verhindert Konfigurationsdrift zwischen Umgebungen und macht jede Mapping-Aenderung nachvollziehbar. Gerade bei Time-Series-Workloads mit Data Streams ist ein sauberes Template-Setup keine Kuer, sondern Voraussetzung fuer verlaessliche Dashboards, Alerts und Reports ueber alle Backing-Indizes hinweg.

11. FAQ: Index-Templates und Component-Templates