Reuse YAML Configuration Blocks with Anchors and Merge Keys

Repeating the same block in every service

If you maintain a Docker Compose file, Kubernetes manifest, or CI/CD pipeline definition, you have probably copied the same environment variables, image pull policy, or resource limits into half a dozen places. Change one value, and you must hunt down every duplicate. YAML offers a built-in way to define a fragment once and reuse it: anchors and aliases.

An anchor marks a node with a name using the & symbol. An alias pulls that node back in using *. The merge key << lets you fold an anchored mapping into another mapping without replacing existing keys.

Worked example: shared service defaults

Imagine two services that share an image, port mapping, and logging configuration, but need different overrides.

# docker-compose.yml
service_template: &service_template
  image: myapp:latest
  ports:
    - "8080:80"
  environment:
    DEBUG: "false"
    LOG_LEVEL: "info"

web:
  <<: *service_template
  environment:
    DEBUG: "true"

worker:
  <<: *service_template
  command: ["worker", "--queue", "high"]

Here, &service_template defines the reusable block. The <<: *service_template line copies every key from that block into web and worker. The web service then overrides DEBUG to true, while worker adds a command without touching the shared defaults.

Verify the merged result

Run this in your terminal to load the file and inspect the parsed structure. No special permissions are required; you only need read access to the file.

python -c "import yaml, pprint; data = yaml.safe_load(open('example.yaml')); pprint.pprint(data)"

Placeholder: replace example.yaml with the path to your file. Expected check: the web and worker dictionaries should contain image, ports, and environment from the template, with web showing DEBUG: 'true'. Risk: none; this is a read-only inspection.

Limitations to keep in mind

• Document-scoped only: Anchors and aliases cannot cross separate YAML files. If you define &template in base.yml, you cannot use *template in override.yml without an external preprocessor that combines the documents first.
• Merge key support varies: The << merge key is part of the YAML 1.1 type resolution scheme and common in many parsers, but strict YAML 1.2 parsers may not support it. Test your target library before relying on it in production.
• Readability cost: Heavy use of anchors can hide where a value actually comes from, especially in large files. Use them for genuine duplication, not for every minor similarity.

Practical closing

Start by identifying one repeated block in your largest YAML file. Extract it into an anchor at the top of the document, replace the duplicates with aliases and merge keys, then reload the file with your application's YAML parser to confirm the values inherited correctly. If you need the same block across multiple files, look into a composition tool or a preprocessor rather than trying to stretch YAML anchors beyond a single document.