Vault IDs across environments · Ansible

One vault password for the whole estate means anyone who can run a development playbook can decrypt production credentials. Vault IDs exist to break that: separate passwords, separate labels, separate reach.

They work — but not in the way the name suggests, and the gap between the two is worth measuring rather than assuming.

The syntax

A vault ID is label@source:

Read-only / Safethree sources, one label

# Prompt for the password interactively
ansible-vault view --vault-id prod@prompt group_vars/prod/vault.yml

# Read it from a file
ansible-vault view --vault-id prod@~/.vault/prod-pass group_vars/prod/vault.yml

# Run an executable and use its stdout - the client-script form
ansible-vault view --vault-id prod@~/.vault/prod-client.py group_vars/prod/vault.yml

The label is recorded in the file header when you encrypt:

Read-only / Safethe label lands in the header— Executed on ansible-core 2.21.3.

$ ansible-vault encrypt --vault-id prod@.prod-pass prod-secrets.yml; head -1 prod-secrets.yml

$ANSIBLE_VAULT;1.2;AES256;prod

Multiple IDs can be offered at once, and DEFAULT_VAULT_IDENTITY_LIST makes that the default for every invocation:

Read-only / Safeoffering several, without repeating yourself

# ansible.cfg
[defaults]
# Equivalent to passing --vault-id for each. Tried in order.
vault_identity_list = dev@~/.vault/dev-pass, prod@~/.vault/prod-pass

# Which one is used when encrypting, since the list has more than one
vault_encrypt_identity = dev

--encrypt-vault-id overrides vault_encrypt_identity for a single command. Without either, offering more than one identity and running an encryption makes the choice ambiguous, so set it deliberately — encrypting production material under the development label because it happened to be first in the list is a mistake that is invisible until somebody reads the header.

What the label actually enforces

Here is the part that matters. Four executed runs against the same file, encrypted under the label prod.

Read-only / SafeA. only the dev password offered— Executed on ansible-core 2.21.3. The dev password is genuinely different from the prod password.

$ ansible-vault view --vault-id dev@.dev-pass prod-secrets.yml; echo exit=$?

[ERROR]: Failed to view 'prod-secrets.yml': Decryption failed
(no vault secrets were found that could decrypt).
exit=1

Good. The dev password does not open the prod file — because it is the wrong password, not because it carries the wrong label.

Read-only / SafeB. both passwords offered— Executed on 2.21.3 with vault_id_match at its default of False.

$ ansible-vault view --vault-id dev@.dev-pass --vault-id prod@.prod-pass prod-secrets.yml; echo exit=$?

db_host: db1.example.com
db_password: REPLACE_ME
api_token: REDACTED
exit=0

Also expected. You offered the right password; it worked.

Now the one that changes how you should think about this.

Read-only / SafeC. the PROD password, offered under the label 'dev'— Executed on 2.21.3, vault_id_match at its default of False. The file header says prod. The identity offered is labelled dev.

$ ansible-vault view --vault-id dev@.mislabelled-pass prod-secrets.yml; echo exit=$?

db_host: db1.example.com
db_password: REPLACE_ME
api_token: REDACTED
exit=0

By default, the label is a hint and nothing else

The file says prod. The identity was labelled dev. It decrypted anyway, and reported success.

Ansible tries every secret it holds until one works. The label is used to decide which to try first, not which is permitted. With DEFAULT_VAULT_ID_MATCH at its default of False, a mismatched label is not an error, not a warning, and not visible in the output.

So a vault ID scheme built only on labels provides documentation of intent, which is genuinely valuable for humans, and no enforcement whatsoever. The separation is real only because the passwords differ — run A worked for that reason alone.

That distinction matters the moment somebody, for convenience, adds the production password to their local vault_identity_list under a development label. Nothing complains, everything works, and the scheme you believed you had is gone with no signal that it went.

The setting that closes it:

Read-only / SafeD. the same command with vault_id_match on— Executed on 2.21.3. Identical to run C except for the environment variable.

$ ANSIBLE_VAULT_ID_MATCH=True ansible-vault view --vault-id dev@.mislabelled-pass prod-secrets.yml; echo exit=$?

[ERROR]: Failed to view 'prod-secrets.yml': Decryption failed
(no vault secrets were found that could decrypt).
exit=1

Same password, same file, refused — because the label does not match.

Read-only / Safethe setting and its default— Executed on ansible-core 2.21.3 with no configuration file present.

$ ansible-config dump | grep VAULT_ID_MATCH

DEFAULT_VAULT_ID_MATCH(default) = False

The documented description, from ansible-config list:

If true, decrypting vaults with a vault id will only try the password from the matching vault-id.

Turn it on, and understand what it costs

# ansible.cfg
[defaults]
vault_id_match = True
vault_identity_list = dev@~/.vault/dev-pass, prod@~/.vault/prod-pass

What you gain. The label becomes load-bearing. A password offered under the wrong label is refused, so a production password accidentally present under a development identity cannot open production material. Separation now survives a configuration mistake rather than depending on nobody making one.

What it costs. Files encrypted without a label — the 1.1 header form — have no vault ID to match. If your repository has legacy unlabelled files, they will need re-encrypting under a label before this setting is usable, and turning it on before doing that migration breaks every run that touches them.

Sequence it:

Inventory what you have: grep -rl 'ANSIBLE_VAULT;1.1' inventory/ finds every unlabelled file.
Re-encrypt each under the correct label, with rekey --new-vault-id label@source.
Confirm nothing unlabelled remains.
Then set vault_id_match = True, and confirm a deliberate mismatch is now refused — do not trust the setting until you have seen it say no.

Step 4 is the one people skip, and it is the only one that proves the control works.

Designing the scheme

Labels should name the key, because that is what the label selects.

Read-only / Safea scheme that maps to who may decrypt what

dev       -> anyone on the engineering team
staging   -> engineering team
prod      -> platform on-call rota only
payments  -> payments team only; prod does not open it
ca-2026   -> the signing material, two-person access

Two rules that keep it honest.

One label per group of people who may decrypt. If two labels always travel together — everyone with prod also has staging — the second one is documentation, not separation. That may be fine, but know which it is.

Production credentials must not be reachable from a developer workstation. This is the whole objective, and vault IDs alone do not achieve it. The password file for prod should not exist on a laptop. If it does, the label scheme is describing an intention that the filesystem contradicts.

Auditing the scheme you actually have

# Which labels are in use, and how many files carry each
grep -rho 'ANSIBLE_VAULT;1\.[12];AES256;\?[a-z0-9_-]*' inventory/ | sort | uniq -c

# Anything still unlabelled
grep -rl 'ANSIBLE_VAULT;1.1' inventory/

# What this controller can currently open
ansible-config dump --only-changed | grep -i vault
ls -l ~/.vault/ 2>/dev/null

The last two together answer the question that matters: what can this machine decrypt right now? Run them on a developer workstation. If the answer includes prod, the scheme on paper and the scheme in force are different schemes, and only one of them is real.

Under the hood

The client-script source is the most useful and least known of the three.

DEFAULT_VAULT_PASSWORD_FILE and --vault-password-file both accept an executable, in which case it is run and its standard output is used as the password. A script whose name ends in -client — or -client.EXTENSION — is treated specially: Ansible invokes it with --vault-id <label> so the script knows which password is being asked for.

That is what makes one script able to serve an entire scheme:

#!/usr/bin/env python3
"""Named prod-client.py so Ansible passes --vault-id.
Fetches the vault password from the platform secret store.
No password is stored on this machine."""
import argparse, sys
p = argparse.ArgumentParser()
p.add_argument('--vault-id', default='default')
args = p.parse_args()
# fetch_from_secret_store returns the password for this label, or raises
sys.stdout.write(fetch_from_secret_store(args.vault_id))

Two properties this buys you, and they are the reason the next lesson in this part is about where the password lives:

Nothing is stored on the controller. The password is fetched at run time by an identity the controller holds — a machine credential, an instance role, a keyring entry — rather than sitting in a file that anyone who can read the repository directory can also read.

Access becomes auditable and revocable. The secret store records who asked for which label and when, and access can be withdrawn centrally without touching any machine. A password file offers neither.

The cost is a dependency: if the secret store is unreachable, nothing decrypts and no automation runs. That trade appears again in the external secret managers lesson at the end of this part, and it is the same trade both times.

What happens if you need to give a contractor access to run staging playbooks?

The scheme makes this a bounded question rather than an argument, which is most of its value.

What they need: the staging vault password, and only that.

What must not follow: the prod password, the payments password, or a vault_identity_list that offers everything the platform team’s controller offers.

Concretely:

Give them a controller configuration listing only the identities they may use. Not a copy of somebody else’s ansible.cfg.
Confirm vault_id_match = True is in force, so a stray production password cannot silently work under a staging label.
Give them an inventory that contains staging hosts. An inventory containing production is a separate exposure that has nothing to do with Vault — and the SSH part of this course covers the stronger control, which is that the staging key is not in production authorized_keys.
Record what they were given, so that offboarding is a checklist rather than an act of memory.
Rotate the staging vault password when they leave. Not because they are untrustworthy, but because you cannot un-tell someone a password, and access you cannot revoke is not access you granted — it is access they now have.

Point 5 is the one that gets skipped, and it is the reason for the manifest in the vault operations lesson: rotation is a routine task when you know what a password protects, and an archaeology project when you do not.

Knowledge check

Why this matters

Vault IDs are usually introduced as an organisational convenience — a way to keep environments tidy — and then quietly relied on as a security boundary. The measurement in this lesson is the difference between those two readings, and it takes one command to see.

A team that has drawn labelled boundaries and left vault_id_match at its default has a scheme that works exactly as long as nobody makes a configuration mistake. The first person who adds a second password to their identity list for convenience removes the separation, and there is no error, no warning and nothing in any log to say it happened.

vault_id_match = True turns the label into a control. It is one line, it requires a migration you can inventory with a grep, and it is the difference between a boundary that is enforced and one that is merely described.