How to Encrypt and Manage Secrets in Ansible Playbooks Using Ansible Vault with Vault Ids and Password Files

ByAkensai

Knowing how to encrypt and manage secrets in Ansible playbooks using Ansible Vault with Vault IDs and password files is one of the most important skills for any system administrator. Hardcoded passwords and API keys in plain-text playbooks are a serious security risk. Ansible Vault solves this problem. It lets you encrypt sensitive data directly inside your playbooks and variable files. In this tutorial, you will learn how to create encrypted secrets, assign Vault IDs for multi-environment setups, and use password files to automate decryption without manual prompts. By the end, you will have a solid, repeatable workflow for keeping credentials out of your source code.

Prerequisites and Requirements for Encrypting Ansible Secrets

Before you start, make sure you have the following in place.

Required software:

  • Ansible 2.4 or later installed on your control node
  • Python 3.6 or later
  • A Linux-based control node (Ubuntu 20.04 or later is recommended)
  • SSH access to at least one managed host

Assumed knowledge:

  • Basic Ansible playbook structure
  • Familiarity with YAML syntax
  • Comfort working in the Linux terminal

Estimated time: 30–45 minutes.

You can verify your Ansible version with this command:

ansible --version

If Ansible is not installed, run the following on Ubuntu:

sudo apt update
sudo apt install ansible -y

For full installation options, check the official Ansible installation guide.

How to Encrypt and Manage Secrets in Ansible Playbooks Using Vault IDs

For a related walkthrough, see: How to Configure Ufw Firewall on Ubuntu 24.04

This section walks you through the full process. You will create password files, encrypt variables, and wire everything together in a playbook.

Step 1: Create your Vault password files.

A password file stores your Vault password as plain text. Ansible reads it automatically. This removes the need to type a password every time you run a playbook.

Create a directory to store your password files:

mkdir -p ~/.vault_passwords
chmod 700 ~/.vault_passwords

Now create a password file for your development environment:

echo "MyDevVaultPassword123!" > ~/.vault_passwords/dev.txt
chmod 600 ~/.vault_passwords/dev.txt

Create a second one for production:

echo "MyProdVaultPassword456!" > ~/.vault_passwords/prod.txt
chmod 600 ~/.vault_passwords/prod.txt

Never commit these files to version control. Add them to your .gitignore immediately.

Step 2: Create encrypted variable files using Vault IDs.

Vault IDs let you label encrypted content. This is useful when you manage multiple environments. The format is label@source.

Create an encrypted variable file for your development secrets:

ansible-vault create --vault-id dev@~/.vault_passwords/dev.txt group_vars/all/dev_secrets.yml

Your default editor opens. Add your secrets in YAML format:

db_password: "super_secret_dev_password"
api_key: "dev_api_key_abc123"

Save and close the file. Ansible encrypts it automatically using the dev Vault ID.

Now create the production secrets file:

ansible-vault create --vault-id prod@~/.vault_passwords/prod.txt group_vars/all/prod_secrets.yml

Add your production credentials and save the file.

Step 3: Encrypt an existing variable file.

If you already have a plain-text variable file, encrypt it in place:

ansible-vault encrypt --vault-id dev@~/.vault_passwords/dev.txt group_vars/all/existing_vars.yml

You can view the encrypted content at any time without decrypting the file permanently:

ansible-vault view --vault-id dev@~/.vault_passwords/dev.txt group_vars/all/dev_secrets.yml

Step 4: Encrypt a single string value.

Sometimes you only need to encrypt one variable inside a larger file. Use ansible-vault encrypt_string for this:

ansible-vault encrypt_string --vault-id prod@~/.vault_passwords/prod.txt 'TopSecretPassword' --name 'db_root_password'

The output looks like this:

db_root_password: !vault |
          $ANSIBLE_VAULT;1.2;AES256;prod
          61386134653665...

Paste this block directly into any YAML variable file or playbook.

Step 5: Reference encrypted variables in your playbook.

Create a simple playbook that uses your encrypted secrets:

---
- name: Deploy application secrets
  hosts: webservers
  vars_files:
    - group_vars/all/dev_secrets.yml
  tasks:
    - name: Print database password (for testing only)
      ansible.builtin.debug:
        msg: "DB Password is {{ db_password }}"

Remove the debug task before using this in production. It is only here to confirm decryption works.

Step 6: Run your playbook with multiple Vault IDs.

When your playbook uses secrets from different environments, pass multiple Vault IDs at runtime:

ansible-playbook site.yml 
  --vault-id dev@~/.vault_passwords/dev.txt 
  --vault-id prod@~/.vault_passwords/prod.txt

Ansible automatically matches each encrypted block to the correct Vault ID label.

Step 7: Edit or rekey an encrypted file.

To update an encrypted file without decrypting it first:

ansible-vault edit --vault-id dev@~/.vault_passwords/dev.txt group_vars/all/dev_secrets.yml

To change the encryption password for a file, use the rekey command:

ansible-vault rekey --vault-id dev@~/.vault_passwords/dev.txt 
  --new-vault-id dev@~/.vault_passwords/new_dev.txt 
  group_vars/all/dev_secrets.yml

This is useful when rotating credentials after a security incident.

Troubleshooting Common Errors When Managing Ansible Vault Secrets

Even experienced admins run into problems. Here are the most common issues and how to fix them.

Error: “Decryption failed”
This usually means the wrong password file was used. Double-check that the Vault ID label in the command matches the label used when the file was created. Labels are case-sensitive.

Error: “ERROR! A vault password or secret is required”
You forgot to pass the --vault-id flag. Always include it when running playbooks that contain encrypted variables.

Password file permissions warning
If Ansible warns about insecure permissions, run:

chmod 600 ~/.vault_passwords/dev.txt

Encrypted strings not decrypting in playbooks
Make sure the !vault block is indented correctly in YAML. A single indentation error breaks decryption. Use a YAML linter to check your files.

Accidentally committed a password file
Remove it from Git history immediately using git filter-repo or BFG Repo Cleaner. Then rotate all affected passwords. For guidance on securing Git repositories, see the GitHub guide on removing sensitive data.

Conclusion

You now have a working system to encrypt and manage secrets in Ansible playbooks using Ansible Vault with Vault IDs and password files. You created environment-specific password files, encrypted full variable files and individual strings, and ran playbooks that automatically decrypt secrets at runtime. This approach keeps credentials out of your source code without adding manual steps to your workflow. From here, consider storing your Vault password files in a secrets manager like HashiCorp Vault or AWS Secrets Manager for even tighter security. You can also explore using a custom Vault password script instead of a static file. Knowing how to encrypt and manage secrets in Ansible playbooks using Ansible Vault with Vault IDs and password files will protect your infrastructure as your team and automation grow.

Similar Posts