Ansible Vault: Encrypt & Decrypt Secrets — Complete Guide (2026)

Ansible Vault: Encrypt & Decrypt Secrets — Complete Guide (2026)

Ansible Vault encrypts sensitive data — passwords, API keys, certificates, and secret variables — so you can safely store them in version control alongside your playbooks. This guide covers every vault operation with practical examples.

See also: Ansible Vault: Encrypt Secrets & Manage Credentials (2026 Guide)

Quick Start

# Encrypt a file
ansible-vault encrypt secrets.yml
# Decrypt a file
ansible-vault decrypt secrets.yml
# View encrypted file
ansible-vault view secrets.yml
# Edit encrypted file
ansible-vault edit secrets.yml
# Run playbook with vault
ansible-playbook site.yml --ask-vault-pass

Encrypt a File

# Create and encrypt a new file
ansible-vault create secrets.yml
# Encrypt an existing file
ansible-vault encrypt vars/production-secrets.yml

Encrypted file contents:

$ANSIBLE_VAULT;1.1;AES256
36313632356133666231393135353838363263333234363634323763393161613830636437333632
...

See also: Ansible Vault: Encrypt Secrets & Manage Encrypted Variables (Complete Guide)

Encrypt a String (Inline Variables)

Encrypt individual variables instead of entire files:

ansible-vault encrypt_string 'SuperSecretP@ss!' --name 'db_password'

Output:

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

Paste this directly into your variables file:

# vars/production.yml
db_host: db.prod.example.com
db_port: 5432
db_user: appuser
db_password: !vault |
  $ANSIBLE_VAULT;1.1;AES256
  36313632356133666231393135353838363263333234363634323763393161613830636437333632
  ...

Decrypt

# Decrypt file permanently (removes encryption)
ansible-vault decrypt secrets.yml
# View without decrypting the file
ansible-vault view secrets.yml
# Edit in place (decrypts → opens editor → re-encrypts)
ansible-vault edit secrets.yml

See also: Ansible Secrets Management: Best Practices for Enterprise Credential Security

Run Playbooks with Vault

Interactive Password Prompt

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

Password File

# Create password file
echo 'MyVaultPassword123!' > ~/.vault_pass
chmod 600 ~/.vault_pass
# Use password file
ansible-playbook site.yml --vault-password-file ~/.vault_pass

In ansible.cfg (No Flag Needed)

[defaults]
vault_password_file = ~/.vault_pass

Environment Variable

export ANSIBLE_VAULT_PASSWORD_FILE=~/.vault_pass
ansible-playbook site.yml  # No flag needed

Script as Password Source

#!/bin/bash
# ~/.vault_pass.sh — fetch from password manager
pass show ansible/vault-password

chmod +x ~/.vault_pass.sh
ansible-playbook site.yml --vault-password-file ~/.vault_pass.sh

Rekey (Change Password)

# Change vault password
ansible-vault rekey secrets.yml
# Rekey with password files
ansible-vault rekey secrets.yml \
  --vault-password-file old_pass.txt \
  --new-vault-password-file new_pass.txt
# Rekey multiple files
ansible-vault rekey vars/*.yml

Multiple Vault IDs

Use different passwords for different environments:

# Encrypt with vault ID
ansible-vault encrypt --vault-id prod@~/.vault_pass_prod secrets-prod.yml
ansible-vault encrypt --vault-id dev@~/.vault_pass_dev secrets-dev.yml
# Run with multiple vault IDs
ansible-playbook site.yml \
  --vault-id dev@~/.vault_pass_dev \
  --vault-id prod@~/.vault_pass_prod

Encrypt string with vault ID

ansible-vault encrypt_string --vault-id prod@~/.vault_pass_prod 'secret' --name 'api_key'

Best Practices

1. Keep Vault Files Separate

group_vars/
├── production/
│   ├── vars.yml          # Unencrypted variables
│   └── vault.yml         # Encrypted secrets
├── staging/
│   ├── vars.yml
│   └── vault.yml

# group_vars/production/vars.yml
db_host: db.prod.example.com
db_port: 5432
db_user: "{{ vault_db_user }}"
db_password: "{{ vault_db_password }}"
# group_vars/production/vault.yml (encrypted)
vault_db_user: admin
vault_db_password: SuperSecretP@ss!
vault_api_key: sk-abc123def456

2. Prefix Vault Variables

Use vault_ prefix for encrypted variables to clearly identify their source:

# In vault.yml
vault_db_password: secret123
vault_api_token: abc-xyz
# In vars.yml (references vault vars)
db_password: "{{ vault_db_password }}"
api_token: "{{ vault_api_token }}"

3. Never Commit Password Files

# .gitignore
.vault_pass
.vault_pass.*
*.vault_password

4. Use no_log for Sensitive Tasks

- name: Set database password
  ansible.builtin.shell: |
    mysql -u root -e "ALTER USER 'app'@'%' IDENTIFIED BY '{{ vault_db_password }}';"
  no_log: true

Vault in CI/CD

GitHub Actions

# .github/workflows/deploy.yml
- name: Run Ansible
  env:
    ANSIBLE_VAULT_PASSWORD: ${{ secrets.ANSIBLE_VAULT_PASSWORD }}
  run: |
    echo "$ANSIBLE_VAULT_PASSWORD" > .vault_pass
    ansible-playbook site.yml --vault-password-file .vault_pass
    rm -f .vault_pass

GitLab CI

deploy:
  script:
    - echo "$VAULT_PASSWORD" > .vault_pass
    - ansible-playbook site.yml --vault-password-file .vault_pass
    - rm -f .vault_pass

Jenkins

withCredentials([string(credentialsId: 'ansible-vault-pass', variable: 'VAULT_PASS')]) {
    sh 'echo $VAULT_PASS > .vault_pass'
    sh 'ansible-playbook site.yml --vault-password-file .vault_pass'
    sh 'rm -f .vault_pass'
}

Common Operations Reference

| Command | Purpose | |---------|---------| | ansible-vault create file.yml | Create new encrypted file | | ansible-vault encrypt file.yml | Encrypt existing file | | ansible-vault decrypt file.yml | Permanently decrypt file | | ansible-vault view file.yml | View without decrypting | | ansible-vault edit file.yml | Edit in place | | ansible-vault rekey file.yml | Change password | | ansible-vault encrypt_string 'text' | Encrypt inline string |

FAQ

What is Ansible Vault?

Ansible Vault is a built-in feature that encrypts sensitive data (passwords, keys, certificates) using AES-256 encryption. It lets you store secrets in version control safely and decrypt them at runtime when executing playbooks.

How do I encrypt a password in Ansible?

Use ansible-vault encrypt_string 'MyPassword' --name 'variable_name' to encrypt a single value. Paste the output into your vars file. Or encrypt an entire file with ansible-vault encrypt secrets.yml.

Can I encrypt individual variables instead of whole files?

Yes. Use ansible-vault encrypt_string to encrypt single values. The encrypted string uses the !vault YAML tag and can be placed in any regular (unencrypted) YAML file alongside plaintext variables.

How do I use Ansible Vault in CI/CD?

Store the vault password as a CI/CD secret (GitHub Secrets, GitLab CI variable, etc.). Write it to a temporary file at runtime, pass it with --vault-password-file, and delete it after the playbook runs.

What encryption does Ansible Vault use?

Ansible Vault uses AES-256 (symmetric encryption) with PBKDF2 key derivation. The password you provide is used to derive the encryption key. It's strong enough for production secrets.

Can I have different vault passwords for different environments?

Yes. Use vault IDs: --vault-id prod@password_file and --vault-id dev@password_file. Each encrypted file or string is tagged with its vault ID, and Ansible uses the correct password automatically.

Conclusion

Ansible Vault is essential for managing secrets in automation. Encrypt sensitive files and variables with AES-256, use password files for automation, prefix vault variables with vault_, and keep encrypted and unencrypted vars in separate files for maintainability.

Related Articles

• Ansible Vault decrypt: Decrypt Files & Variables • Ansible Security Best Practices • Ansible Variables: Complete Guide