Vault – secrets management¶

Sensitive variables are stored with Ansible Vault. The repo is pre-configured to read the password from .ansible_vault_pass (set in ansible.cfg). Never commit that file.

Setup¶

echo "your-vault-password" > .ansible_vault_pass
chmod 600 .ansible_vault_pass

Where vault files live¶

group_vars/all/vault.yml                          ← global encrypted secrets
inventories/prod/group_vars/db.vault.yml          ← DB group secrets
inventories/prod/group_vars/web.vault.yml         ← web group secrets (Cloudflare tokens)
inventories/prod/host_vars/<host>/vault.yml       ← per-host secrets

Follow the same layout for inventories/stage/.

Use *.vault.yml.example files as templates – they show the required keys with empty values.

View a vault file¶

ansible-vault view inventories/prod/group_vars/db.vault.yml

Edit a vault file¶

ansible-vault edit inventories/prod/host_vars/bk-db-01/vault.yml

Set your preferred editor first:

export EDITOR=vim   # or nano, "code -w", etc.

Create a new vault file¶

ansible-vault create inventories/prod/group_vars/web.vault.yml

Add variables following the vault_ prefix convention:

vault_mariadb_root_password: "change-me"
vault_cloudflared_tunnel_token: "eyJ..."

Encrypt an existing plain-text file¶

If you started with an unencrypted file and want to encrypt it in place:

ansible-vault encrypt inventories/prod/group_vars/db.yml

Prefer keeping sensitive values in *.vault.yml files and non-sensitive config in plain *.yml files. Mixing them makes it harder to audit what is and isn't encrypted.

Encrypt a single value¶

Useful when you need to embed one secret inside an otherwise plain file:

ansible-vault encrypt_string --name vault_mariadb_app_password 'SuperSecret123!'

Paste the output directly into a YAML file. Reference it from a role variable:

# host_vars/myhost/main.yml
mariadb_app_password: "{{ vault_mariadb_app_password }}"

# host_vars/myhost/vault.yml (encrypted block)
vault_mariadb_app_password: !vault |
  $ANSIBLE_VAULT;1.1;AES256
  ...

Change the vault password (rekey)¶

1. Update .ansible_vault_pass with the new password.
2. Rekey every vault file:

ansible-vault rekey \
  group_vars/all/vault.yml \
  inventories/prod/group_vars/db.vault.yml \
  inventories/prod/group_vars/web.vault.yml \
  inventories/prod/host_vars/bk-db-01/vault.yml

You will be prompted for the old password and then the new one (taken from .ansible_vault_pass).

Running playbooks with vault¶

With .ansible_vault_pass in place, no extra flags are needed:

ansible-playbook -i inventories/prod/hosts.yml db.yml --limit bk-db-01

If you want a password prompt instead:

ansible-playbook -i inventories/prod/hosts.yml db.yml --ask-vault-pass

Best practices¶

• Always prefix secret variable names with vault_ (e.g. vault_mariadb_root_password).
• Keep *.vault.yml and plain *.yml files separate.
• Add no_log: true to any task that might print secret values.
• Never commit .ansible_vault_pass or any unencrypted secret to Git.