Ansible Vault Cheatsheet: Mastering Secure Configuration Management

What is Ansible Vault?

Ansible Vault is a feature in Ansible that allows you to encrypt and protect sensitive data (such as passwords, API keys, etc.) that needs to be included in your Ansible projects.

Why Use a Vault Password?

Ansible Vault uses a password to encrypt and decrypt files. This is useful for keeping sensitive information secure, as it allows you to store encrypted content in version control systems without exposing sensitive data.

Benefits of Using a Vault Password:

• Security: Keeps sensitive data encrypted and safe.
• Version Control: Encrypted files can be safely pushed to repositories like Git.
• Ease of Use: Once configured, using vault-encrypted files in playbooks is simple.

---

Example Use Case: Storing Database Credentials Securely

Let's assume we want to store database credentials (username and password) in a secure file for use in an Ansible playbook.

---

1. Create a New Vault File

To create a new encrypted vault file that stores database credentials:

ansible-vault create db_credentials.yml

This command will:

• Prompt for a password (which will be used for encryption).
• Open the default text editor (e.g., Vim) where you can add your sensitive data.

Add the following content to db_credentials.yml (sample database credentials):

db_user: admin
db_password: secure_password123

Once you save and exit, the file will be encrypted.

---

2. Edit an Existing Vault File

To edit the vault file (e.g., if you need to update the database password), use the ansible-vault edit command:

ansible-vault edit db_credentials.yml

This will:

• Prompt for the vault password to decrypt the file.
• Open the file in your default editor, allowing you to make changes.

Update the password (or any other value), then save and exit to re-encrypt the file automatically.

---

3. Encrypting Individual Strings

Sometimes you may want to encrypt just a single string rather than an entire file. This is useful for storing sensitive data in otherwise unencrypted files.

ansible-vault encrypt_string 'secret_password' --name 'db_password'

This will output an encrypted version of 'secret_password' that you can paste into a YAML file:

db_password: !vault |
          $ANSIBLE_VAULT;1.1;AES256
          66386439653236336462626566653063336164663966303231363934653561363132333162393533
          3661643066663534383564343537343334633431346664310a316465383138636532343463633236
          37623064636339623565626265353466613262366165396233396465636135353863376136393132
          3938626664623838350a653839636539636465626565316130383833623733326132366265376461
          6233

---

4. Using Multiple Vault Passwords

When working with different environments (e.g., development and production), you might want to use different vault passwords for each.

• 1. Create vault-encrypted files with different IDs:

ansible-vault create --vault-id dev@prompt secret_dev.yml

ansible-vault create --vault-id prod@prompt secret_prod.yml

• 2. Use these vault IDs in your playbook:

ansible-playbook site.yml --vault-id dev@prompt --vault-id prod@prompt

This allows you to use different passwords for different environments, enhancing security.

---

5. View the Contents of a Vault File

To view the encrypted file without editing it, use the ansible-vault view command:

ansible-vault view db_credentials.yml

This command will:

• Prompt for the vault password.
• Display the decrypted content of the vault file.

This is useful when you only need to see the values without making changes.

---

6. Encrypt an Existing File

If you already have a plain-text file and want to encrypt it using Ansible Vault, you can use:

ansible-vault encrypt plain_file.yml

This will:

• Encrypt the contents of plain_file.yml and overwrite the file with its encrypted version.

---

7. Decrypt an Encrypted Vault File

If you need to decrypt a vault file and revert it to plain text, you can use:

ansible-vault decrypt db_credentials.yml

This will:

• Prompt for the vault password.
• Decrypt the file, leaving it as plain text.

---

8. Running a Playbook with Encrypted Variables

If your playbook includes variables from a vault-encrypted file (like db_credentials.yml), you can run the playbook by providing the vault password:

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

Alternatively, you can specify a password file for automation purposes:

ansible-playbook site.yml --vault-password-file /path/to/vault_pass.txt

Adding and Using Vault-Encrypted Variables in a Playbook

To use the encrypted variables from db_credentials.yml in your playbook:

• 1. Include the vault file in your playbook:

Add the following line at the beginning of your playbook:

   - name: Include database credentials
     include_vars:
       file: db_credentials.yml

• 2. Use the decrypted variables in your tasks:

Once included, you can use the variables like any other Ansible variable:

   - name: Configure database connection
     mysql_user:
       name: "{{ db_user }}"
       password: "{{ db_password }}"
       priv: "*.*:ALL"
       host: "localhost"
       state: present

• 3. Full playbook example:

   ---
   - hosts: database_servers
     vars_files:
       - db_credentials.yml

     tasks:
       - name: Configure database connection
         mysql_user:
           name: "{{ db_user }}"
           password: "{{ db_password }}"
           priv: "*.*:ALL"
           host: "localhost"
           state: present

In this example, we use vars_files to include the encrypted file directly in the play.

Remember to run this playbook with either --ask-vault-pass or --vault-password-file as mentioned earlier.

---

9. Specifying Vault Password in ansible.cfg

To avoid entering the vault password every time, you can specify the vault password file in your ansible.cfg:

[defaults]
vault_password_file = /path/to/vault_pass.txt

This is especially useful for automation purposes, but be cautious about the security implications of storing your vault password on disk.

---

10. Changing the Encryption Key (Rekeying)

If you need to change the encryption key of a vault-encrypted file:

ansible-vault rekey secret.yml

This will prompt you for the current vault password and then ask for a new password. It's a good practice to periodically rekey your vault-encrypted files for security reasons.

---

Best Practices for Ansible Vault

1. Use a Strong Vault Password: Always choose a strong and unique password to protect your encrypted files.

2. Version Control Safety: It is safe to store vault-encrypted files in version control, but never commit the vault password or password file to version control.

3. Separate Vault Files: If possible, separate sensitive data into dedicated vault files to minimise the exposure of credentials across different environments or teams.

4. Use --vault-password-file for Automation: When automating playbook runs in CI/CD pipelines (e.g., GitLab CI), use the --vault-password-file option to avoid manual password entry.

5. Restrict File Access: Ensure that only authorised users and systems have access to the vault password file and the encrypted files.

6. Environment-Specific Vaults: Use separate vaults for different environments (development, staging, production) to ensure proper security segregation.

---

Summary of Commands

Action	Command
Create a new encrypted file	ansible-vault create secret.yml
Edit an existing encrypted file	ansible-vault edit secret.yml
View an encrypted file without editing	ansible-vault view secret.yml
Encrypt an existing file	ansible-vault encrypt existing_file.yml
Decrypt an encrypted file	ansible-vault decrypt secret.yml
Encrypt a string	ansible-vault encrypt_string 'secret_password' --name 'db_password'
Create encrypted files with different vault IDs	ansible-vault create --vault-id dev@prompt secret_dev.yml ansible-vault create --vault-id prod@prompt secret_prod.yml
Run a playbook with vault-encrypted files	ansible-playbook site.yml --ask-vault-pass ansible-playbook site.yml --vault-password-file /path/to/vault_pass.txt ansible-playbook site.yml --vault-id dev@prompt --vault-id prod@prompt
Change the encryption key of a vault-encrypted file	ansible-vault rekey secret.yml

Remember: When using ansible-vault, you'll be prompted for the vault password unless you specify a password file.

---

Jeremy Stretch 241024