A Guide to Encrypting Sensitive Data with Ansible Vault

When automating tasks with Ansible, you often need to handle sensitive information like API keys, database passwords, or private SSH keys. Storing these secrets in plain text within your playbooks is a significant security risk. Ansible Vault provides a robust solution by allowing you to encrypt these values and data structures, keeping your sensitive data secure at rest.

This tutorial will guide you through the practical steps of using Ansible Vault. You'll learn how to encrypt entire files and individual variables, manage vault passwords effectively, and integrate encrypted content seamlessly into your Ansible workflows.

Step 1: Understand Ansible Vault Basics

Ansible Vault is a built-in feature designed to secure confidential data within your Ansible projects. It encrypts this data on disk, ensuring that sensitive information is not exposed in plain text. When Ansible runs a playbook or task, it automatically decrypts vault-encrypted content at runtime, provided the correct password is supplied.

• File-level Encryption: Vault primarily operates at the file level, meaning an entire file is either encrypted or unencrypted.
• Inline Encryption: For individual sensitive values, Ansible Vault also supports encrypting strings directly within a file.
• Algorithm: Ansible Vault uses AES-256 in CTR mode for encryption, deriving the key from your password using PBKDF2 with HMAC-SHA256.

Before proceeding, ensure you have Ansible installed on your control machine. This tutorial assumes you have a basic understanding of Ansible playbooks and ad-hoc commands.

Step 2: Encrypting Files with Ansible Vault

The most common use case for Ansible Vault is encrypting entire files that contain sensitive variables. This ensures that anyone accessing your project repository cannot view the secrets without the vault password.

1. Create an unencrypted secrets file:

   First, create a YAML file containing some sensitive data. Name it secrets.yml:

   ---db_password: "mySuperSecretDBPass"api_key: "sk_live_verysecretkey"

2. Encrypt the file:

   Use the ansible-vault encrypt command to encrypt this file. You will be prompted to set and confirm a vault password.

   ansible-vault encrypt secrets.yml

   After encryption, if you open secrets.yml, you will see a block of encrypted text, starting with $ANSIBLE_VAULT;1.1;AES256.

3. Edit an encrypted file:

   To modify an encrypted file, use ansible-vault edit. This command decrypts the file into a temporary editor, allows you to make changes, and then re-encrypts it upon saving.

   ansible-vault edit secrets.yml

4. View an encrypted file:

   To view the decrypted contents of a vault-encrypted file without editing, use ansible-vault view.

   ansible-vault view secrets.yml

Step 3: Encrypting Individual Variables (Inline)

Sometimes you only need to encrypt a single sensitive value within a larger, unencrypted file (e.g., a vars.yml file that contains both sensitive and non-sensitive data). For this, use ansible-vault encrypt_string.

1. Encrypt a string:

   Run the command and provide the string you want to encrypt. You'll be prompted for a vault password.

   ansible-vault encrypt_string --vault-password-file ~/.vault_pass.txt 'my_inline_secret_value' --name 'my_secret_var'

   This command will output an encrypted string formatted for inclusion in a YAML file, similar to this:

   my_secret_var: !vault |  $ANSIBLE_VAULT;1.1;AES256;...

2. Add to a playbook or variable file:

   Copy the entire output, including my_secret_var: !vault | and paste it into your vars.yml or directly into a playbook.

Step 4: Supplying the Vault Password to Ansible

Ansible needs the correct vault password to decrypt content at runtime. There are several ways to provide this password.

• Interactively:

  Use the --ask-vault-pass flag with ansible or ansible-playbook. Ansible will prompt you for the password.

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

• Using a password file:

  This is a more secure and convenient method, especially for automation. Create a plain text file containing only your vault password (e.g., ~/.vault_pass.txt).

  echo "YourVaultPassword" > ~/.vault_pass.txt

  Important: Set strict permissions for this file to prevent unauthorized access.

  chmod 600 ~/.vault_pass.txt

  Then, provide the file path using --vault-password-file:

  ansible-playbook my_playbook.yml --vault-password-file ~/.vault_pass.txt

  You can also set the ANSIBLE_VAULT_PASSWORD_FILE environment variable to point to your password file.

Step 5: Managing Multiple Vault Passwords with Vault IDs

For more complex setups, such as separate secrets for development, staging, and production environments, you can use multiple vault passwords with Vault IDs. This allows you to encrypt different files with different passwords and reference them by an ID.

1. Encrypt with a Vault ID:

   When encrypting, specify a --vault-id. For example, to encrypt a development secrets file:

   ansible-vault encrypt dev_secrets.yml --vault-id dev@prompt

   The @prompt tells Ansible to ask for the password for the 'dev' vault ID interactively. You could also use @/path/to/dev_pass.txt for a password file.

2. Reference in a playbook:

   In your playbook, you can specify which vault ID to use for certain tasks or variables, though typically Ansible will attempt to decrypt any vault content it finds if it has access to the correct passwords.

3. Provide multiple passwords at runtime:

   When running a playbook that uses multiple vault IDs, you can supply all necessary passwords:

   ansible-playbook my_multi_env_playbook.yml --vault-id dev@~/.vault_pass_dev.txt --vault-id prod@~/.vault_pass_prod.txt

   This approach gives you granular control over which secrets are accessible for different environments or contexts.

Ansible Vault is a powerful tool for securing sensitive data in your automation workflows. By following these steps, you can ensure your secrets are protected while maintaining the flexibility and efficiency of Ansible.

For more tutorials on enhancing your technical skills and streamlining your workflows, visit Yammbo.