YamlBox

Artigo do guia · 5 min de leitura

Convertendo Kubernetes YAML para JSON com segurança

A conversão de Kubernetes YAML para JSON acontece no limite API: Kubernetes fala JSON e YAML é uma camada de conveniência que kubectl e suas bibliotecas cliente convertem para você – e é por isso que entender a conversão é importante quando algo dá errado.

Atualizado

Kubernetes YAML para JSON: por que converter?

  • Depurando com a forma API real: quando um campo é rejeitado, JSON mostra exatamente o que o servidor vê, sem ambiguidade de digitação YAML.
  • Alimentando pipelines: muitas ferramentas (mecanismos de política, scripts de CI, pipelines jq) consomem JSON mais confortavelmente do que YAML.
  • Diferenciação da saída renderizada: comparar duas versões Helm como JSON torna as alterações de tipo visíveis — o bug clássico “true is not “true””.
  • Documentação e ensino: chaves JSON tornam o aninhamento de spec.template.spec.containers inconfundível.

O problema de vários documentos

Um arquivo manifesto geralmente contém muitos recursos separados por ---: Namespace, ConfigMap, Deployment, Service, Ingress, HPA. Um conversor ingênuo de YAML para JSON lê o primeiro documento e descarta silenciosamente o resto – um modo de falha genuinamente perigoso para o trabalho de infraestrutura. Bons conversores produzem um array JSON, um elemento por documento, e informam quantos encontraram.

Helm, âncoras e "por que não há âncoras na minha saída?"

Âncoras e aliases podem desduplicar blocos dentro de um arquivo. Os modelos Helm vão além — eles não são YAML até serem renderizados. Converta apenas a saída renderizada (helm template / helm get manifest), nunca um arquivo de modelo bruto. Consolidar âncoras em seus valores é o comportamento correto: JSON não tem aliases, então o conversor deve desreferencia-las.

As armadilhas da digitação

  • Booleanos: versões e nomes como "y", "yes", "on" são booleanos em YAML 1.1. Em Kubernetes, uma tag de imagem como “on” ou uma versão como “1.10” é um caso clássico de corrupção silenciosa – sempre cite-os na fonte.
  • Portas e recursos: containerPort: 8080 é um int; "8080" como string será rejeitado pelo API para campos digitados. JSON mantém a distinção explícita.
  • Quantidades de memória: 128Mi é uma string em ambos os formatos — correto, porque é analisado por Kubernetes, não por YAML.
  • Valores de ambiente: os valores de env são strings por especificação; valor: 3000 em YAML torna-se o número 3000, que API rejeita. Este é um dos bugs de manifesto mais comuns, e a saída JSON torna isso óbvio instantaneamente.

Um fluxo de trabalho prático

  1. Renderize primeiro (se Helm): helm template mychart > rendered.yaml.
  2. Converta com suporte a vários documentos em um array JSON, para que nenhum recurso seja descartado.
  3. Faça uma comparação com o que o cluster tem: kubectl get deploy web-app -o json, em comparação com uma ferramenta JSON diff — as mudanças que importam se destacam imediatamente.
  4. Patches com confiança: patches JSON (RFC 6902) e patches de mesclagem estratégica são mais fáceis de escrever contra JSON inequívocos.

Ambas as etapas são cobertas pelas ferramentas deste site: YAML a JSON para a conversão e JSON Diff para comparar o resultado com a saída kubectl — nenhum dado do cluster sai da sua máquina.