YAML sem surpresa

fundamentos

Indentação

Espaços apenas. Tabulação é erro de sintaxe em YAML.
Dois espaços por nível é a convenção.
A indentação define a estrutura; não há chaves para corrigir engano.

spec:
  containers:
    - name: app          # o "-" faz parte da indentação do item
      image: app:1.0
      ports:
        - containerPort: 8080

Tipos e o que o parser adivinha

numero: 42            # int
decimal: 3.14         # float
texto: "42"           # string (aspas obrigatórias para preservar)
booleano: true
nulo: null            # ou ~, ou campo vazio
lista: [a, b]         # forma inline
mapa: {chave: valor}  # forma inline

Valores que parecem outra coisa e viram tipo errado:

Escrito	Interpretado como	Como forçar string
`no`, `off`, `yes`, `on`	booleano (YAML 1.1)	`"no"`
`NO` (código da Noruega)	`false`	`"NO"`
`1.10`	número 1.1 (versão vira outra coisa)	`"1.10"`
`012`	número em octal, em alguns parsers	`"012"`
`1e3`	1000	`"1e3"`
`2026-09-04`	data	`"2026-09-04"`
`:senha` ou `@valor`	erro de sintaxe	`":senha"`
`*` no início	referência a âncora	`"*"`

O caso conhecido como “problema da Noruega”: um campo pais: NO vira false. Regra prática: coloque entre aspas tudo que precisa ser string — versões, códigos, senhas, valores com dois-pontos.

Strings multilinha

literal: |            # preserva quebras de linha
  primeira linha
  segunda linha

dobrado: >            # junta em uma linha só
  este texto
  vira uma linha

sem_final: |-         # remove a nova linha final
  sem quebra no fim

com_finais: |+        # mantém as quebras finais
  texto

| é o que você quer para script embutido, certificado ou configuração de aplicação.

data:
  script.sh: |
    #!/usr/bin/env bash
    set -euo pipefail
    echo "cuidado com a indentação: ela é removida do bloco"

Âncoras e aliases

padroes: &padroes
  imagePullPolicy: IfNotPresent
  resources:
    requests: { cpu: 100m, memory: 128Mi }

containers:
  - name: api
    <<: *padroes           # herda o mapa
    image: api:1.0
  - name: worker
    <<: *padroes
    image: worker:1.0

Funciona no arquivo, e tem limites: âncoras não atravessam documentos, o Kubernetes não as resolve depois de aplicado (o resultado já vem expandido) e o excesso deixa o manifest difícil de ler. Para reuso de verdade, prefira Kustomize ou Helm.

Múltiplos documentos

apiVersion: v1
kind: Namespace
metadata: { name: loja }
---
apiVersion: apps/v1
kind: Deployment
metadata: { name: loja, namespace: loja }

--- separa documentos; ... encerra explicitamente (raro). A ordem importa quando há dependência (namespace antes dos recursos dentro dele).

Validação

yq '.' arquivo.yaml                          # falha se a sintaxe estiver errada
yamllint -d relaxed arquivo.yaml
kubectl apply --dry-run=client -f arquivo.yaml   # estrutura
kubectl apply --dry-run=server -f arquivo.yaml   # servidor + admission + políticas
kubeconform -strict -summary arquivo.yaml         # contra o schema da API
kubectl kustomize overlays/prod | kubeconform -strict

--dry-run=server é o que pega erro de campo inválido, versão de API removida e violação de política. Vale mais que qualquer linter.

Comentários e boas práticas

# comentário de linha inteira
replicas: 3   # comentário no fim da linha

Comentário não sobrevive à maioria das ferramentas que reescrevem o arquivo — yq -i é exceção e preserva.
Prefira listas explícitas com - a listas inline em manifests longos.
Mantenha o arquivo curto: manifest de 800 linhas é sinal de que falta uma abstração.
Formate de maneira consistente (dois espaços, sem espaços à direita) e verifique no CI.

Pegadinhas

Tabulação quebra o arquivo — configure o editor para converter em espaços.
Espaço faltando depois de : (chave:valor) faz virar uma string única.
Chave duplicada não é erro em muitos parsers: a última vence, em silêncio.
Indentação errada em uma lista muda a estrutura sem gerar erro de sintaxe.
on: no GitHub Actions é interpretado como booleano por alguns parsers antigos.
Valor com : precisa de aspas: mensagem: "erro: falhou".
Barra invertida em string com aspas duplas é escape; use aspas simples para literal.
YAML é um superconjunto de JSON: JSON válido é YAML válido, e às vezes é mais seguro.