Si alguna vez has copiado y pegado las mismas 10 líneas de YAML en tres lugares diferentes de un archivo de configuración, has sentido el dolor que las anclas de YAML están diseñadas para resolver. Una ancla te permite definir un valor una vez y referenciarlo desde cualquier lugar del mismo documento. Cambia el valor en un lugar, y cada referencia se actualiza.
Esta publicación recorre cómo funcionan las anclas y los alias, cuándo usarlos y los casos límite que atrapan a la gente.
La sintaxis básica
Una ancla de YAML es un nombre que le das a un nodo:
defaults: &defaults
retries: 3
timeout: 30
log_level: infoEl &defaults es la ancla. Se adjunta al valor de defaults, que es un mapa. Puedes poner anclas en cualquier nodo — una cadena, un número, una lista, un mapa, una secuencia.
Un alias es una referencia a una ancla:
production:
<<: *defaults
region: us-east-1
replicas: 5
staging:
<<: *defaults
region: us-west-2
replicas: 2El <<: *defaults es la “clave de fusión”. Dice “toma todo de la ancla llamada defaults y fúselo en este mapa.” El resultado es el mismo que si hubieras escrito el contenido de defaults en línea:
production:
retries: 3
timeout: 30
log_level: info
region: us-east-1
replicas: 5Pero si cambias retries en defaults, cada lugar que usa la ancla se actualiza. Ese es todo el punto.
Anclas en valores individuales
Las anclas no tienen que fusionarse en un mapa. Puedes anclar un valor individual y referenciarlo:
api_version: &api "v2.1.0"
services:
auth:
version: *api
billing:
version: *api
reports:
version: *apiAhora cambiar la versión de la API es un cambio de una línea. Las referencias todas siguen.
También puedes anclar una lista:
allowed_origins: &origins
- https://app.example.com
- https://admin.example.com
- https://staging.example.com
cors:
web: *origins
api: *originsLa lista se reutiliza textualmente.
Cuándo ayudan las anclas
Las anclas brillan cuando tienes valores predeterminados compartidos entre múltiples instancias. Los manifiestos de Kubernetes, los archivos docker-compose y las matrices de CI están llenos de este patrón.
Una nota para 2026: Helm y Kustomize dominan la plantillización de Kubernetes ahora, y operan fuera del sistema de anclas de YAML — generan YAML, no lo analizan. Si estás en Helm o Kustomize, no necesitas anclas (tienes values.yaml y parches de superposición en su lugar). Las anclas todavía son la decisión correcta para flujos de trabajo simples de kubectl apply -f, matrices de GitHub Actions, archivos docker-compose y cualquier configuración escrita a mano que no pase por un motor de plantillas.
Un ejemplo de Kubernetes — tres servicios con los mismos límites de recursos:
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_resourcesUn ejemplo de docker-compose — mismo entorno para desarrollo y producción:
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: devEn ambos casos, cambiar el entorno común es un cambio de una línea.
Las trampas
Las anclas son poderosas pero tienen algunos bordes filosos.
Las anclas son locales a un documento. Un archivo YAML multi-documento (con separadores ---) tiene su propio ámbito para anclas. Una ancla definida en el documento uno no puede ser referenciada desde el documento dos. Si estás usando herramientas que producen YAML multi-doc (como kubectl get -o yaml con múltiples recursos), no puedes usar anclas para compartir valores entre ellos.
Las anclas y la fusión interactúan con las sobrescrituras de formas sorprendentes. Si tanto la ancla como el mapa que referencia definen la misma clave, el valor del mapa que referencia gana:
defaults: &defaults
retries: 3
timeout: 30
production:
<<: *defaults
retries: 10 # this winsEntonces production.retries es 10, no 3. Ese es el comportamiento esperado, pero afecta a la gente que espera “el último gana” o “el primero gana” dependiendo del orden.
Las claves en mapas fusionados no se pueden eliminar. Si defaults tiene una clave legacy_setting: true y quieres “desactivarla” en production, no puedes. La fusión solo agrega claves; nunca las elimina. Solución alternativa: no incluyas la clave en la ancla.
Las anclas no pueden referenciarse a sí mismas. Una ancla autorreferencial crea un ciclo. La mayoría de los analizadores detectan esto y lanzan un error. Si alguna vez obtienes un error de “ancla recursiva”, busca un alias que apunte de vuelta a la ancla que lo contiene.
Las anclas y JSON no se mezclan. JSON no tiene concepto de anclas. Si conviertes YAML a JSON con anclas, las anclas se expanden (el JSON se hace más grande) o se eliminan (el JSON se hace más pequeño). En cualquier caso, el resultado es más grande que el YAML. Si necesitas una versión JSON, generalmente necesitas una fuente de configuración diferente.
Algunos linters se quejan de las anclas. yamllint por defecto deshabilita las anclas (anchors: disable) por razones de estilo. Si estás usando anclas, necesitarás o configurar tu linter o aceptar las advertencias. La mayoría de los equipos que usan anclas consideran que vale la pena la fricción del lint.
Las anclas funcionan en el grafo de objetos analizado, no en el texto. Si ordenas las claves alfabéticamente con una herramienta como yq y luego re-serializas, las anclas se preservan por referencia, no por el orden visible de las claves. La salida sigue siendo correcta, pero puede ser visualmente sorprendente — la ancla aparece en un lugar, el alias en otro, y ambos se refieren al mismo objeto.
Verificando anclas en tu configuración
La forma más rápida de verificar que tus anclas están funcionando es cargar el YAML en un analizador que las resuelva e imprimir el resultado. El validador YAML de DevSpeedTools muestra el grafo de objetos resuelto — si tus anclas están conectadas correctamente, verás los mismos valores en todas partes.
Para una inspección más detallada, la herramienta de estadísticas YAML te dice el número total de claves únicas vs. duplicadas, lo cual es un buen indicador de “¿mis anclas realmente están eliminando duplicados?”
Para una experiencia de editor interactivo, VS Code con la extensión YAML de Red Hat resolverá las anclas al pasar el cursor y te mostrará a dónde apunta cada alias.
El resumen
Las anclas son la versión de YAML de una variable. Funcionan en el momento del análisis, no en el de la serialización, por lo que el archivo que escribes contiene la ancla una vez y las referencias en muchos lugares. El analizador las expande al mismo valor.
Úsalas para valores predeterminados compartidos. No intentes usarlas para compartir estado entre documentos. No esperes que la conversión a JSON las preserve. Y en caso de duda, ejecuta el archivo a través de un validador para confirmar que la expansión coincide con tu intención — anclas que silenciosamente producen el valor equivocado son el tipo de error que llega a producción y vive allí durante un año.