YAML em configurações de implantação

O que é YAML em configurações de implantação?

YAML é um formato de texto feito para ser lido facilmente por pessoas e interpretado por programas. A sigla significa "YAML Ain't Markup Language". Em vez de chaves e colchetes, ele organiza as informações com recuos (espaços) e pares no formato chave: valor.

Na implantação, ou deploy, esses arquivos funcionam como uma receita. Eles dizem à ferramenta de infraestrutura qual aplicação executar, quantas cópias manter, quais portas abrir e quais configurações carregar. Assim, o mesmo sistema pode ser publicado sempre da mesma forma, sem depender de passos manuais.

Para que serve o YAML na implantação de uma integração fiscal?

Em um ERP ou plataforma de vendas que emite NF-e, NFS-e ou NFC-e por API, o YAML costuma guardar as configurações do serviço responsável pela integração fiscal: o endereço da API, o tempo máximo de espera de cada requisição, a quantidade de tentativas em caso de falha e o ambiente usado.

Uma vantagem prática é separar ambientes. É possível ter um arquivo para o ambiente de homologação, que gera documentos sem valor fiscal para testes, e outro para o ambiente de produção, que emite documentos válidos. Trocar de ambiente passa a ser uma mudança de configuração, e não de código.

Como funciona a estrutura de um arquivo YAML?

A base são pares de chave e valor, como timeout: 30. Para agrupar informações, usa-se recuo com espaços: tudo que está mais à direita pertence ao item acima. Listas são indicadas por um hífen no início da linha. Comentários começam com o caractere #.

O recuo tem significado. Um espaço a mais ou a menos muda a estrutura e pode fazer a ferramenta ler a configuração de forma errada ou recusar o arquivo. Por isso, tabulações não são aceitas como recuo, apenas espaços.

Qual a diferença entre YAML e JSON?

Os dois representam o mesmo tipo de dado: objetos, listas, textos e números. Na verdade, quase todo JSON válido também é YAML válido. A diferença está na escrita: o JSON usa chaves, colchetes e aspas obrigatórias, enquanto o YAML depende de recuos e permite comentários.

Na prática, o YAML é preferido para arquivos que pessoas editam com frequência, como configurações de implantação. Já o JSON é o formato mais comum para trocar dados entre sistemas, como no payload de uma requisição de emissão fiscal.

Quais cuidados tomar ao usar YAML com dados fiscais e credenciais?

O principal cuidado é nunca escrever segredos diretamente no arquivo, como a API Key, o token de autenticação ou a senha do certificado digital A1. Arquivos YAML costumam ir para repositórios de código e podem ser vistos por muitas pessoas. O ideal é que o YAML apenas faça referência a um segredo guardado em local protegido, como um Kubernetes Secret ou um cofre de chaves.

Outro cuidado é com a interpretação automática de valores. Um CNPJ ou código de município que começa com zero pode ser lido como número e perder esse zero. Em algumas versões do formato, palavras como no ou yes viram valores verdadeiro ou falso. Colocar esses valores entre aspas garante que sejam tratados como texto.

Exemplos de YAML em configurações de implantação

• Um arquivo de Deployment do Kubernetes define a variável FISCAL_API_BASE_URL apontando para o endereço de homologação da API fiscal, enquanto um arquivo separado aponta para produção.
• Um docker-compose.yml sobe localmente o backend de integração fiscal junto com o banco de dados e a fila de emissão, para que a equipe teste a emissão de NFS-e antes do deploy.
• Um pipeline de integração contínua descrito em YAML executa testes de emissão em homologação e só libera a publicação em produção se todos passarem.
• Um arquivo de configuração lista os CNPJs das filiais entre aspas, evitando que zeros à esquerda sejam removidos na leitura.