KYAML torna manifestos Kubernetes mais previsíveis

O YAML está presente em praticamente todos os manifestos, tutoriais e exemplos de Kubernetes. O problema não é o formato em si, mas a quantidade de escolhas que ele permite. Diferentes estilos de indentação, valores implícitos, strings sem aspas e outras características podem gerar arquivos visualmente inconsistentes e interpretações inesperadas.

Para reduzir essa variabilidade, o SIG CLI introduziu o KYAML, uma forma mais restrita e consistente de escrever YAML para Kubernetes. A proposta está definida no KEP 5295 e não cria uma nova linguagem nem exige um novo analisador. KYAML é um subconjunto estrito de YAML, portanto continua compatível com os analisadores e ferramentas que já trabalham com YAML.

O que muda no KYAML

KYAML fica entre o YAML tradicional e o JSON. Ele evita depender de espaços em branco significativos e usa uma estrutura mais explícita para representar os dados. Objetos usam chaves, listas usam colchetes e valores de texto devem ser escritos entre aspas duplas.

Um exemplo de estrutura KYAML pode ser representado assim:

apiVersion: "v1" kind: "Pod" metadata: { name: "meu pod", labels: { app: "demo" } } spec: { containers: [{ name: "nginx", image: "nginx:1.20" }] }

A sintaxe continua sendo YAML válida, mas elimina parte da flexibilidade que costuma causar divergências de estilo. O resultado é mais fácil de comparar em revisões de código, formatar automaticamente e processar em ferramentas de automação.

A proposta também evita alguns comportamentos ambíguos do YAML. Em vez de depender de regras implícitas para interpretar determinados valores, o formato privilegia uma representação explícita e uniforme. Isso é especialmente importante em configurações de infraestrutura, nas quais uma diferença pequena de interpretação pode alterar o comportamento de um recurso.

Usando KYAML com kubectl

O kubectl passou a oferecer KYAML como formato de saída. Em versões Kubernetes 1.36 ou posteriores, é possível configurar esse formato como padrão para o comando get usando o kuberc:

kubectl kuberc set --section defaults --command get --option output=kyaml

Nas versões 1.33 até 1.35, o recurso ainda precisa ser acessado com o prefixo alpha:

kubectl alpha kuberc set --section defaults --command get --option output=kyaml

Também é possível solicitar a saída diretamente em um comando, usando a opção de saída kyaml. Isso permite inspecionar recursos existentes no cluster e gerar uma representação formatada sem alterar o conteúdo lógico do objeto.

A configuração via kuberc separa preferências pessoais das configurações de cluster presentes no kubeconfig. Assim, o desenvolvedor pode definir como prefere visualizar os recursos sem modificar os contextos compartilhados ou a configuração usada por outras pessoas.

Convertendo arquivos existentes

Para converter manifestos já existentes, o ecossistema Kubernetes também oferece ferramentas específicas. O pacote sigs.k8s.io/yaml inclui o utilitário yamlfmt, capaz de converter arquivos para KYAML.

A instalação pode ser feita com:

go install sigs.k8s.io/yaml/yamlfmt@latest

O utilitário pode receber um arquivo e imprimir a versão KYAML na saída padrão. Também aceita um diretório, convertendo e imprimindo todos os arquivos encontrados nele. Como a saída é exibida no terminal, é necessário redirecioná-la para um arquivo ou implementar a gravação adequada quando a intenção for persistir a conversão.

O yamlfmt do Google também passou a oferecer um formatador dedicado para KYAML a partir da versão 0.21.0. Ele pode ser instalado com Go ou obtido como binário na página de releases do projeto.

Benefícios para projetos Kubernetes

A adoção de uma convenção única reduz diferenças irrelevantes em pull requests. Arquivos formatados da mesma maneira produzem revisões mais objetivas, com menos alterações causadas apenas por indentação, aspas ou estilo de listas.

A formatação consistente também facilita a validação automática. Repositórios podem executar o formatador em pipelines de integração contínua e rejeitar alterações que não estejam no padrão esperado. O próprio projeto Kubernetes possui verificações para encontrar arquivos YAML e garantir que estejam formatados corretamente.

Outro benefício é a maior previsibilidade para exemplos e documentação. O KEP propõe que o KYAML seja usado como formato padrão nos exemplos mantidos pelo projeto Kubernetes. Isso pode reduzir a variedade de estilos encontrados por quem está aprendendo ou copiando manifestos para seus próprios ambientes.

A compatibilidade com YAML é um ponto central da proposta. Ferramentas atuais não precisam ser substituídas apenas porque um arquivo passou a usar a sintaxe KYAML. A mudança está principalmente na forma de produzir e formatar os documentos, não no mecanismo usado para interpretá-los.

O que considerar antes de adotar

KYAML não elimina a necessidade de validação semântica. Um manifesto pode estar perfeitamente formatado e ainda conter uma imagem inexistente, uma referência inválida ou uma configuração incompatível com o cluster.

Também não é necessário converter todos os arquivos de uma vez. Uma equipe pode começar pela saída do kubectl, aplicar o formatador em novos manifestos e depois migrar arquivos antigos conforme eles forem alterados. Essa abordagem reduz conflitos e permite avaliar o impacto no fluxo de revisão.

É importante verificar a versão do kubectl e a disponibilidade do kuberc antes de documentar comandos para toda a equipe. A sintaxe varia entre as versões 1.33, 1.35 e 1.36, principalmente pelo uso temporário do prefixo alpha.

Como isso pode ser útil para você

Mestre, você pode adotar KYAML nos seus repositórios Kubernetes para padronizar manifestos, reduzir ruído em revisões e criar uma verificação automática no CI. Uma aplicação prática é combinar yamlfmt com validação de esquema e um pipeline que rejeite arquivos fora do padrão, oferecendo depois essa organização como parte de uma consultoria de melhoria de entrega e governança DevOps.

Fonte: https://kubernetes.io/blog/2026/08/11/how-to-pretty-print-kubernetes-yaml-as-kyaml/