# YAML em configurações de implantação > YAML em configurações de implantação é o uso de arquivos de texto no formato YAML para descrever como um sistema deve ser instalado e executado: quais serviços sobem, com quais variáveis, em qual ambiente e com quais recursos. É comum em Kubernetes, Docker Compose e pipelines de integração contínua, incluindo integrações com APIs fiscais. **Também conhecido como:** Arquivo YAML de deploy, Manifesto YAML, Configuração em YAML, YML, YAML, YAML deployment configuration **Glossário:** [Glossário de A a Z](https://conota.dev/glossario/) · **Letra:** Y ## 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. ## Perguntas frequentes ### Posso colocar a API Key da emissão fiscal no arquivo YAML? Não é recomendado. O YAML deve apenas referenciar a chave, que precisa ficar em um local protegido, como um Kubernetes Secret, um cofre de chaves ou variáveis de ambiente gerenciadas. Isso reduz o risco de vazamento pelo repositório de código. ### Por que meu arquivo YAML dá erro mesmo parecendo correto? A causa mais comum é o recuo: uso de tabulação em vez de espaços ou quantidade de espaços inconsistente. Também vale conferir se há dois-pontos sem espaço depois e se textos com caracteres especiais estão entre aspas. ### A extensão é .yaml ou .yml? As duas são aceitas e representam o mesmo formato. A escolha costuma seguir o padrão da ferramenta ou da equipe. ## Termos relacionados - [Kubernetes na infraestrutura de APIs](https://conota.dev/glossario/kubernetes-na-infraestrutura-de-apis.md) - [Kubernetes Secret](https://conota.dev/glossario/kubernetes-secret.md) - [Gerenciamento de segredos](https://conota.dev/glossario/gerenciamento-de-segredos.md) - [JSON](https://conota.dev/glossario/json.md) - [Ambiente de homologação](https://conota.dev/glossario/ambiente-de-homologacao.md) - [Ambiente de produção](https://conota.dev/glossario/ambiente-de-producao.md) --- Fonte: [YAML em configurações de implantação](https://conota.dev/glossario/yaml-em-configuracoes-de-implantacao/) · Atualizado em 2026-10-22