Why Secrets Need Special Handling
Playbooks and inventory files routinely need database passwords, API keys, and TLS private keys, but committing those values in plaintext to a Git repository — even a private one — creates a permanent leak risk, since anyone with repo access or a copy of the git history can read them forever. Ansible Vault solves this by encrypting a file (or a single string within a file) with AES256 symmetric encryption, so the ciphertext can be safely committed to version control while only holders of the vault password can decrypt it at runtime.
Cricket analogy: A team keeps its strategic bowling plans against a specific batter in a locked dossier that only the coaching staff can open, rather than pinning it on a public noticeboard, just as Ansible Vault locks secrets away from anyone without the password.
Encrypting Files and Individual Strings
ansible-vault create secrets.yml opens an editor to write a brand-new encrypted file, ansible-vault edit secrets.yml decrypts it into a temp editor session and re-encrypts on save, and ansible-vault encrypt existing.yml converts an already-existing plaintext file in place. For cases where only one value in an otherwise-plaintext file needs protecting, ansible-vault encrypt_string 'supersecret' --name 'db_password' produces a block that can be pasted directly into a normal YAML file, keeping the rest of the file readable while only that one variable is ciphertext.
Cricket analogy: A team can lock an entire tactics folder (encrypt a whole file) or just redact one confidential clause about an injury (encrypt_string one value) while leaving the rest of the document readable to staff.
Vault IDs for Multiple Passwords
A single Ansible project often needs different secrets for different environments — a dev vault password shared with the whole team and a prod vault password restricted to a small group — and vault IDs solve this with labeled passwords: ansible-vault encrypt --vault-id prod@prompt secrets/prod.yml tags the encrypted file with the 'prod' label, and running the playbook with --vault-id dev@~/.vault_pass_dev --vault-id prod@prompt supplies both passwords at once, with Ansible automatically trying the matching one for each labeled file.
Cricket analogy: A stadium issues different colored access passes for the players' area versus the VIP box, each opened by a different keycard, similar to vault IDs labeling different secrets with different passwords for different audiences.
Integrating Vault into Automation
For CI/CD pipelines where no human is present to type a password interactively, --vault-password-file points to a file (or an executable script that prints the password) containing the vault password, and that file itself must never be committed to version control — it belongs in the CI system's secret store or a restricted-permission path on the runner. For more advanced setups, Ansible also supports lookup plugins for external secret managers like community.hashi_vault.hashi_vault or amazon.aws.aws_secretsmanager_secret, letting a playbook fetch a secret at runtime from a centralized secrets service instead of decrypting a local file at all.
Cricket analogy: A stadium's automated turnstile reads an encoded season-ticket chip instead of requiring a human gate attendant to check IDs, similar to a CI pipeline reading a vault password file automatically instead of a human typing it.
# Create a new encrypted file interactively
ansible-vault create group_vars/production/vault.yml
# Encrypt a single string to paste into a normal YAML file
ansible-vault encrypt_string 'S3cur3P@ss' --name 'db_password' --vault-id prod@prompt
# Produces:
# db_password: !vault |
# $ANSIBLE_VAULT;1.2;AES256;prod
# 66386439653...
# Edit an existing encrypted file (decrypts to a temp editor, re-encrypts on save)
ansible-vault edit group_vars/production/vault.yml
# Run a playbook supplying two labeled vault passwords
ansible-playbook site.yml \
--vault-id dev@~/.vault_pass_dev \
--vault-id prod@prompt
# CI-friendly non-interactive run
ansible-playbook site.yml --vault-password-file /run/secrets/vault_passPair every group_vars/<group>/vars.yml with a matching group_vars/<group>/vault.yml, where vars.yml references vault-encrypted variables with a vault_ prefix (e.g. db_password: "{{ vault_db_password }}"). This keeps variable names readable in vars.yml while the actual secret values stay encrypted in vault.yml.
Never commit a .vault_pass file or vault-password-file to the same Git repository it protects — that defeats the entire purpose of encryption. Add it to .gitignore explicitly, and store the actual password in your CI/CD platform's secret store instead.
- Ansible Vault encrypts files or individual strings with AES256 so secrets can be safely committed to version control.
- ansible-vault create, edit, and encrypt manage whole files; encrypt_string protects a single value inline.
- Vault IDs let a project use multiple labeled passwords, such as separate dev and prod vault passwords.
- --vault-password-file enables non-interactive decryption for CI/CD pipelines without a human typing a password.
- Lookup plugins for HashiCorp Vault, AWS Secrets Manager, and similar services can fetch secrets at runtime instead of decrypting local files.
- Pairing vars.yml (readable names) with vault.yml (encrypted values) via a vault_ prefix convention keeps projects maintainable.
- The vault password file itself must never be committed to the repository it protects.
Practice what you learned
1. What encryption algorithm does Ansible Vault use to protect file contents?
2. Which command encrypts a single variable value so it can be pasted into an otherwise plaintext YAML file?
3. What is the purpose of a vault ID label, such as --vault-id prod@prompt?
4. How should a CI/CD pipeline decrypt vault secrets without a human typing a password interactively?
5. What is a key risk explicitly warned against when using Ansible Vault?
Was this page helpful?
You May Also Like
Variables and Precedence
How Ansible collects variable values from more than twenty possible sources and resolves conflicts using a strict, well-defined precedence order.
Group and Host Variables
How Ansible's group_vars and host_vars directories organize variables by inventory group and individual host, and how group nesting affects precedence.
Related Reading
Related Study Notes in DevOps
Browse all study notesNginx Study Notes
DevOps · 30 topics
DevOpsAdvanced Kubernetes Study Notes
Kubernetes · 30 topics
DevOpsAdvanced Bash Scripting Study Notes
Bash · 30 topics
DevOpsApache Kafka Study Notes
Kafka · 30 topics
DevOpsDocker & Kubernetes Study Notes
YAML · 40 topics
DevOpsCI/CD Tools & Pipelines Study Notes
YAML · 37 topics