Vault Operations #

Ansible Vault protects sensitive variables (passwords, API keys, certificates) stored in the inventory. Each environment has its own set of vault.yml files that must be encrypted at rest and decrypted only while editing.

Repository: ansible-inventory-deevnet

Setup #

After cloning the inventory repository, run the one-time hook setup:

cd ansible-inventory-deevnet
make install-hooks

This runs git config core.hooksPath hooks, pointing Git at the version-controlled hooks/ directory. The hooks stay in sync with the repo automatically — no copying required. This must be run once per clone.

Encrypting and Decrypting #

Decrypt all vault files #

make unvault

Iterates over every vault.yml in the repo and decrypts any that are currently encrypted. Already-decrypted files are skipped.

Encrypt all vault files #

make vault

Iterates over every vault.yml in the repo and encrypts any that are currently in plaintext. Already-encrypted files are skipped.

Typical editing workflow #

make unvault          # decrypt vault files
# edit secrets as needed
make vault            # re-encrypt before committing
git add -u && git commit

Secrets a change produces #

Most secrets here were generated by an operator, so a lost one is regenerated. Some are not: the recovery key and AppRole credentials from OpenBao’s first init, a Proxmox API token secret, a vendor key a device shows once. The moment one of those exists it exists in exactly one place, and that place is a decrypted working tree — a file git has been told to reject. Nothing is holding it.

Lock it in before doing anything else with the change:

# 1. write the value into its vault.yml
make vault                      # 2. encrypt
git add -u && git commit        # 3. the hook verifies the staged blob is encrypted
git push                        # 4. now it is off this machine
# 5. ONLY NOW delete the file the change wrote it to

Steps 3, 4 and 5 are one action, not a tidy-up for later. A change that carries on with a once-only secret still sitting in a decrypted file is one interrupted command away from having destroyed it.

This is not hypothetical. CHG-0010 lost OpenBao’s recovery key and Ansible’s AppRole exactly this way: they were written into the decrypted vault file, the init output was deleted as the change record instructed, and a git reset --hard run eight minutes later to work around a failed fast-forward discarded the plaintext. With the root token revoked and no recovery key, OpenBao could no longer be administered and had to be rebuilt.

While the tree is decrypted #

A decrypted vault file is an uncommitted modification to every vault file in the repository, and it is uncommitted by design. Any git command that discards uncommitted work discards the plaintext with it — and because plaintext is never staged, it is not in the object database, so there is nothing to recover. Not the reflog, not git stash list, not git fsck --lost-found.

Never run, while decrypted:

If a pull will not fast-forward or a branch switch is blocked, encrypt and commit first:

make vault && git add -u && git commit
git pull --rebase

Do not reach for git stash. It would put the plaintext in the object database, which is the one thing the pre-commit hook exists to prevent, and it is not covered by the hook because nothing is staged.

Keep the decrypted window as short as the work allows, and close it with make vault and a commit rather than leaving it open across a session.

Pre-commit Guard #

The hooks/pre-commit script runs automatically on every commit. It checks each staged vault.yml file by inspecting the staged blob (git show ":$file"), not the working tree. If any staged vault file does not begin with $ANSIBLE_VAULT, the commit is rejected with an error message.

If your commit is blocked:

make vault
git add -u
git commit

Vault Files #

The following vault.yml files exist across the inventory:

This list is descriptive, not a definition. make vault and make unvault discover their targets with find . -name 'vault.yml', so a new file is picked up without being added here — regenerate the list with that same command rather than trusting this table to be current.