Securing Sensitive Data in Ansible with Vault

Preventing Secret Exposure in Version Control

Storing passwords, API keys, or SSL certificates in plaintext within Ansible playbooks or inventory files creates a critical security vulnerability, especially when using version control systems like Git. The solution is Ansible Vault, which uses AES-256 symmetric encryption to protect sensitive data while allowing it to remain part of your automation repository.

The primary takeaway is that Ansible Vault allows you to encrypt either entire files or specific variable strings. This ensures that secrets are only decrypted in memory during runtime and are never stored as plaintext on disk in your repository.

Prerequisites

• Ansible installed (version 2.9 or later recommended).
• A defined password for your vault (this must be kept secure and separate from the code).
• Sudo or administrative privileges on the control node to manage files.

Method 1: Encrypting Entire Variable Files

Use this method when a file contains exclusively sensitive data, such as a secrets.yml file used for database credentials.

1. Create the plaintext file: Define your variables in a standard YAML format.

   # secrets.yml
   db_password: "SuperSecretPassword123"
   api_key: "abc-123-def-456"

2. Encrypt the file: Run the following command on the control node. You will be prompted to enter a new vault password.

   ansible-vault encrypt secrets.yml

3. Verify encryption: Use cat to ensure the file is now ciphertext.

   cat secrets.yml

   Expected result: The output should begin with $ANSIBLE_VAULT;1.1;AES256 followed by an encrypted block.

Method 2: Encrypting Individual Strings (Inline Vault)

Inline encryption is preferred when you want to keep the structure of your variable files human-readable while only hiding specific values.

1. Encrypt the specific value: Run the encrypt_string command. Use the --name flag to assign the variable name directly.

   ansible-vault encrypt_string 'SuperSecretPassword123' --name 'db_password'

2. Integrate into YAML: Copy the resulting encrypted block and paste it into your group_vars or host_vars file.

   # group_vars/all.yml
   db_user: admin
   db_password: !vault | 
             $ANSIBLE_VAULT;1.1;AES256
             3665... (encrypted data)

Executing Playbooks with Vaulted Data

Because the data is encrypted, Ansible cannot resolve these variables unless provided with the password at runtime.

Option A: Manual Password Entry

Run the playbook and prompt for the password manually. This is safest for local development.

ansible-playbook site.yml --ask-vault-pass

Option B: Using a Password File (Automation)

For CI/CD pipelines, store the password in a secure file on the control node (outside the repository) and reference it in ansible.cfg.

1. Create the password file:

   echo "your_vault_password" > ~/.vault_pass.txt
       chmod 600 ~/.vault_pass.txt

2. Configure ansible.cfg: Add the following line to your configuration file:

   [defaults]
   vault_password_file = ~/.vault_pass.txt

Diagnostic Checks and Verification

Test Scenario	Action	Expected Result
Encryption Check	cat secrets.yml	Ciphertext starting with $ANSIBLE_VAULT
Access Denial	ansible-playbook site.yml (without pass)	Failure: "Decryption failed" or "Vault password required"
Successful Run	ansible-playbook site.yml --ask-vault-pass	Tasks complete; variables resolved in memory

Limitations and Recovery

• No Recovery: If the vault password is lost, the data is permanently unrecoverable. There is no "forgot password" mechanism for AES-256 symmetric encryption.
• Performance: Decrypting large numbers of inline strings can slightly increase playbook startup time.
• Security Risk: Never commit the vault_password_file to Git. Add it to your .gitignore immediately.

Rollback: Decrypting Files

If you need to return a file to plaintext for auditing or migration, use the decrypt command on the control node:

ansible-vault decrypt secrets.yml

Risk: Once decrypted, the file is in plaintext. Ensure you do not commit this version to your version control system.