O comportamento que morde aqui é especificado, não acidental: o Especificação YAML 1.2 define como um escalar não citado é resolvido para um tipo.
Certa vez, enviei uma implantação que fixava um serviço na versão 1.1 Quando o arquivo de configuração disse claramente 1.10. Não é um tipo de digitação. Não é um mau achado e substituição. O arquivo YAML, que eu li quatro vezes, dizia o seguinte:
image_tag: 1.10
e o analisador entregou meu script de implantação o número 1.1. porque 1.10 isn't uma string de versão para YAML - it's a literal flutuante, e os flutuadores não continuam atrás de zeros. Dez se torna um ponto um. O arquivo era 100% válido YAML. O linter ficou feliz. CI era verde. O recipiente errado apagou.
É o que ninguém fala sobre a validação do YAML: "Válido" não é o mesmo que "correto". Um verificador de sintaxe que responde apenas sim/não está respondendo à pergunta fácil A pergunta difícil - aquela que realmente quebra as implantações - é Em que meu YAML se transformou? Como o YAML não é um formato de configuração, é um mecanismo de inferência de tipo vestindo roupas de um formato de configuração e toma decisões sobre seus dados que você nunca pediu para fazer.
o Validador YAML no Toolz.dev responde a ambas as perguntas Ele diz se o documento analisa, e então ele mostra o resultado analisado como JSON - a estrutura de dados real que seu ferramental receberá Essa segunda metade é o que teria me salvado. "image_tag": 1.1 No painel de saída é impossível de interpretar mal.
tl;dr: Cole seu yaml no Validador YAML e leia o Saída JSON, não apenas a marca de seleção verde. É aí que o tipo de coerção se mostra:
1.10→1.1,0123→123, valores não aspassados, tornando-se silenciosamente números, booleanos ou nulos. Ele é executado em JS-YAML (YAML 1.2) inteiramente em seu navegador, portanto, os segredos do Kubernetes e as credenciais de banco de dados nunca saem da sua máquina. Cite qualquer coisa que deva ficar uma corda. Se você precisar comparar o resultado com uma configuração JSON, o formatador json e json diff pegar de lá.
O que um validador YAML realmente verifica?
Duas coisas diferentes, e vale a pena separá-las porque elas falham de forma diferente.
Validação de sintaxe Pergunta: Este texto pode ser analisado? Abas onde os espaços pertencem, um espaço perdido após dois pontos, um escalar de bloco cujo corpo não é recuado, uma citação não fechada. estes são alto Falhas. Seu analisador lança, seu pipeline fica vermelho, você o conserta em dois minutos. Irritante, não perigoso.
inspeção semântica pergunta: o que foi analisado em? É aqui que vivem as falhas silenciosas. O documento é válido. O pipeline é verde. O valor simplesmente não é o que você pensou que escreveu. Ninguém descobre até que a produção se adapte de forma estranha e, então, ninguém está olhando para o arquivo de configuração, porque o arquivo de configuração está "bem"
A maioria dos verificadores online do YAML só fazem o primeiro O validador Toolz.dev faz o primeiro e depois entrega-lhe o segundo - o documento analisado, renderizado como JSON, mesmo ao lado da sua entrada, Adquira o hábito de ler esse painel It' s a diferença entre o & quot; o ficheiro está bem formado" e o & quot; o ficheiro significa o que EU quis dizer."
Quais erros YAML realmente quebram as compilações?
Aqui está o que realmente aparece, classificado por quanto da minha vida cada um me custou. Cada comportamento abaixo que eu verifiquei js-yaml 4, que é o analisador do Validador Toolz.dev e que implementa o YAML 1.2 especificação.
1. Abas. Sempre guias.
YAML proíbe caracteres de tabulação para recuo Não é & quot; desencoraja" - proíbe. A especificação é explícita e a mensagem de erro é refrescantemente direta:
tab characters must not be used in indentation
A razão pela qual isso continua acontecendo é que as guias são invisíveis. Seu editor mostra um arquivo bem alinhado; o analisador vê um caractere de controle. Corrija-o na origem: defina seu editor para inserir espaços e ative o "Render Whitespace" para arquivos YAML. Dois espaços por nível, que é a convenção em que todos os principais ecossistemas YAML estabeleceram.
2. Chaves duplicadas
database:
host: localhost
port: 5432
host: production-db.example.com
host aparece duas vezes. O que acontece? Depende inteiramente do seu analisador, que é uma frase horrível para escrever sobre um formato de configuração.
js-yaml arremessos: duplicated mapping key. Bom. Isso e #39; é o comportamento que você deseja e é & #39; é o que o validador Toolz.dev mostrará a você. Mas PyYAML - que é o que Ansible, e muitas ferramentas Python, senta-se - silenciosamente pega o antecede valor e segue em frente. nenhum aviso. O host do banco de dados agora é o que quer que seja a última duplicata, que em um arquivo longo você mesclarou muito pode estar a trezentas linhas de onde você está procurando.
Este é o melhor argumento para executar as configurações por meio de um validador estrito, mesmo quando as ferramentas de produção as aceitam. um validador que rigoroso Do que o seu tempo de execução é um validador que encontra bugs.
3. Tipo de coerção - aquela que me pegou
YAML infere tipos de escalares não aspas. É muito confiante e muitas vezes é errado sobre sua intenção:
| você escreveu | você quis dizer | YAML 1.2 oferece |
|---|---|---|
version: 1.10 |
A string \u2010"1.10" | o flutuador 1.1 |
pin: 0123 |
A string \u2013" | o inteiro 123 |
port: "8080" |
o número 8080 | a corda "8080" |
enabled: true |
booleano | booleano true - correto |
value: |
Corda vazia, talvez? | null |
value: ~ |
um til | null |
que 0123 row é o único I & #39; d tatuagem em pessoas CEP, PINs, números de conta, IDs com preenchimento zero - cada zero à esquerda que você escreveu por uma razão é comido Citar-los.
A regra que nunca me decepcionou: Se o valor for um identificador, uma versão, um código ou qualquer coisa em que você nunca usaria aritmética, coloque-o entre aspas. Portas e contagens de réplicas podem ficar nuas. tudo o que meramente ar numérico deve ser "quoted".
4. Os booleanos dependentes da versão (também conhecido como problema da Noruega)
Este é genuinamente notório, e os detalhes importam mais do que o meme.
para YAML 1.1, o tipo booleano aceita yes, no, on, off, y, ne suas capitalizações, além de true e false. por isso country: NO - Noruega's Código de país ISO - análises como booleanas falso. para YAML 1.2, que limpou isso, apenas true e false são booleanos; NO é apenas a corda "NO".
o que significa o mesmo arquivo Significa coisas diferentes em ferramentas diferentes:
country: NO
feature_flag: on
- JS-YAML 4 (YAML 1.2 e o que este validador usa):
{"country": "NO", "feature_flag": "on"}- cordas. - Pyyaml (YAML 1.1):
{"country": False, "feature_flag": True}- booleanos.
Mesmos bytes. dados diferentes. Se o seu CI executa um Linter Python em uma configuração que um serviço de nó consome, você tem dois analisadores discordando sobre seu arquivo e nenhum deles está errado.
Esta é também a origem das ações do GitHub' Quirkest Weird: The on: chave com a qual todo fluxo de trabalho começa é um booleano Para um analisador YAML 1.1, os scripts que os arquivos de fluxo de trabalho do Lint em Python encontram uma chave chamada True em vez de on. Citação ("on":) é legal e resolve.
O movimento defensivo é o mesmo de antes: cite-o. country: "NO" meios "NO" em todos os analisadores que já existiram.
5. Bloqueie o recuo escalar
description: |
This is not indented
o | (literal) e > (Dobrado) Escalares de blocos precisam de seu conteúdo recuado em relação à chave. O conteúdo não recuado termina o bloco imediatamente e o analisador começa a ler sua prosa como teclas YAML, que produz mensagens de erro que parecem não ter nada a ver com o erro real.
Vale a pena conhecer os indicadores de mastigação enquanto você está aqui: | Mantém uma nova linha à direita, |- tira, |+ Mantém todos eles. Se você está incorporando uma chave privada ou um script e algo downstream reclama de uma nova linha à direita, este é o seu botão.
6. caracteres especiais não citados
Um espaço de dois pontos dentro de um valor não aspasado encerra o valor e inicia uma nova chave. Isso se encaixa em mensagens de erro e URLs:
message: Error: file not found # parse error
regex: [a-z]+ # parsed as a LIST, not a string
time: "22:22" # quote it — in YAML 1.1 this was base-60!
[, {, #, &, *, !, |, >, %, @ No início de um escalar, todos significam algo. Cite primeiro, faça perguntas depois.
Como valido o YAML no Toolz.dev?
- abra o Validador YAML. Sem conta, sem upload.
- Cole seu documento. Um arquivo de valores Helm, um docker-compose, um fluxo de trabalho - seja lá o que for e #39; está se comportando mal.
- Clique em Validar. Os erros voltam com o exato linha e coluna No analisador, mais a string de razão do analisador (
bad indentation of a mapping entry,duplicated mapping key, e assim por diante). - Leia o painel de saída JSON. Este é o passo que as pessoas pulam e é o que importa. Digitalize-o para obter os valores de que você gosta. é
image_taguma string ou um número? Essa porta é citada? um valor vazio se tornounull? - Corrigir, revalidar. Erros podem mascarar uns aos outros - o analisador pára no primeiro que pode' t recuperar de, então consertar um às vezes revela mais dois Isso' s normal, não um sinal de que as coisas estão piorando.
uma limitação conhecida, declarada claramente
O validador atualmente analisa um único documento yaml. Se você colar um arquivo de vários documentos - vários manifestos do Kubernetes separados por --- num ficheiro, que é um padrão extremamente comum - irá reportar
expected a single document in the stream, but found more
Esse é o analisador correto, não o arquivo sendo quebrado. A solução atual é validar cada documento separadamente: cole tudo acima do ---, verifique e cole o próximo pedaço. O suporte a vários documentos está na minha lista precisamente porque os usuários do Kubernetes acertam isso imediatamente, e prefiro falar sobre o GAP do que permitir que você o descubra no meio do incidente.
YAML vs JSON: Quando devo usar qual?
YAML 1.2 é um superconjunto estrito de JSON - todo documento JSON válido é YAML válido, e é por isso que o validador pode entregar a você a saída JSON em tudo Mas os formatos têm personalidades opostas.
| yaml | JSON | |
|---|---|---|
| estrutura definida por | Recuo (significativo de espaço em branco) | Suspensórios e colchetes (explícito) |
| comentários | Sim (#) |
não |
| Inferência de tipo | Agressivo - infere números, booleanos, nulo, datas | Nenhum - aspas significam string, sempre |
| vários documentos | Sim (--- separador) |
não |
| reutilizar | âncoras (&), aliases (*), mesclar chaves (<<) |
nenhum |
| Modo de falha | interpretação silenciosa | Erro de análise em voz alta |
| melhor em | Arquivos que os humanos escrevem e editam | troca de máquinas de dados |
O comércio é real e vai nos dois sentidos YAML & #39; s legibilidade e comentários são exatamente por que a configuração de infraestrutura vive lá - ninguém quer manter um manifesto Kubernetes de 400 linhas em JSON sem comentários JSON & #39; s total falta de inteligência é exatamente por isso que as APIs usá-lo: "1.10" é "1.10" E não há nada para discutir.
minha regra: YAML para arquivos que as pessoas editam, JSON para datamchines passa. E quando um arquivo YAML é gerado por um programa em vez de digitado por uma pessoa, isso & #39; é um cheiro - a configuração gerada por máquina não recebe nenhum benefício do YAML' e todos os seus riscos.
Se você estiver se movendo entre os dois, o Conversor JSON para YAML Lida com a transformação e o formatador json Vai arrumar o outro lado.
O que são âncoras e apelidos, e devo usá-los?
O YAML permite que você defina um bloco uma vez e o reutilize. âncora com &, referência com *, mesclar em um mapa com <<:
defaults: &defaults
adapter: postgres
host: localhost
port: 5432
development:
<<: *defaults
database: myapp_dev
test:
<<: *defaults
database: myapp_test
ambos development e test saia com o adaptador, host e porta mesclados. It' é genuinamente útil e o js-yaml lida com isso - verifiquei a resolução da mesclagem corretamente.
No entanto, dois avisos.
Primeiro, Mesclar chaves são uma extensão YAML 1.1, não faz parte do núcleo YAML 1.2. o apoio é generalizado mas não universal, e - aquele que apanha pessoas - Ações do GitHub não os suportam. âncoras em um arquivo de fluxo de trabalho não farão o que você deseja. Verifique seu consumidor antes de se apoiar nisso.
Em segundo lugar, as âncoras tornam o arquivo mais difícil de ler para a próxima pessoa e, na configuração, a próxima pessoa geralmente é você às 2 da manhã. Eu as uso para blocos genuinamente repetidos e nunca para esperteza.
Enquanto estamos no lado perigoso do YAML: o formato suporta tags personalizadas que alguns analisadores usam para construir objetos arbitrários. Python yaml.load() era notoriamente explorável desta forma, e é por isso que yaml.safe_load() existe e por que você deve usá-lo - sempre - em qualquer YAML que veio de fora de sua equipe. js-yaml's load() Na V4 é seguro por padrão (ele não construirá tipos arbitrários), o que é um a menos para se preocupar aqui.
Como faço para parar de escrever yaml quebrado em primeiro lugar?
A prevenção supera a validação e a maior parte é a configuração do editor:
- Dois espaços, nunca guias. Defina-o por tipo de arquivo para que você não possa esquecer.
- Ativar renderização de espaços em branco para
.yml/.yaml. Se você puder ver a guia, não confirmará a guia. - Instale um servidor de linguagem YAML. A validação de esquema em tempo real contra Kubernetes, ações do GitHub e esquemas de composição do Docker captura uma classe inteira de erros que a validação de sintaxe não pode: YAML válido com uma tecla de ortografia incorreta.
- Citação por padrão em caso de dúvida. O custo de uma cotação desnecessária é zero. O custo de um ausente é uma implantação.
- Valide antes de empurrar, não após falha do CI. Colar em uma guia do navegador leva oito segundos; um pipeline com falha leva oito minutos.
- Para Kubernetes, coloque as verificações. A validação de sintaxe captura a estrutura;
kubectl apply --dry-run=clientcaptura o esquema. Eles encontram bugs diferentes e você quer os dois.
E o hábito que realmente mudou as coisas para mim: quando uma implantação baseada em configuração faz algo inexplicável, Observe a saída analisada antes de olhar para qualquer outra coisa. Não o arquivo. a saída analisada. O arquivo é uma história sobre o que você quis dizer. A saída analisada é o que realmente aconteceu.
Esse é o mesmo instinto que governa tudo em minha Fluxo de trabalho de depuração de API - leia os dados, não o código - e ele se aplica tão bem às configurações quanto às respostas Se você quiser o tour mais amplo do que mais vive nessa caixa de ferramentas, o Guia de ferramentas de codificação cobre isso.
Perguntas frequentes
Por que meu YAML valida, mas ainda interrompe minha implantação?
Porque a validade da sintaxe e o correto semântico são coisas diferentes. YAML infere tipos de valores não aspas, então 1.10 torna-se o flutuador 1.1, 0123 torna-se o inteiro 123, e um valor vazio torna-se null - tudo em um documento perfeitamente válido Leia a saída JSON analisada, não apenas o resultado de aprovação/reprovação, e cite qualquer valor que deva permanecer uma string.
Por que o YAML transforma meu número de versão em um número diferente?
1.10 é um literal flutuante para YAML e os flutuadores não preservam os zeros à direita, então resolve 1.1. Qualquer versão, número de compilação ou identificador com preenchimento zero deve ser citado: version: "1.10". Este é um dos erros mais caros do YAML porque o arquivo parece certo e a análise é bem-sucedida.
Qual é o problema da Noruega no YAML?
No YAML 1.1, os valores no, NO, off, e yes são booleanos, então o código do país da Noruega NO analisa como false. YAML 1.2 corrigiu isso apenas true e false são booleanos - mas muitas ferramentas (nomeadamente PyYAML, que Ansible usa) ainda implementam 1.1. o mesmo arquivo pode, portanto, significar coisas diferentes em ferramentas diferentes Citando o valor (country: "NO") o torna uma string em todos os lugares.
Posso usar guias para recuo em YAML?
Não. A especificação YAML proíbe caracteres de tabulação no recuo e os analisadores os rejeitam com um erro como & quot; caracteres de tabulação não devem ser usados no recuo." Configure seu editor para inserir espaços para arquivos YAML - dois espaços por nível é a convenção padrão.
O validador Toolz.dev YAML oferece suporte a arquivos de vários documentos?
Atualmente não. Ele valida um único documento, portanto, um arquivo contendo vários manifesto do Kubernetes separados por --- Retorna "Esperou um único documento no stream." Valide cada documento separadamente como uma solução alternativa. O suporte a vários documentos está planejado.
As chaves duplicadas são permitidas no YAML?
A especificação diz que as chaves de mapeamento devem ser únicas, mas os analisadores discordam na prática, o js-yaml - que este validador usa - lança uma tecla de mapeamento & quot; duplicada & quot; erro O PyYAML silenciosamente mantém o último valor, o que significa que uma duplicata pode substituir silenciosamente sua configuração sem nenhum aviso, Executar sua configuração através de um validador rigoroso captura isso antes que seu tempo de execução silenciosamente aceite.
É seguro validar os segredos e credenciais do Kubernetes online?
Com o validador Toolz.dev, sim - a análise acontece inteiramente no seu navegador via JavaScript e nada é transmitido para qualquer servidor Você pode confirmar isso sozinho abrindo sua guia de rede browser' s enquanto você valida e observa que nenhuma solicitação é feita Aplique essa mesma verificação a qualquer ferramenta online antes de colar a configuração da infraestrutura nela.
Qual é a diferença entre .yml e .yaml?
Nada funcional - ambas as extensões são reconhecidas por cada analisador YAML. A recomendação oficial é .yaml; .yml Sobrevive da era das extensões de três caracteres e permanece extremamente comum (as ações do Docker Compose e do GitHub padronizam). Escolha um e mantenha-se consistente em um projeto.
Como faço para converter YAML em JSON?
Cole o YAML no validador e leia o painel de saída - ele renderiza o documento analisado como JSON, que é a conversão. Como o YAML 1.2 é um superconjunto do JSON, todo documento YAML válido tem um equivalente JSON, mas a inferência de tipo é aplicada primeiro, portanto, não é citado 1.10 chega como 1.1 e 0123 quanto 123. Cite esses valores primeiro se você precisar deles preservados como strings.
Como faço para validar o YAML em um esquema?
Este validador verifica a sintaxe e mostra o resultado analisado, mas não valida contra um esquema - que é uma verificação separada confirmando suas chaves e tipos de valor correspondem ao que uma ferramenta como Kubernetes ou GitHub Actions espera Para validação de esquema, use um servidor de linguagem YAML em seu editor ou uma CLI com reconhecimento de esquema, como kubeconform Para Kubernetes ou kubectl apply --dry-run=client. A sintaxe e a validação do esquema capturam bugs diferentes, então execute ambos.
