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.
- 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
- 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.ymland 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:
- 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
- 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
- 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
Use a Strong Vault Password: Always choose a strong and unique password to protect your encrypted files.
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.
Separate Vault Files: If possible, separate sensitive data into dedicated vault files to minimize the exposure of credentials across different environments or teams.
Use
--vault-password-filefor Automation: When automating playbook runs in CI/CD pipelines (e.g., GitLab CI), use the--vault-password-fileoption to avoid manual password entry.Restrict File Access: Ensure that only authorized users and systems have access to the vault password file and the encrypted files.
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.ymlansible-vault create --vault-id prod@prompt secret_prod.yml
|
| Run a playbook with vault-encrypted files |
ansible-playbook site.yml --ask-vault-passansible-playbook site.yml --vault-password-file /path/to/vault_pass.txtansible-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.
Top comments (0)