Mastering Ansible Vault: Secure Password Management and Encryption Techniques

When managing target nodes, some operations require a password, but prompting for interactive input during automation with Ansible is undesirable.

Common non‑interactive approaches include writing sensitive data to files, using environment variables, command‑line options, or expect‑style tools, each with drawbacks.

Ansible provides a safer and more convenient solution: Vault encryption, which uses the AES256 algorithm.

12.1 Getting Started: Creating an Encrypted File

Ansible uses the ansible-vault command for encryption tasks. The create sub‑command creates a new encrypted file.

$ ansible-vault --help

positional arguments:
  {create,decrypt,edit,view,encrypt,encrypt_string,rekey}
    create              创建新的文件并加密
    decrypt             解密已加密的文件
    edit                编辑已加密文件的内容
    view                查看已加密文件的内容
    encrypt             加密已存在的未加密文件
    encrypt_string      加密一段字符串
    rekey               修改已加密文件的Vault ID和凭据密码

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 user
Confirm new vault password (default):  # prompt user
---
mypasswd: 123456

The --vault-id @prompt option makes ansible-vault create ask interactively for the credential password that protects the file.

12.2 Vault ID and Credential Password Provisioning

The --vault-id option can be used in three forms:

prompt – interactive prompt for the credential password.

filename – read the password from a plain file (e.g., a.txt).

script – execute a script and read the password from its stdout (e.g., a.sh).

Example of three different sources:

$ 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.

12.3 Encrypting an Existing File

To encrypt an existing plain 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
...

Multiple files can be encrypted at once with a shared Vault ID.

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

12.4 Meaning of the Encryption Header

Every encrypted file starts with a header line such as:

$ANSIBLE_VAULT;1.2;AES256;id1

The fields are:

$ANSIBLE_VAULT – fixed identifier.

Version (1.1, 1.2, …) – indicates the Vault format.

Algorithm – currently only AES256.

Vault ID – present only if a custom ID was used.

You can extract the Vault ID with:

$ 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
---
plain_passwd: 123456
port: 2312

Multiple files can be decrypted in a single command.

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

12.6 Changing Vault ID and Credential Password

Use ansible-vault rekey to modify the Vault ID, the credential password, or both.

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

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

# Keep ID, change password
$ ansible-vault rekey --vault-id [email protected] \
    --new-vault-id [email protected] \
    first_encrypted.yml

# Change ID, keep password
$ ansible-vault rekey --vault-id [email protected] \
    --new-vault-id [email protected] \
    first_encrypted.yml

12.7 Editing the Content of an Encrypted File

Use ansible-vault edit to open the file in the default editor, edit the plaintext, and have it re‑encrypted automatically.

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

Alternatively, decrypt, modify, and re‑encrypt in a non‑interactive way:

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

12.8 Using Vault‑Encrypted Files in ansible‑playbook Tasks

Playbooks can reference encrypted variable files via vars_files. Example playbook:

---
- 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

Encrypt the variable files with different Vault IDs and run the playbook with both IDs:

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

TASK [debug var in first_passwd] *********************
ok: [localhost] => {"passwd1": "passwd in first_passwd"}

TASK [debug var in second_passwd] ********************
ok: [localhost] => {"passwd2": "passwd in second_passwd"}

12.9 Encrypting a String and Embedding it in a YAML File

Use ansible-vault encrypt_string to encrypt a literal and optionally assign a name.

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

The encrypted block can be copied directly into a YAML file.

---
mysql_port: 3306
mysql_user: root
mysql_pass: !vault |
  $ANSIBLE_VAULT;1.2;AES256;id1
  39623437656130313338613033383464376437...
mysql_host: 192.168.200.27

When reading from stdin, use --stdin-name instead of --stdin --name.

$ ansible-vault encrypt_string --vault-id [email protected] --stdin-name 'mysql_pass' <<<"hello"
mysql_pass: !vault |
  $ANSIBLE_VAULT;1.2;AES256;id1
  35386538393939633862626361323735306...
Encryption successful

12.10 Speeding Up Encryption/Decryption

Install the cryptography Python package to improve performance when handling many files.

pip install cryptography

12.11 Vault Encryption Best Practices

Encrypt only files that contain sensitive data, not large configuration files. Use a separate variable file for each secret and reference it with a vault_ ‑prefixed variable in the main file.

# main.yml
---
mysql_port: 3306
mysql_user: root
mysql_pass: "{{ vault_mysql_pass }}"
mysql_host: 192.168.200.27

# vault_mysql_pass.yml (encrypted)
---
vault_mysql_pass: "abcdef"

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