TL;DR — Resumo Rápido

Ansible Vault criptografa segredos em playbooks com AES-256. Aprenda vault create, encrypt_string, vault IDs, integracao CI/CD e rotacao de senhas.

ANSIBLE VAULT — CRIPTOGRAFIA AES-256 DE SEGREDOS TEXTO SIMPLES (PERIGO) db_pass: supersecret api_key: abc123xyz ssl_key: -----BEGIN... Visivel no historico git! ansible-vault encrypt CRIPTOGRAFADO (SEGURO NO GIT) $ANSIBLE_VAULT;1.1;AES256 66386439653763616335616... 32663930343936663766303... 61373039636131336531353... Blob criptografado AES-256 --vault-password -file / --ask-vault -pass EXECUCAO (MEMORIA) db_pass: supersecret api_key: abc123xyz ssl_key: -----BEGIN... Descriptografado apenas em memoria A senha do vault nunca toca o disco durante a execucao — apenas o blob criptografado e armazenado no git

Armazenar senhas de banco de dados, chaves de API e chaves privadas SSL em texto simples dentro dos seus playbooks Ansible e um dos erros de seguranca mais comuns na automacao de infraestrutura. Uma vez que um segredo chega sem criptografia a um repositorio git, ele esta efetivamente comprometido — o historico do git persiste para sempre, e qualquer pessoa com acesso de leitura ao repositorio pode recupera-lo. O Ansible Vault resolve isso criptografando segredos diretamente dentro do seu repositorio usando AES-256, para que voce possa fazer commit de arquivos de credenciais criptografados junto com seus playbooks sem expor nada sensivel.

Pre-requisitos

Antes de trabalhar com este guia, voce deve ter:

  • Ansible 2.8 ou posterior instalado no seu no de controle (ansible --version para verificar)
  • Familiaridade basica com playbooks do Ansible e estrutura de diretorios group_vars
  • Um projeto Ansible existente com inventario e pelo menos um playbook
  • Um editor de texto configurado como seu $EDITOR (nano, vim ou VS Code)
  • Para secoes de CI/CD: um pipeline do GitHub Actions, GitLab CI ou Jenkins que voce possa modificar

Novo no Ansible? Leia primeiro o nosso guia de Ansible para iniciantes para configurar a estrutura do seu projeto antes de adicionar o Vault.

Por Que Segredos em Texto Simples Sao Perigosos

Cada segredo armazenado em texto simples em um repositorio git carrega o mesmo risco: exposicao. Considere o que tipicamente acaba em arquivos de variaveis Ansible sem o Vault:

  • Senhas root de banco de dados em group_vars/dbservers.yml
  • Chaves de acesso AWS em host_vars/deploy.yml
  • Credenciais SMTP em roles/notifications/defaults/main.yml
  • Conteudo de chave privada SSL em um bloco vars: dentro de um playbook

Qualquer um dos seguintes eventos expoe esses segredos imediatamente: um repositorio acidentalmente tornado publico, a conta do GitHub de um colaborador comprometida, um log de CI/CD vazado, ou um ex-funcionario insatisfeito. O Ansible Vault evita isso garantindo que os arquivos armazenados no git contenham apenas texto cifrado AES-256, nao os valores reais dos segredos.

A propria senha do vault nunca entra no seu repositorio. Ela permanece na sua memoria, em um gerenciador de senhas, ou no armazenamento de segredos do seu CI/CD — separada do codigo.

Criando Arquivos Criptografados com ansible-vault create

O subcomando create abre seu $EDITOR configurado com um arquivo vazio, permite que voce digite seus segredos e salva o arquivo criptografado ao fechar o editor:

ansible-vault create group_vars/all/vault.yml

Sera solicitado que voce insira uma nova senha de vault (duas vezes para confirmacao). O editor abre. Insira seus segredos:

vault_db_password: "Tr0ub4dor&3"
vault_db_root_password: "R4nd0mS33d#9"
vault_api_key: "sk-live-abc123def456ghi789"
vault_smtp_password: "M@ilS3rv1c3P@ss"
vault_ssl_private_key: |
  -----BEGIN RSA PRIVATE KEY-----
  MIIEpAIBAAKCAQEA3cH7...
  -----END RSA PRIVATE KEY-----

Salve e feche. O arquivo em disco agora contem apenas o blob criptografado:

$ANSIBLE_VAULT;1.1;AES256
66386439653763616335616230333934356262313032393132376163633335636630
34663437326664303537373561373039636131336531353364386530636431343739
...

Editando e visualizando arquivos criptografados

# Abrir no editor para modificacoes
ansible-vault edit group_vars/all/vault.yml

# Exibir conteudo descriptografado sem editar
ansible-vault view group_vars/all/vault.yml

# Criptografar um arquivo de texto simples existente
ansible-vault encrypt secrets.yml

# Descriptografar um arquivo de volta para texto simples (usar com cuidado)
ansible-vault decrypt secrets.yml

Criptografando Variaveis Individuais com encrypt_string

As vezes voce quer um unico segredo dentro de um arquivo nao vault — talvez porque quer o contexto circundante visivel sem descriptografar tudo. O subcomando encrypt_string gera um valor criptografado que voce pode colar diretamente em qualquer arquivo YAML:

ansible-vault encrypt_string --name 'vault_stripe_key' 'sk_live_abc123xyz'

Saida:

vault_stripe_key: !vault |
  $ANSIBLE_VAULT;1.1;AES256
  66653465346564383664396631316639
  37313739623731633864333736396230
  ...

Cole este bloco diretamente em qualquer arquivo YAML de variaveis. O Ansible o descriptografa de forma transparente em tempo de execucao, da mesma forma que lida com um arquivo vault completamente criptografado.

Quando usar encrypt_string vs arquivos criptografados:

AbordagemUsar quando
ansible-vault create vault.ymlMaioria dos casos — mantem segredos organizados, facil de auditar
encrypt_stringSegredo unico em arquivo principalmente simples; segredos inline em roles
Playbook inteiro criptografadoRaramente necessario; prejudica a legibilidade

Vault IDs: Multiplas Senhas para Diferentes Conjuntos de Segredos

Os Vault IDs permitem rotular conteudo criptografado para que o Ansible saiba qual senha se aplica. Isso e essencial quando staging e producao usam senhas diferentes, ou quando voce quer rotacionar uma senha sem re-criptografar tudo.

Criptografar com um vault ID

# Criptografar com um vault ID nomeado
ansible-vault create --vault-id prod@prompt group_vars/production/vault.yml
ansible-vault create --vault-id staging@prompt group_vars/staging/vault.yml

# Ou apontar para um arquivo de senha
ansible-vault create --vault-id prod@~/.vault_prod group_vars/production/vault.yml

Descriptografar com multiplos vault IDs

ansible-playbook site.yml \
  --vault-id prod@~/.vault_prod \
  --vault-id staging@~/.vault_staging

O Ansible faz a correspondencia automaticamente de cada bloco criptografado com seu rotulo de vault ID e usa a senha correta. O conteudo criptografado sem um vault ID explicito padroniza para o rotulo default.

Integracao CI/CD com —vault-password-file

Prompts interativos de senha bloqueiam pipelines automatizados. A flag --vault-password-file aceita um caminho para um arquivo contendo apenas a senha do vault, permitindo execucao totalmente nao interativa.

Exemplo com GitHub Actions

# .github/workflows/deploy.yml
name: Deploy
on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Instalar Ansible
        run: pip install ansible

      - name: Gravar senha vault em arquivo
        run: echo "${{ secrets.ANSIBLE_VAULT_PASSWORD }}" > ~/.vault_pass

      - name: Executar playbook
        run: |
          ansible-playbook -i inventory/production site.yml \
            --vault-password-file ~/.vault_pass

      - name: Remover arquivo de senha vault
        if: always()
        run: rm -f ~/.vault_pass

Armazene ANSIBLE_VAULT_PASSWORD nos segredos do GitHub Actions do repositorio (Configuracoes → Segredos → Actions). A senha do vault nunca aparece nos logs porque o GitHub mascara valores de segredos.

Exemplo com GitLab CI

# .gitlab-ci.yml
deploy:
  script:
    - echo "$ANSIBLE_VAULT_PASSWORD" > ~/.vault_pass
    - ansible-playbook -i inventory/production site.yml --vault-password-file ~/.vault_pass
    - rm -f ~/.vault_pass
  variables:
    ANSIBLE_VAULT_PASSWORD: $ANSIBLE_VAULT_PASSWORD

Usando um script de senha vault

Para senhas de vault dinamicas (obtidas do HashiCorp Vault, AWS Secrets Manager ou Azure Key Vault em tempo de execucao), crie um script executavel que retorne a senha:

#!/bin/bash
# ~/.get_vault_pass.sh
aws secretsmanager get-secret-value \
  --secret-id ansible/vault-password \
  --query SecretString \
  --output text
chmod +x ~/.get_vault_pass.sh
ansible-playbook site.yml --vault-password-file ~/.get_vault_pass.sh

Melhores Praticas: Organizando Variaveis Vault

O padrao mais sustentavel separa seus arquivos de variaveis em dois arquivos paralelos por grupo:

group_vars/
  all/
    vars.yml      # variaveis simples + referencias a variaveis vault_
    vault.yml     # criptografado, apenas variaveis com prefixo vault_
  production/
    vars.yml
    vault.yml
  staging/
    vars.yml
    vault.yml

group_vars/all/vars.yml — texto simples, seguro para inspecionar no git:

# group_vars/all/vars.yml
db_host: "db.internal.example.com"
db_port: 5432
db_name: "myapp_prod"
db_password: "{{ vault_db_password }}"    # referencia, nao o valor

api_endpoint: "https://api.stripe.com/v1"
stripe_key: "{{ vault_stripe_key }}"

smtp_host: "smtp.sendgrid.net"
smtp_user: "apikey"
smtp_password: "{{ vault_smtp_password }}"

group_vars/all/vault.yml — criptografado, todas com prefixo vault_:

# group_vars/all/vault.yml  (este arquivo esta criptografado em disco)
vault_db_password: "Tr0ub4dor&3"
vault_stripe_key: "sk_live_abc123"
vault_smtp_password: "SG.abc123xyz"

Beneficios deste padrao:

  • Playbooks referenciam nomes legiveis (db_password), nao variaveis vault diretamente
  • git diff mostra mudancas na estrutura de vars.yml sem precisar da senha vault
  • Voce pode auditar quais variaveis existem no arquivo vault por nome (execute ansible-vault view)
  • Novos membros da equipe podem ler vars.yml para entender a estrutura de variaveis sem acesso ao vault

Rotacionando Senhas do Vault com rekey

Rotacionar a senha do vault e uma operacao de um unico comando:

ansible-vault rekey group_vars/all/vault.yml

Sera solicitada a senha atual do vault, depois voce devera inserir e confirmar a nova senha. O arquivo e re-criptografado no lugar. Nenhum segredo e descriptografado para disco durante este processo.

Para multiplos arquivos vault de uma vez:

# Re-criptografar todos os arquivos vault do projeto
find . -name "vault.yml" -exec ansible-vault rekey {} \;

# Ou com --new-vault-password-file para rotacao nao interativa
ansible-vault rekey \
  --vault-password-file ~/.old_vault_pass \
  --new-vault-password-file ~/.new_vault_pass \
  group_vars/all/vault.yml group_vars/production/vault.yml

Apos o rekey, atualize o armazenamento de segredos do seu CI/CD com a nova senha antes da proxima execucao do pipeline.

Usando Ansible Vault com AWX e Semaphore

AWX / Ansible Tower

O AWX tem um tipo de credencial nativo para Ansible Vault. Crie uma credencial do tipo Vault (Configuracoes → Credenciais → Adicionar → Vault), insira a senha do vault e atribua-a ao seu template de trabalho. O AWX gerencia a passagem da senha de forma segura sem expola na saida do trabalho.

Para multiplos vault IDs no AWX, crie uma credencial Vault por ID e atribua todas elas ao template de trabalho.

Semaphore UI

O Semaphore armazena senhas vault em seu Armazenamento de Chaves. Navegue ate Key Store → Nova Chave, selecione o tipo Senha, insira sua senha vault e nomeie-a (ex. vault-production). Ao criar um template de tarefa, selecione a chave vault no campo Vault Password.

O Semaphore passa a chave para o Ansible por meio de um arquivo temporario que e excluido apos a execucao do playbook, seguindo o mesmo modelo de seguranca da abordagem de arquivo de senha no CI/CD.

Comparacao: Ansible Vault vs Alternativas

FerramentaCriptografiaNativo no gitCI/CDSegredos dinamicosComplexidade
Ansible VaultAES-256Sim — arquivos no repoArquivo de senhaVia scriptBaixa
HashiCorp VaultAES-256-GCMNao — servico externoAPI + tokenSim (leases)Alta
SOPSAES-256 / PGP / KMSSim — valores criptografadosChave KMSNaoMedia
git-cryptAES-256Sim — transparenteChave GPGNaoMedia

Escolha o Ansible Vault quando seus segredos precisam ser acessiveis apenas por playbooks Ansible e voce nao quer infraestrutura adicional. Escolha o HashiCorp Vault quando precisar de segredos dinamicos, expiracao granular de contratos ou acesso de segredos para multiplas aplicacoes. O SOPS e util quando voce precisa de arquivos criptografados lidos por ferramentas alem do Ansible (Terraform, Helm). O git-crypt funciona bem para arquivos criptografados gerais em um repo, mas carece de integracoes especificas para Ansible.

Cenario Real: Credenciais de BD e Chaves de API em Multiplos Ambientes

Voce gerencia tres ambientes (desenvolvimento, staging, producao) para uma aplicacao web. Cada ambiente tem um banco de dados PostgreSQL, uma chave de API do Stripe e uma senha SMTP do SendGrid. O desenvolvimento usa senhas locais fracas; a producao usa credenciais fortes gerenciadas pela equipe de seguranca.

Estrutura de diretorios:

projeto/
  ansible.cfg
  inventory/
    development/hosts
    staging/hosts
    production/hosts
  group_vars/
    all/
      vars.yml         # estrutura de variaveis compartilhada
    development/
      vars.yml         # configuracao de dev nao sensivel
      vault.yml        # segredos de dev criptografados (senha separada)
    staging/
      vars.yml
      vault.yml        # segredos de staging criptografados
    production/
      vars.yml
      vault.yml        # segredos de producao criptografados (mais restritos)
  playbooks/
    deploy.yml
    db_setup.yml

O vault.yml de cada ambiente usa um vault ID e senha separados, gerenciados pela equipe apropriada:

# Criar vault de desenvolvimento (senha da equipe de desenvolvimento)
ansible-vault create --vault-id dev@prompt group_vars/development/vault.yml

# Criar vault de staging (senha da equipe QA)
ansible-vault create --vault-id staging@prompt group_vars/staging/vault.yml

# Criar vault de producao (senha da equipe de operacoes)
ansible-vault create --vault-id prod@prompt group_vars/production/vault.yml

Pipeline de implantacao (apenas producao):

ansible-playbook -i inventory/production playbooks/deploy.yml \
  --vault-id prod@~/.vault_prod

A senha do vault de producao nunca e compartilhada com desenvolvedores ou QA. Se o vault de staging for comprometido, os segredos de producao nao sao afetados porque usam uma senha completamente separada.

Armadilhas e Casos Extremos

Esquecer a senha do vault e permanente. Nao ha mecanismo de recuperacao. Os dados criptografados sao perdidos. Armazene as senhas vault em um gerenciador de senhas e em um segredo CI/CD imediatamente apos a criacao.

Evite --ask-vault-pass em automacao. Bloqueia pipelines e requer entrada interativa. Sempre use --vault-password-file em qualquer contexto nao interativo.

ansible.cfg pode definir padroes de vault. Adicione vault_password_file = ~/.vault_pass ao seu ansible.cfg para evitar especifica-lo em cada comando.

Arquivos vault.yml nunca devem estar no .gitignore. O objetivo e fazer commit deles criptografados. Se voce sentir a tentacao de ignorar um arquivo vault no git, provavelmente o deixou em texto simples por acidente.

Arquivos criptografados ainda aparecem como alterados no git ao serem re-criptografados identicamente. AES-256 no modo CBC produz texto cifrado diferente para o mesmo texto simples a cada vez. Nao execute ansible-vault encrypt em arquivos sem alteracoes, pois isso polui o historico git.

Arquivos binarios tambem podem ser criptografados. Certificados SSL, arquivos keystore e chaves SSH em formato binario podem ser criptografados com ansible-vault encrypt. O Ansible os descriptografa para um arquivo temporario antes de passar o caminho para o modulo relevante.

Solucao de Problemas

Erro “Decryption failed” (falha na descriptografia):

# Verificar se a senha esta correta visualizando o arquivo
ansible-vault view group_vars/all/vault.yml

# Verificar se o vault ID corresponde se usar vault IDs
ansible-vault view --vault-id prod@prompt group_vars/production/vault.yml

O playbook executa sem solicitar a senha vault e usa valor incorreto:

Verifique se vault_password_file esta definido em ansible.cfg. Se o arquivo nao existir ou estiver vazio, o Ansible ignora silenciosamente a descriptografia do vault. Adicione --ask-vault-pass temporariamente para confirmar.

Erro “File is not encrypted” (arquivo nao criptografado) ao editar:

O arquivo esta armazenado como texto simples. Criptografe primeiro: ansible-vault encrypt filename.yml.

A variavel mostra a string literal {{ vault_db_password }} na saida da tarefa:

A variavel e referenciada mas o arquivo vault nao foi carregado. Verifique se o arquivo vault esta em um caminho que o Ansible carrega automaticamente (group_vars/, host_vars/) ou inclua-o explicitamente com vars_files: no playbook.

O pipeline CI/CD mostra a senha vault nos logs:

Nunca passe a senha vault como argumento de linha de comando. Sempre grave em um arquivo primeiro. Confirme que seu provedor CI mascara a variavel secreta na saida do log.

Resumo

  • Armazene todos os segredos em arquivos group_vars/*/vault.yml criptografados com ansible-vault create
  • Use a convencao de prefixo vault_ para distinguir variaveis criptografadas das simples
  • Referencie variaveis vault de arquivos vars.yml simples usando {{ vault_varname }} para que os playbooks permaneçam legiveis
  • Use encrypt_string apenas para segredos individuais inline, nao como padrao principal de segredos
  • Use vault IDs para manter senhas separadas para diferentes ambientes ou equipes
  • Integre com CI/CD usando --vault-password-file e armazene a senha no seu gerenciador de segredos
  • Rotacione senhas vault com ansible-vault rekey e atualize os segredos CI/CD imediatamente
  • Nunca armazene senhas vault em arquivos que sao enviados para o git
  • AWX e Semaphore tem suporte nativo de credenciais vault — prefira isso a solucoes alternativas

Artigos Relacionados