Âncoras e aliases de YAML explicados (com exemplos para copiar)

Se você já copiou e colou as mesmas 10 linhas de YAML em três lugares diferentes em um arquivo de configuração, você sentiu a dor que as âncoras de YAML são projetadas para resolver. Uma âncora permite que você defina um valor uma vez e o referencie de qualquer lugar no mesmo documento. Altere o valor em um lugar, e toda referência é atualizada.

Este post percorre como âncoras e aliases funcionam, quando usá-los e os edge cases que pegam as pessoas.

A sintaxe básica

Uma âncora de YAML é um nome que você dá a um nó:

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

O &defaults é a âncora. Ela se anexa ao valor de defaults, que é um map. Você pode colocar âncoras em qualquer nó — uma string, um número, uma lista, um map, uma sequência.

Um alias é uma referência a uma âncora:

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

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

O <<: *defaults é a “chave de merge”. Ele diz “pegue tudo da âncora chamada defaults e mescle neste map.” O resultado é o mesmo que se você tivesse escrito o conteúdo de defaults inline:

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

Mas se você alterar retries em defaults, todo lugar que usa a âncora é atualizado. Esse é todo o ponto.

Âncoras em valores únicos

Âncoras não precisam ser mescladas em um map. Você pode ancorar um valor único e referenciá-lo:

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

Agora alterar a versão da API é uma mudança de uma linha. As referências todas seguem.

Você também pode ancorar uma lista:

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

cors:
  web: *origins
  api: *origins

A lista é reutilizada textualmente.

Quando âncoras ajudam

Âncoras brilham quando você tem padrões compartilhados entre múltiplas instâncias. Manifestos de Kubernetes, arquivos docker-compose e matrizes de CI são repletos desse padrão.

Uma nota para 2026: Helm e Kustomize dominam a criação de templates no Kubernetes agora, e eles operam fora do sistema de âncoras do YAML — eles geram YAML, não o analisam. Se você está usando Helm ou Kustomize, não precisa de âncoras (você tem values.yaml e overlays de patch no lugar). Âncoras ainda são a escolha certa para workflows de kubectl apply -f puro, matrizes de GitHub Actions, arquivos docker-compose e qualquer configuração escrita manualmente que não passa por um motor de templates.

Um exemplo de Kubernetes — três serviços com os mesmos limites 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_resources

Um exemplo de docker-compose — mesmo ambiente para dev e produção:

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

Em ambos os casos, alterar o ambiente comum é uma edição de uma linha.

As armadilhas

Âncoras são poderosas, mas têm algumas arestas afiadas.

Âncoras são locais a um documento. Um arquivo YAML multi-documento (com separadores ---) tem seu próprio escopo para âncoras. Uma âncora definida no documento um não pode ser referenciada do documento dois. Se você está usando ferramentas que produzem YAML multi-doc (como kubectl get -o yaml com múltiplos recursos), não pode usar âncoras para compartilhar valores entre eles.

Âncoras e merge interagem com override de maneiras surpreendentes. Se ambos a âncora e o map de referência definem a mesma chave, o valor do map de referência vence:

defaults: &defaults
  retries: 3
  timeout: 30

production:
  <<: *defaults
  retries: 10  # este vence

Então production.retries é 10, não 3. Esse é o comportamento esperado, mas pega pessoas que esperam “o último vence” ou “o primeiro vence” dependendo da ordem.

Chaves em maps mesclados não podem ser removidas. Se defaults tem uma chave legacy_setting: true e você quer “desativá-la” em production, não pode. Merge apenas adiciona chaves; nunca remove. Solução alternativa: não inclua a chave na âncora.

Âncoras não podem referenciar a si mesmas. Uma âncora autorreferencial cria um ciclo. A maioria dos parsers detecta isso e lança um erro. Se você nunca receber um erro “recursive anchor”, procure um alias apontando de volta para a âncora que o contém.

Âncoras e JSON não se misturam. JSON não tem conceito de âncoras. Se você converter YAML para JSON com âncoras, as âncoras são expandidas (o JSON fica maior) ou descartadas (o JSON fica menor). De qualquer forma, o resultado é maior que o YAML. Se você precisa de uma versão JSON, geralmente precisa de uma fonte de configuração diferente.

Alguns linters reclamam de âncoras. yamllint por padrão desativa âncoras (anchors: disable) por razões de estilo. Se você está usando âncoras, precisará configurar seu linter ou aceitar os avisos. A maioria das equipes que usa âncoras considera vale a pena o atrito com o linter.

Âncoras funcionam no grafo de objetos analisado, não no texto. Se você ordenar chaves alfabeticamente com uma ferramenta como yq e depois re-serializar, as âncoras são preservadas por referência, não pela ordem visível das chaves. A saída ainda está correta, mas pode ser visualmente surpreendente — a âncora aparece em um lugar, o alias em outro, e eles se referem ao mesmo objeto.

Verificando âncoras na sua configuração

A maneira mais rápida de verificar se suas âncoras estão funcionando é carregar o YAML em um parser que as resolva e imprimir o resultado. O validador de YAML no DevSpeedTools mostra o grafo de objetos resolvido — se suas âncoras estão conectadas corretamente, você verá os mesmos valores em todo lugar.

Para uma inspeção mais completa, a ferramenta de estatísticas de YAML diz o número total de chaves únicas vs. duplicadas, o que é uma boa métrica para “minhas âncoras realmente estão deduplicando alguma coisa?”

Para uma experiência de editor interativo, o VS Code com a extensão Red Hat YAML resolve âncoras ao passar o mouse e mostra onde cada alias aponta.

O resumo

Âncoras são a versão de YAML de uma variável. Elas funcionam no momento da análise, não no momento da serialização, então o arquivo que você escreve contém a âncora uma vez e as referências em muitos lugares. O parser as expande para o mesmo valor.

Use-as para padrões compartilhados. Não use-as para tentar compartilhar estado entre documentos. Não espere que a conversão para JSON preserve-as. E em caso de dúvida, execute o arquivo através de um validador para confirmar que a expansão corresponde à sua intenção — âncoras que silenciosamente produzem o valor errado são o tipo de bug que vai para produção e fica lá por um ano.