Mastering Ansible Vault: Secure Password Management Without Interactive Prompts

When managing target nodes, some operations require a password, but prompting for passwords during automated Ansible runs is undesirable.

Common non‑interactive approaches such as storing secrets in files, environment variables, command‑line options, or expect tools are insecure or inconvenient.

Ansible provides a safer solution: Vault encryption, which uses AES‑256.

Older Ansible versions (<2.4) had limited Vault features, requiring a single password for all tasks. Modern versions support multiple Vault IDs and more flexible usage.

12.1 A basic example: creating an encrypted file

The ansible-vault command offers sub‑commands like create, view, edit, encrypt, decrypt, rekey, and encrypt_string.

$ ansible-vault --help

positional arguments:
  {create,decrypt,edit,view,encrypt,encrypt_string,rekey}
    create              Create a new encrypted file
    decrypt             Decrypt an encrypted file
    edit                Edit an encrypted file
    view                View the contents of an encrypted file
    encrypt             Encrypt an existing plain file
    encrypt_string      Encrypt a string
    rekey               Change the Vault ID or password

Example: create a file passwd_prompt.yml and add a password variable.

$ ansible-vault create --vault-id @prompt passwd_prompt.yml

New vault password (default):             # prompt for password
Confirm new vault password (default):     # confirm

---
mypasswd: 123456

The --vault-id @prompt option makes Ansible ask for the credential password interactively; the file stores the encrypted data and still requires the password to be accessed. The term "credential password" is used for this password.

Viewing the encrypted file also requires the credential password:

$ ansible-vault view --vault-id @prompt passwd_prompt.yml
Vault password (default):
---
mypasswd: 123456

The first line of any encrypted file is the header $ANSIBLE_VAULT;1.1;AES256 (or 1.2 when a Vault ID is used).

12.2 Vault ID and credential password sources

The --vault-id label@source option tells Ansible how to obtain the credential password. Sources can be:

prompt – interactive prompt

a regular file – the file’s content is used as the password

a script – the script’s stdout is used as the password

Examples:

$ ansible-vault create --vault-id id1@prompt first_encrypted.yml
$ ansible-vault create --vault-id [email protected]  second_encrypted.yml
$ ansible-vault create --vault-id [email protected]   third_encrypted.yml

If the Vault ID is omitted, the default ID is used.

When running Ansible commands, the same Vault IDs must be supplied to decrypt the data, and multiple --vault-id options can be used:

# Using a file as password source
ansible-vault view --vault-id [email protected] second_encrypted.yml

# Interactive prompt
ansible-vault view --vault-id id2@prompt second_encrypted.yml

# Multiple IDs for a playbook
ansible-playbook --vault-id [email protected] --vault-id [email protected] main.yml

12.3 Encrypting an existing file

To encrypt a plain YAML file, use ansible-vault encrypt with the same options as create:

$ cat plain.yml
---
plain_passwd: 123456
port: 2312

$ ansible-vault encrypt --vault-id [email protected] plain.yml
Encryption successful

$ cat plain.yml
$ANSIBLE_VAULT;1.2;AES256;id1
336130623037643739633938313061336431
363838333864616665623034336439316234
643337663235366365316332643063653863
3534303533633334340a6438326433616236
383566346533653135313633633139613133
353935653734363833616464326662336132

Multiple files can be encrypted at once, sharing the same Vault ID.

$ ansible-vault encrypt --vault-id [email protected] foo.yml bar.yml baz.yml

12.4 Understanding the encryption header

Every encrypted file starts with a header line such as:

$ANSIBLE_VAULT;1.2;AES256;id1

The fields are:

Literal $ANSIBLE_VAULT Version (1.1 for default ID, 1.2 when an explicit ID is used)

Algorithm (currently only AES256)

Optional Vault ID

You can extract the Vault ID with a simple awk command:

$ awk -F';' 'NR==1{print $4}' encrypted.yml
id2

12.5 Decrypting an encrypted file

Use ansible-vault decrypt with the appropriate --vault-id:

$ ansible-vault decrypt --vault-id [email protected] plain.yml
Decryption successful

$ cat plain.yml
---
plain_passwd: 123456
port: 2312

Multiple files can be decrypted in one command.

$ ansible-vault decrypt --vault-id [email protected] foo.yml bar.yml baz.yml

12.6 Changing Vault ID or credential password

Re‑key an encrypted file with a new Vault ID or password:

$ ansible-vault rekey --vault-id [email protected] \
                      --new-vault-id [email protected] \
                      first_encrypted.yml
Rekey successful

The file’s header and ciphertext change accordingly.

$ cat first_encrypted.yml
$ANSIBLE_VAULT;1.2;AES256;id2
366666343166313633396135346464653537373936
343936653437616235316630333538343139336361
656330646535656335376662623062343863306561
3033383533306266620a3866396139663235303931
313230666235303833633330653863323738623339

You can modify only the Vault ID or only the password by keeping one part of the label@source unchanged.

12.7 Editing an encrypted file

Use ansible-vault edit to open the file in the default editor, edit the plaintext, and automatically re‑encrypt on save:

$ ansible-vault edit --vault-id [email protected] first_encrypted.yml

Alternatively, decrypt, modify with sed, then re‑encrypt.

$ ansible-vault decrypt xxx
sed -i 's/old/new/' xxx
ansible-vault encrypt xxx

12.8 Using Vault‑encrypted files in an ansible‑playbook

Encrypted variable files can be referenced in a playbook via vars_files. When multiple encrypted files use different Vault IDs, supply each ID on the command line:

---
- hosts: localhost
  gather_facts: no
  vars_files:
    - first_passwd.yml
    - second_passwd.yml
  tasks:
    - name: debug var in first_passwd
      debug:
        var: passwd1
    - name: debug var in second_passwd
      debug:
        var: passwd2

$ ansible-playbook --vault-id [email protected] --vault-id [email protected] test.yml

12.9 Encrypting a string and embedding it in YAML

Use ansible-vault encrypt_string to encrypt a literal and output a ready‑to‑paste YAML snippet:

$ ansible-vault encrypt_string --vault-id [email protected] 'hello' --name 'mysql_pass'
mysql_pass: !vault |
          $ANSIBLE_VAULT;1.2;AES256;id1
          39623437656130313338613033383464376437
          66303938343635623430353664303334623138
          33353435366262653437663839316261623664
          6362633233653237360a343439376437633733
          6262
Encryption successful

The --stdin-name option can be used to read the plaintext from standard input.

12.10 Speeding up encryption/decryption

Install the cryptography Python package for better performance when handling many files:

pip install cryptography

12.11 Vault best practices

Encrypt only the files that contain sensitive data, not large monolithic files. Use a naming convention such as vault_* for encrypted variables so they are easily identifiable, and keep the clear‑text variables in separate, unencrypted files that reference the encrypted ones via Jinja2.

---
mysql_port: 3306
mysql_user: root
mysql_pass: "{{vault_mysql_pass}}"
mysql_host: 192.168.200.27

---
vault_mysql_pass: "abcdef"

$ ansible-vault encrypt --vault-id [email protected] mysql_pass.yml