Use a vault ID to label content with the password that encrypted it, so development and production secrets use different passwords. The label is stored in plain text in the file header, and you pass --vault-id label@source at run time to choose which password to use.
One password or many
A vault password can be any string you choose. With a small team and few secrets, one password for everything is simple, but it must be stored securely in a file or secret manager. With a larger team or many values, the documentation suggests multiple passwords, for example per user, per access level, per file, per directory or per environment.
How vault IDs work
You pass the ID in three places:
- With
--vault-idtoansible-vaultwhen you create encrypted content. - With the same ID wherever you store the password.
- With
--vault-idtoansible-playbookwhen you run a playbook that uses that content.
The encrypted variable carries the label in its header. A header looks like $ANSIBLE_VAULT;1.2;AES256;dev, with the label as the last element before the encrypted data. The label is a hint, in plain text.
Example
ansible-vault encrypt_string --vault-id dev@prompt 'dbpass' --name db_password
ansible-playbook site.yml --vault-id dev@prompt --vault-id prod@~/.vault_prod
The source after the @ can be a prompt, a file or a script.
What this gives you
| Benefit | Detail |
|---|---|
| Blast radius | Someone with the dev password cannot open production content |
| Auditability | The label shows which password a file expects |
| Separate rotation | Rotate prod without touching dev |
What to watch
- Because the label is plain text, do not put sensitive words in it. Use
prod, not a customer name. - A password script is code, so review it like code.
- Do not commit password files. Keep them outside the repository, with tight permissions.
- Use a secret manager as the password source in CI where you can.
Rollout steps
- Choose labels that match your environments.
- Re-encrypt production secrets under a separate password.
- Store each password in a different secret entry with its own access list.
- Pass only the IDs a job needs, so a dev pipeline never receives the prod password.
- Rotate when people leave a team.
Quick check
Is the vault ID label encrypted?
No. It is in the header in plain text.
Do I need vault IDs with one password?
No. They are for telling several passwords apart.
Can a playbook use several passwords at once?
Yes, by passing several --vault-id options.
Safeguard offers SBOM and dependency scanning and policy gates that can block a pull request on findings, and you can try a free scan at gold.safeguard.sh/scan.
Sources
Last reviewed: 19 October 2026.
