Ansible Vault Guide

A comprehensive guide to Ansible Vault, the built-in feature for keeping sensitive data (passwords, keys, tokens) secure. This document covers everything from creating encrypted files to automating decryption.

What is Ansible Vault?

Ansible Vault allows you to encrypt files or individual variables so that they are stored as garbled text (AES-256 encryption) instead of plain text.

• Problem: You can't commit passwords to Git in plain text.

• Solution: Encrypt them with Vault, and Ansible decrypts them on the fly when running the playbook.

Part 1: Basic Commands (crud Operations)

Create a New Encrypted File

Creates a new file and immediately prompts you for a password to encrypt it.

ansible-vault create secrets.yml

• Process:

  1. Prompts for a new Vault password.

  2. Opens your default text editor (vim/nano).

  3. You write your variables (e.g., db_pass: 12345).

  4. When you save and exit, the file is saved as encrypted text.

View an Encrypted File

If you try to cat the file, you will see garbage. Use this command to read it.

ansible-vault view secrets.yml

• Argument: You will be asked for the vault password to decrypt it temporarily for viewing.

Edit an Encrypted File

Modifies an existing encrypted file.

ansible-vault edit secrets.yml

• Process: Ansible decrypts the file in memory, opens the editor, and re-encrypts it immediately when you save.

Part 2: File Management (encrypting & Decrypting)

Encrypt an Existing Plaintext File

If you already have a vars.yml file and want to secure it.

ansible-vault encrypt vars.yml

• Result: The readable file is converted into an encrypted Vault file.

Decrypt a File (permanent)

Removes encryption and saves the file as plain text (Dangerous! Use carefully).

ansible-vault decrypt secrets.yml

Change Password (rekey)

If you want to change the vault password without decrypting and re-encrypting manually.

ansible-vault rekey secrets.yml

• Input: Requires the Old password first, then the New password.

Part 3: Using Vault in Playbooks

The Playbook Structure

You include the encrypted file in vars_files just like a normal file. Ansible handles the decryption automatically.

File: use-vault.yml

- name: Use encrypted variables
  hosts: all
  become: true
  vars_files:
    - secrets.yml  # The encrypted file
  tasks:
    - name: Show database credentials
      debug:
        msg: "User: {{ db_user }}, Password: {{ db_pass }}"

Running the Playbook

You must provide the password when running the playbook, otherwise, it will fail.

Option A: Interactive Prompt

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

• --ask-vault-pass: Tells Ansible to ask you for the password at the start.

Option B: Password File (Automation Friendly) Instead of typing the password every time, save it in a file.

1. Create a file containing just the password:

   echo "SuperSecret123" > ~/.vault_pass.txt

2. Run the playbook pointing to that file:

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

Part 4: Advanced Features (pro Tips)

Encrypting Single Variables (inline Vault)

Sometimes you don't want to encrypt the whole file, just one specific password (like inside group_vars/all.yml).

Command:

ansible-vault encrypt_string 'SuperSecret123' --name 'db_password'

Output: It gives you a block of text you can paste directly into your YAML file:

db_password: !vault |
          $ANSIBLE_VAULT;1.1;AES256
          36373832656...

• Benefit: You can read the rest of the file (keys, usernames) normally, while only the sensitive value is hidden.

Multiple Vault Passwords

Ansible supports using multiple passwords for different environments (e.g., Dev vs Prod).

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

Summary Cheat Sheet