Anchors y Aliases en YAML: Patrones de Configuración DRY

Repetir la misma configuración en múltiples secciones de un archivo YAML viola el principio DRY (Don't Repeat Yourself) y crea dolores de cabeza de mantenimiento. Los anchors y aliases de YAML resuelven esto permitiéndote definir un valor una vez y referenciarlo múltiples veces.

Sintaxis Básica

Anchor (&): Marca un valor para reutilización Alias (*): Referencia un valor anclado

# Define an anchor
defaults: &default_settings
  timeout: 30
  retries: 3
  log_level: info

# Use aliases to reference it
development:
  <<: *default_settings
  log_level: debug

production:
  <<: *default_settings
  retries: 5

La clave de fusión << incorpora todos los pares clave-valor del anchor referenciado. Las propiedades definidas después de la fusión sobreescriben los valores anclados.

Resultado después de la resolución:

development:
  timeout: 30
  retries: 3
  log_level: debug  # overridden

production:
  timeout: 30
  retries: 5        # overridden
  log_level: info

Tipos de Anchor

Anchors Escalares

Reutiliza un solo valor:

max_connections: &max_conn 100

database:
  pool_size: *max_conn
cache:
  pool_size: *max_conn

Anchors de Secuencia

Reutiliza listas completas:

common_ports: &ports
  - 80
  - 443

web_server:
  ports: *ports
load_balancer:
  ports: *ports

Anchors de Mapeo

Reutiliza objetos completos (el patrón más común):

logging: &log_config
  driver: json-file
  options:
    max-size: "10m"
    max-file: "3"

services:
  api:
    logging: *log_config
  worker:
    logging: *log_config

La Clave de Fusión (<<)

La clave de fusión tiene un comportamiento específico:

1. Copia todos los pares clave-valor del mapeo referenciado
2. Las claves establecidas explícitamente tienen prioridad sobre las claves fusionadas
3. Múltiples fusiones se procesan en orden (el primero gana en conflictos)

# Multiple merges
base: &base
  a: 1
  b: 2

extra: &extra
  b: 3
  c: 4

combined:
  <<: [*base, *extra]
  # Result: a=1, b=2 (base wins), c=4

Ejemplos del Mundo Real

Docker Compose

x-common: &common
  restart: unless-stopped
  networks:
    - app-network
  logging:
    driver: json-file
    options:
      max-size: "10m"

services:
  api:
    <<: *common
    image: myapp/api:latest
    ports:
      - "8080:8080"
    environment:
      DATABASE_URL: postgres://db:5432/myapp

  worker:
    <<: *common
    image: myapp/worker:latest
    environment:
      QUEUE_URL: redis://cache:6379

  scheduler:
    <<: *common
    image: myapp/scheduler:latest

Docker Compose usa la convención de prefijo x- para campos de extensión que contienen anchors. Consulta nuestra guía YAML para Docker Compose para más patrones.

GitHub Actions

jobs:
  test:
    runs-on: ubuntu-latest
    env: &common_env
      NODE_VERSION: '20'
      CI: true
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: ${{ env.NODE_VERSION }}
      - run: npm test

  build:
    runs-on: ubuntu-latest
    needs: test
    env:
      <<: *common_env
      BUILD_TARGET: production
    steps:
      - uses: actions/checkout@v4
      - run: npm run build

Kubernetes

apiVersion: apps/v1
kind: Deployment
spec:
  template:
    spec:
      containers:
        - name: app
          resources: &resources
            requests:
              cpu: 100m
              memory: 128Mi
            limits:
              cpu: 500m
              memory: 512Mi
        - name: sidecar
          resources: *resources  # Same resource limits

Limitaciones y Errores Comunes

1. Sin Referencias Entre Archivos

Los anchors solo funcionan dentro de un único archivo YAML. No puedes referenciar un anchor definido en otro archivo. Para reutilización entre archivos, usa herramientas de plantillas como Helm, Jsonnet o Kustomize.

2. Sin Sobreescrituras Parciales en Secuencias

No puedes fusionar y sobreescribir parcialmente una lista — reemplazas la lista completa:

base_ports: &ports
  - 80
  - 443

service:
  ports: *ports  # You get exactly [80, 443]
  # Cannot add port 8080 to this list via merge

Solución alternativa: Define la lista extendida por separado.

3. El Orden Importa

Los anchors deben definirse antes de ser referenciados:

# WRONG - alias before anchor
service:
  settings: *defaults

defaults: &defaults
  timeout: 30

# CORRECT - anchor before alias
defaults: &defaults
  timeout: 30

service:
  settings: *defaults

4. No Todas las Herramientas Soportan Claves de Fusión

La clave de fusión << no es parte de la especificación principal de YAML — es una extensión específica de tipo. La mayoría de los parsers YAML populares la soportan, pero algunos parsers estrictos pueden no hacerlo.

Valida el uso de anchors en tu YAML con nuestro Validador YAML.

FAQ

¿Se preservan los anchors al convertir YAML a JSON?

No. Cuando se parsea YAML, los anchors y aliases se resuelven en sus valores. El JSON resultante tendrá los valores expandidos en línea. Esto significa que convertir a JSON y de vuelta perderá la estructura DRY. Los anchors existen solo en el formato fuente YAML.

¿Puedo usar anchors con sobreescrituras anidadas complejas?

La clave de fusión (<<) solo realiza una fusión superficial — copia las claves de nivel superior del mapeo anclado. Los objetos anidados se reemplazan completamente, no se fusionan en profundidad. Para comportamiento de fusión profunda, necesitas una solución específica de la herramienta (función merge de Helm, procesadores YAML personalizados).

Recursos Relacionados

• Validador YAML — Valida YAML con anchors y aliases
• Tutorial de Sintaxis YAML — Fundamentos de YAML
• YAML para Docker Compose — Patrones específicos de Docker