YAML-Anker und Aliase erklärt (mit Kopier-Beispielen)

Wenn Sie jemals dieselben 10 Zeilen YAML an drei verschiedene Stellen in eine Konfigurationsdatei kopiert haben, kennen Sie den Schmerz, den YAML-Anker lösen sollen. Ein Anker lässt Sie einen Wert einmal definieren und von überall im selben Dokument darauf verweisen. Ändern Sie den Wert an einer Stelle, und jede Referenz aktualisiert sich.

Dieser Beitrag erklärt, wie Anker und Aliase funktionieren, wann man sie verwendet, und die Randfälle, die Leute aus der Bahn werfen.

Die grundlegende Syntax

Ein YAML-Anker ist ein Name, den Sie einem Knoten geben:

defaults: &defaults
  retries: 3
  timeout: 30
  log_level: info

&defaults ist der Anker. Er hängt am Wert von defaults, der eine Map ist. Sie können Anker auf jeden Knoten setzen — eine Zeichenkette, eine Zahl, eine Liste, eine Map, eine Sequenz.

Ein Alias ist eine Referenz auf einen Anker:

production:
  <<: *defaults
  region: us-east-1
  replicas: 5

staging:
  <<: *defaults
  region: us-west-2
  replicas: 2

<<: *defaults ist der “Merge-Key”. Er sagt “nimm alles aus dem Anker namens defaults und füge es in diese Map ein.” Das Ergebnis ist dasselbe, als würden Sie den Inhalt von defaults Inline ausschreiben:

production:
  retries: 3
  timeout: 30
  log_level: info
  region: us-east-1
  replicas: 5

Aber wenn Sie retries in defaults ändern, aktualisiert sich jeder Ort, der den Anker verwendet. Das ist der ganze Punkt.

Anker auf einzelnen Werten

Anker müssen nicht in eine Map zusammengeführt werden. Sie können einen einzelnen Anker setzen und darauf verweisen:

api_version: &api "v2.1.0"
services:
  auth:
    version: *api
  billing:
    version: *api
  reports:
    version: *api

Jetzt ist die Änderung der API-Version eine Zeile. Die Referenzen folgen alle.

Sie können auch eine Liste anker:

allowed_origins: &origins
  - https://app.example.com
  - https://admin.example.com
  - https://staging.example.com

cors:
  web: *origins
  api: *origins

Die Liste wird wörtlich wiederverwendet.

Wann Anker helfen

Anker glänzen, wenn Sie gemeinsame Standards über mehrere Instanzen hinweg haben. Kubernetes-Manifeste, docker-compose-Dateien und CI-Matrizen sind voll von diesem Muster.

Ein Hinweis für 2026: Helm und Kustomize dominieren jetzt die Kubernetes-Templating, und sie arbeiten außerhalb des YAML-Anker-Systems — sie generieren YAML, sie parsen es nicht. Wenn Sie Helm oder Kustomize verwenden, brauchen Sie keine Anker (Sie haben stattdessen values.yaml und Patch-Overlays). Anker sind immer noch der richtige Ansatz für reine kubectl apply -f-Workflows, GitHub-Actions-Matrizen, docker-compose-Dateien und jede handverfasste Konfiguration, die nicht durch eine Template-Engine läuft.

Ein Kubernetes-Beispiel — drei Dienste mit denselben Ressourcenlimits:

base_resources: &base_resources
  requests:
    cpu: 100m
    memory: 128Mi
  limits:
    cpu: 500m
    memory: 512Mi

apiDeployment:
  spec:
    template:
      spec:
        containers:
          - name: api
            image: myapp/api:1.2.3
            resources: *base_resources

workerDeployment:
  spec:
    template:
      spec:
        containers:
          - name: worker
            image: myapp/worker:1.2.3
            resources: *base_resources

Ein docker-compose-Beispiel — dieselbe Umgebung für Dev und Prod:

common_env: &common_env
  DATABASE_URL: postgres://db.internal/app
  REDIS_URL: redis://cache.internal:6379
  LOG_LEVEL: info

services:
  api:
    environment:
      <<: *common_env
      ENVIRONMENT: dev
  worker:
    environment:
      <<: *common_env
      ENVIRONMENT: dev

In beiden Fällen ist die Änderung der gemeinsamen Umgebungsvariablen eine Zeile.

Die Fallstricke

Anker sind mächtig, haben aber ein paar scharfe Kanten.

Anker sind lokal für ein Dokument. Eine mehrdokument-YAML-Datei (mit ----Trennern) hat ihren eigenen Geltungsbereich für Anker. Ein Anker, der in Dokument eins definiert ist, kann nicht aus Dokument zwei referenziert werden. Wenn Sie Tools verwenden, die Multi-Doc-YAML erzeugen (wie kubectl get -o yaml mit mehreren Ressourcen), können Sie Anker nicht verwenden, um Werte zwischen ihnen zu teilen.

Anker und Zusammenführungen interagieren auf überraschende Weise mit Überschreibungen. Wenn sowohl der Anker als auch die referenzierende Map denselben Schlüssel definieren, gewinnt der Wert der referenzierenden Map:

defaults: &defaults
  retries: 3
  timeout: 30

production:
  <<: *defaults
  retries: 10  # das gewinnt

Also ist production.retries 10, nicht 3. Das ist das erwartete Verhalten, aber es beißt die Leute, die je nach Reihenfolge “letzter gewinnt” oder “erster gewinnt” erwarten.

Schlüssel in zusammengeführten Maps können nicht entfernt werden. Wenn defaults einen Schlüssel legacy_setting: true hat und Sie den in production “entfernen” wollen, geht das nicht. Zusammenführung fügt nur Schlüssel hinzu; sie entfernt nie welche. Workaround: Nehmen Sie den Schlüssel nicht in den Anker auf.

Anker können nicht auf sich selbst verweisen. Ein selbstreferenzierender Anker erzeugt einen Zyklus. Die meisten Parser erkennen das und werfen einen Fehler. Wenn Sie jemals einen “rekursiven Anker”-Fehler bekommen, suchen Sie nach einem Alias, der auf den Anker zurückweist, der ihn enthält.

Anker und JSON vertragen sich nicht. JSON hat kein Konzept von Ankern. Wenn Sie YAML mit Ankern in JSON konvertieren, werden die Anker expandiert (JSON wird größer) oder fallen gelassen (JSON wird kleiner). In beiden Fällen ist das Ergebnis größer als das YAML. Wenn Sie eine JSON-Version brauchen, brauchen Sie normalerweise eine andere Konfigurationsquelle.

Manche Linters beschweren sich über Anker. yamllint deaktiviert aus Stilgründen standardmäßig Anker (anchors: disable). Wenn Sie Anker verwenden, müssen Sie entweder Ihren Linter konfigurieren oder die Warnungen akzeptieren. Die meisten Teams, die Anker verwenden, halten sie für den Lint-Aufwand wert.

Anker funktionieren auf dem geparsten Objekt-Graphen, nicht auf dem Text. Wenn Sie Schlüssel alphabetisch mit einem Tool wie yq sortieren und dann neu serialisieren, werden Anker per Referenz beibehalten, nicht nach der sichtbaren Schlüsselreihenfolge. Die Ausgabe ist immer noch korrekt, aber es visuell überraschend — der Anker taucht an einer Stelle auf, der Alias an einer anderen, und sie verweisen auf dasselbe Objekt.

Anker in Ihrer Konfiguration überprüfen

Der schnellste Weg zu prüfen, ob Ihre Anker funktionieren, ist, die YAML in einem Parser zu laden, der sie auflöst, und das Ergebnis auszugeben. Der YAML-Validator auf DevSpeedTools zeigt den aufgelösten Objekt-Graphen an — wenn Ihre Anker richtig verdrahtet sind, sehen Sie überall dieselben Werte.

Für eine aufwendigere Inspektion sagt Ihnen das YAML-Statistik-Tool die Gesamtanzahl der einzigartigen vs. duplizierten Schlüssel, was ein guter Indikator dafür ist, ob Ihre Anker überhaupt etwas deduplizieren.

Für eine interaktive Editor-Erfahrung löst VS Code mit der Red Hat YAML-Erweiterung Anker beim Überfahren auf und zeigt Ihnen, wohin jeder Alias zeigt.

Die Zusammenfassung

Anker sind YAMLS Version einer Variablen. Sie arbeiten zur Parse-Zeit, nicht zur Serialisierungs-Zeit, also enthält die Datei, die Sie schreiben, den Anker einmal und die Referenzen an vielen Stellen. Der Parser expandiert sie auf denselben Wert.

Verwenden Sie sie für gemeinsame Standards. Versuchen Sie nicht, Zustand über Dokumente hinweg zu teilen. Erwarten Sie nicht, dass JSON-Konvertierung sie erhält. Und im Zweifel: Führen Sie die Datei durch einen Validator, um zu bestätigen, dass die Expansion Ihrem Willen entspricht — Anker, die still und leise den falschen Wert erzeugen, sind die Art von Bug, der in Produktion geht und dort ein Jahr lebt.