Ansible Vault

Ansible Vault encrypts sensitive variables (passwords, license keys, etc.) so they can be safely committed to the repository. This project keeps its encrypted secrets in group_vars/all/vault.yml, where they are loaded automatically for every host.

Define secrets as lowercase Ansible variables in the vault (e.g. server_admin_password, microsoft_sql_sa_password). These take precedence over the equivalent uppercase environment variables (e.g. SERVER_ADMIN_PASSWORD). Use a secure password generator to create strong passwords.

Create

Create the vault file with the secrets you want to encrypt:

cat <<EOF > group_vars/all/vault.yml
server_admin_user: Administrator
server_admin_password: USE_PASSWORD_GENERATOR
microsoft_sql_sa_password: USE_PASSWORD_GENERATOR
microsoft_sql_spadmin_password: USE_PASSWORD_GENERATOR
microsoft_sql_spuser_password: USE_PASSWORD_GENERATOR
EOF

Encrypt

Encrypt the file in place. You will be prompted for a vault password:

ansible-vault encrypt group_vars/all/vault.yml

An encrypted file begins with a header like $ANSIBLE_VAULT;1.1;AES256 and is safe to commit.

Edit

Edit an encrypted file without manually decrypting it. The file is decrypted into your editor and re-encrypted on save:

ansible-vault edit group_vars/all/vault.yml

View

Print the decrypted contents to the terminal without opening an editor:

ansible-vault view group_vars/all/vault.yml

Rekey

Change the password protecting the file:

ansible-vault rekey group_vars/all/vault.yml

Encrypt a Single String

To store an encrypted value inline (e.g. directly in host_vars) rather than encrypting an entire file:

ansible-vault encrypt_string 'USE_PASSWORD_GENERATOR' --name 'microsoft_sql_sa_password'

Paste the resulting !vault block into the relevant YAML file.

Password File

Rather than entering the vault password interactively each run, store it in a file. This file is already listed in .gitignore and must never be committed:

cat <<EOF > ansible_vault.txt
Loc@lPassw0rd
EOF

Point ansible.cfg at the password file so it is used automatically:

[defaults]
vault_password_file = ansible_vault.txt

Running Playbooks

With vault_password_file configured in ansible.cfg, playbooks run without any extra flags. If you have not configured a password file, supply the password at run time instead:

ansible-playbook playbooks/multipurpose-sql.yml --ask-vault-pass

Protect the vault password

Never commit ansible_vault.txt or the unencrypted vault.yml. Store the vault password in a secrets manager (e.g. 1Password) and rotate it with ansible-vault rekey if it is exposed.