Sensitive Data -- Ansible Vault¶

Passwords and secrets should not be in plain text. Ansible Vault encrypts them.

# Create a vault password file (so you don't type it every time)
nano ~/ansible/.vault_pass
# Type a password, save
chmod 600 ~/ansible/.vault_pass

Using an editor rather than echo "password" > .vault_pass keeps the password out of your shell history.

Add to ansible.cfg under [defaults]:

vault_password_file = .vault_pass

Create encrypted variables:

# Create an encrypted vars file for secrets
ansible-vault create inventory/group_vars/vault.yml

Put your secrets in there:

---
vault_nas_samba_password: "your-samba-password"
vault_borg_passphrase: "generate-a-long-random-string"
vault_vaultwarden_admin_token: "generate-a-long-random-string"
vault_cloudflared_token: "your-cloudflare-tunnel-token"
vault_forgejo_secret_key: "generate-a-long-random-string"
vault_paperless_db_password: "generate-a-long-random-string"

Reference vault variables in other files with:

nas_samba_password: "{{ vault_nas_samba_password }}"

A vault file named vault.yml doesn't match any inventory group, so Ansible won't auto-load it from group_vars/. Load it explicitly in the playbook:

vars_files:
  - ../inventory/group_vars/vault.yml

(The worked example's playbooks/base.yml does exactly this.)

Commands (run from ~/ansible/):

# Create an encrypted file (opens your $EDITOR, encrypts on save)
ansible-vault create inventory/group_vars/vault.yml

# Edit the vault file (decrypts, opens your $EDITOR, re-encrypts)
ansible-vault edit inventory/group_vars/vault.yml

# View without editing (decrypts to stdout)
ansible-vault view inventory/group_vars/vault.yml

# Re-encrypt with a new password
ansible-vault rekey inventory/group_vars/vault.yml

To add a new secret, ansible-vault edit the file, add a new vault_-prefixed key, and reference it in your roles or templates as {{ vault_some_new_secret }}.

Encrypting a single value¶

You don't have to encrypt a whole file — you can drop one encrypted string into an otherwise-plaintext vars file. Useful for a single secret alongside normal config.

ansible-vault encrypt_string 'super-secret-token' --name 'vault_api_token'

It prints a block you paste straight into a YAML file:

vault_api_token: !vault |
      $ANSIBLE_VAULT;1.1;AES256
      66386439653...
      33613463...

Ansible decrypts it automatically at runtime, just like a fully-encrypted file.

If you don't use a password file¶

Without vault_password_file in ansible.cfg, pass the password at runtime:

ansible-playbook playbooks/base.yml --ask-vault-pass

Best practices¶

.vault_pass
*.vault_pass

• Prefix vaulted variables with vault_ (e.g. vault_nas_samba_password), then map them to normal names in group_vars/all.yml: nas_samba_password: "{{ vault_nas_samba_password }}". This makes it obvious at a glance which values are secret and keeps no_log easy to reason about.
• Add no_log: true to tasks that handle secrets so they don't print to the terminal or logs.
• Store the vault password itself in a real password manager (e.g. Vaultwarden).

Ref: Ansible — Protecting sensitive data with Vault · Encrypting single values