YAML no Kubernetes: 12 erros de config que quebram deploy às 2h

YAML parece amigável até um erro de dois espaços derrubar produção. Kubernetes popularizou YAML como face da infra, então todo mundo edita formato sensível a whitespace sob pressão — colando de Stack Overflow, ChatGPT ou Helm com caracteres invisíveis. Catálogo abaixo reúne erros que passam em review, como o apiserver vira JSON por baixo, e por que converter e inspecionar no Safe Local Tools no navegador evita colar manifesto interno em formatadores na nuvem antes do kubectl apply.

YAML é interface humana, não linguagem indulgente

YAML 1.2 permite escalares citados ou não, blocos literais — flexibilidade que ajuda prosa e prejudica máquinas. yes/no podem virar booleano; 0123 já foi lido como octal em engines velhos; tabs acidentais quebram indentação. Kubernetes converte YAML→JSON server‑side; YAML válido que vira tipos JSON inesperados gera comportamento sutil, não erro de sintaxe bonito.

Erros 1–3 — tabs, indentação e escalares que viram boolean/null

YAML proíbe tab para estrutura; editores inserem tab ao apertar Tab no painel errado. Sintoma: found character that cannot start any token. Correção: indentar com espaços, .editorconfig, hook rejeitando \t em *.yaml.

Profundidade inconsistente em listas - aninha campos no pai errado — probes somem, env aparece em outro container. Colapso visual + schema Kubernetes na IDE ajuda.

Strings sem aspas ambíguas viram tipos: value: off pode interpretar como falso. Correção: value: "off".

env:
  - name: DEBUG
    value: off   # pode virar false

Erros 4–8 — blocos, chaves duplicadas, Helm e apiVersion

Scripts multilinha em args: com : quebram parse sem bloco |/> citado. Duplicate keys: em alguns loaders a última ganha sem aviso — você jurou imagePullPolicy: Always mas chave anterior sumiu. Correção: lint estrito; rodada YAML→JSON para enxergar duplicidade.

Copiar Helm cru com {{ .Values.foo }} não é objeto Kubernetes até renderizar — use helm template. Par apiVersion/kind pode ser YAML válido e recurso incompreensível para o cluster; mantenha matriz de versões e kubectl api-resources.

Arquivo único de 2000 linhas convida drift de indent — Kustomize, splits por Deployment/Service/Ingress.

Erros 9–12 — segredos, separadores ---, quantities e anchors

Segredos base64 em git são governança esperando incidente — Sealed Secrets, SOPS, operadores externos. --- ausente mistura documentos; use separadores explícitos. CPU 500m e memória 512Mi devem ser strings, não float — citação e regex de quantity conforme docs.

Âncoras & / aliases * não existem em JSON; conversores expandem ou recusam — duplique explicitamente no que vai para git, use anchors só em passo local de template.

Safe Local Tools converte YAML/JSON no cliente, útil quando política de dados impede paste em formatter público. JSON puro expõe coerção escondida, null vs string vazia e arrays virando objetos.

Fluxo saudável antes do apply

Formatar e lintar no CI; converter para JSON localmente para inspecionar estrutura efetiva; kubectl apply --dry-run=server -f manifest.yaml; canário e watch de eventos. CRDs exigem shape além do Deployment — gere validação cliente quando existir; senão dry‑run continua rei.

Quando LLM escreve YAML, ele bagunça indent e alucina apiVersion — mesmos checks mecânicos de sempre. Jobs de CI podem rodar yamllint + kubeconform (instalação omitida aqui) e publicar manifests renderizados do Helm como artefato de review.

yamllint -c .yamllint manifest/
kubeconform -kubernetes-version 1.29.0 -summary manifest/

Segurança revisando manifestos

Trate manifest como código: commits assinados, review obrigatório. Procure hostPath, privileged: true, RBAC com curinga. Pin de imagem por digest em produção, não só tag. NetworkPolicy e Ingress TLS com nome errado de Secret podem servir cert default em silêncio — visão JSON confirma aninhamento.

Multi‑cluster: skew de versão aceita betas em staging e rejeita em prod — documente ao lado de backups e cron, não só ao lado do app.

Volumes montados de ConfigMap/Secret podem falhar por sintaxe YAML no arquivo embutido enquanto o Deployment aplica limpo — um init container que valida gramática antes do processo principal evita loop de CrashLoopBackOff difícil de enxergar no diff do Git.

Quando compliance impede colar manifesto completo em formatador SaaS, converter YAML↔JSON localmente mantém triagem de indentação e de tipos dentro do dispositivo autorizado — combine com kubectl apply --dry-run=server para aproximar o que o apiserver rejeitará antes de gastar rodada de review humana.

Lembretes finais: kube-score sugere confiabilidade mas não substitui schema; engines de política (OPA, Kyverno) precisam dos mesmos manifests que você inspeciona — se JSON revela campo fantasma, a política também precisa enxergá‑lo antes do merge.

Erros de YAML raramente são mistério; são whitespace e tipos amplificados pelo modelo JSON estrito sob o Kubernetes. Antes do próximo apply, converta e inspecione localmente — Experimentar o conversor YAML ↔ JSON →