In-Depth Tutorial: Mastering Ansible Vault

Ansible Vault is used to encrypt sensitive data like passwords, API keys, or SSL certificates in your playbooks. This tutorial will guide you through Ansible Vault from start to finish, explaining every command, best practices, and tips along the way.

Table of Contents

1. Introduction to Ansible Vault
2. Vault Initialization and Basic Commands
3. Encrypting Files with Ansible Vault
4. Using Vault Encrypted Files in Playbooks
5. Encrypting Variables in Playbooks
6. Editing and Viewing Encrypted Files
7. Best Practices for Using Ansible Vault
8. Integrating Ansible Vault with Version Control
9. Documentation and Resources

1. Introduction to Ansible Vault

Ansible Vault provides encryption capabilities to secure sensitive data within your playbooks or variable files. This is especially useful when dealing with production environments where security is critical.

Why Use Vault?

• Protect sensitive data (passwords, keys, tokens).
• Securely store environment-specific data in version control.
• Ensure that your Ansible files follow compliance requirements.

2. Vault Initialization and Basic Commands

Vault commands are the building blocks of how you interact with encrypted data in Ansible. Here’s an overview of the key commands:

3. Encrypting Files with Ansible Vault

Let’s start by encrypting files that contain sensitive data, such as passwords, tokens, or configurations.

Create an Encrypted File

You can create a brand-new encrypted file using the create command. This will prompt you to provide a password for encrypting the file.

ansible-vault create secret.yml

This opens a text editor (by default, vi) where you can input your secret data. For example:

mysql_root_password: my_super_secret_password
api_key: ABC123XYZ456

Save and close the file, and it will be encrypted.

Encrypt an Existing File

If you already have a file (e.g., vars.yml) and you want to encrypt it:

ansible-vault encrypt vars.yml

You will be prompted for a password. Once entered, the file will be encrypted. Now, vars.yml cannot be viewed without using Ansible Vault.

View the Contents of an Encrypted File

To view the contents of an encrypted file without decrypting it:

ansible-vault view secret.yml

You will be prompted for the Vault password to view the decrypted content.

4. Using Vault Encrypted Files in Playbooks

Now that we have encrypted data, we need to use it in playbooks.

Let’s say we encrypted a file called vault.yml containing the following:

vault_mysql_password: $6$rounds=656000$hash_value

You can include this file in your playbook like any other variable file.

Example Playbook:

---
- hosts: all
  become: yes
  vars_files:
    - vault.yml
  tasks:
    - name: "Install MySQL and set root password"
      mysql_user:
        name: root
        password: "{{ vault_mysql_password }}"
        state: present

When running this playbook, you need to provide the Vault password to decrypt vault.yml.

Run the playbook with Vault password prompt:

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

This command will prompt you for the Vault password, decrypt the file, and execute the playbook.

5. Encrypting Variables in Playbooks

Ansible allows encrypting individual variables instead of an entire file. This is useful if you want to encrypt only sensitive parts of a file.

Encrypting a Single Variable

You can encrypt a single variable like this:

ansible-vault encrypt_string 'my_secret_password' --name 'vault_password'

This will output:

vault_password: !vault |
          $ANSIBLE_VAULT;1.1;AES256
          33366331336366623535396666663562346634623635636636663239393939393631663131313432
          3937363663383834346337333362336265646130363732320a363966663665366635343138633932
          ...

Now, you can include the encrypted variable in your playbook directly:

---
- hosts: all
  become: yes
  tasks:
    - name: "Use the encrypted password"
      debug:
        msg: "The decrypted password is {{ vault_password }}"

Run the playbook with Vault password prompt:

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

6. Editing and Viewing Encrypted Files

Sometimes you’ll need to make changes to an encrypted file. Ansible Vault allows you to directly edit an encrypted file.

Editing an Encrypted File

Use the edit command to securely modify an encrypted file:

ansible-vault edit secret.yml

You will be prompted for the Vault password, and the file will open in the default editor for modification. Once saved, it will be re-encrypted automatically.

Decrypting Files Temporarily

If you want to temporarily decrypt a file, you can use the decrypt command:

ansible-vault decrypt secret.yml

This will decrypt the file and save it in plain text. If you want to re-encrypt the file:

ansible-vault encrypt secret.yml

Alternatively, you can decrypt a file for use in a playbook without permanently decrypting it:

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

7. Best Practices for Using Ansible Vault

Here are some best practices when working with Ansible Vault:

1. Never share Vault passwords: Use a password manager to securely store and share vault passwords within your team.
2. Use unique passwords for each environment: Dev, staging, and production should have separate vault passwords.
3. Use Vault in combination with Ansible roles: Store sensitive data in group_vars or host_vars and encrypt only the files that need it.
4. Don’t encrypt everything: Only encrypt sensitive data to keep your setup readable and manageable.
5. Integrate Vault with CI/CD tools: Use tools like Jenkins or GitHub Actions to automatically handle Vault decryption during deployments.
6. Automate Vault password retrieval: In production environments, automate the retrieval of Vault passwords using environment variables or third-party tools like HashiCorp Vault or AWS Secrets Manager.

8. Integrating Ansible Vault with Version Control

When using version control (e.g., Git), make sure to follow these guidelines:

• Commit encrypted files: Since the contents are encrypted, you can safely commit them to Git. However, never commit the Vault password.
• Encrypt secrets early: Encrypt secrets before pushing any playbooks to the repository to avoid exposing sensitive information.
• Keep passwords out of the repo: Use CI/CD tools or environment variables to provide the Vault password during automated runs.

Example .gitignore:

# Ignore plain text secrets files
vars/*.yml
!vars/encrypted_*.yml

9. Documentation and Resources

For more details, here are useful resources to deepen your knowledge of Ansible Vault:

• Ansible Vault Official Documentation (opens in a new tab)
• Best Practices for Ansible (opens in a new tab)
• Ansible Configuration Guide (opens in a new tab)

By mastering these commands and best practices, you can securely handle sensitive data with Ansible Vault, ensuring your production environment remains secure. Let me know if you need any additional details or specific examples!