Reusing YAML Configuration with Anchors, Aliases, and Merge Keys

Problem and takeaway

Configuration files often repeat the same block—resource limits, labels, or default environment variables—across multiple services or environments. Copying those blocks creates drift: a change in one place is easy to forget elsewhere.

YAML provides anchors (&), aliases (*), and a merge key (<<) to define a node once and reuse it. The useful takeaway: use anchors for shared defaults, but treat the merged result as a static copy, not a live link, and verify that your parser supports the merge key before relying on it.

How anchors and aliases work

An anchor labels a YAML node so it can be referenced later. An alias inserts that node again. In most parsers the inserted scalar value is a copy, but mappings and sequences may remain references to the same underlying structure depending on the loader.

Worked configuration example

This example uses a deployment-style file with two services that share CPU, memory, and replica defaults.

defaults: &defaults
  replicas: 3
  resources:
    cpu: 250m
    memory: 256Mi

services:
  api:
    <<: *defaults
    name: api
    image: example/api:1.2
    replicas: 5

  worker:
    <<: *defaults
    name: worker
    image: example/worker:1.2

The anchor &defaults stores the mapping once. The token *defaults aliases it, and << merges those keys into the service mapping. Keys defined directly in api or worker override the merged defaults—notice api sets replicas: 5 instead of the anchored 3.

Version assumption: YAML 1.1 versus 1.2

The merge key << is a YAML 1.1 convention supported by many parsers, including PyYAML, but it is not part of the YAML 1.2 core specification. If your toolchain parses YAML as 1.2, << may be treated as an ordinary key or rejected. Check your parser documentation before using merge keys in infrastructure-as-code files.

Verification commands

Run the following from the directory containing your YAML file. No special permissions are required.

python3 - <<'PY'
import yaml
from pathlib import Path

path = Path("config.yaml")
data = yaml.safe_load(path.read_text())

print(data["services"]["api"])
print(data["services"]["worker"])
PY

Expected check: both services show resources and the anchored replicas: 3 unless overridden. api should show replicas: 5.

Optionally lint indentation and anchor syntax:

yamllint config.yaml

Expected check: no warnings about tabs or inconsistent indentation. YAML forbids tabs for indentation; use spaces only.

Limits and common mistakes

• Aliases are not always independent copies. If your application mutates a loaded mapping in memory, a shared alias can cause changes to appear in multiple places. Test by modifying one merged field and confirming other services retain the anchored default.
• Merge order is not commutative. Keys listed after <<: *defaults override merged keys. Keys listed before may be overridden by the merge, depending on the parser.
• Anchor names collide in large files. Reusing the same anchor name unintentionally can shadow or conflict with the first definition, depending on the parser.
• Strict loaders may reject aliases. Some security-focused configurations disable aliases to mitigate denial-of-service attacks such as "billion laughs." If your loader rejects the file, flatten the duplication or use a templating tool instead.
• Tabs are forbidden. Indentation must use spaces. A single tab breaks parsing.

Practical check after editing

Reload the file with yaml.safe_load and compare the resulting dictionary against your expected values. If you use Git, inspect the diff to confirm only the intended blocks changed and that no anchor was accidentally removed.

If the file was edited in place and causes failures, revert it from version control:

git checkout -- config.yaml

This restores the previous committed state. No rollback is needed for read-only verification.

When not to use anchors

Avoid anchors when the configuration is consumed by multiple tools with unknown parser support, when the file is edited by people unfamiliar with YAML merge semantics, or when you need independent deep copies that must diverge after loading. In those cases, explicit repetition or a generation tool such as Jsonnet, Helm, or Kustomize is clearer.