Vault in Practice

Encrypting the secret is half the job; supplying the key at run time is the other half, and how you do it differs between a human at a terminal and a CI runner with no human at all. --ask-vault-pass prompts interactively, --vault-password-file reads the key from a file or an executable script, and vault_password_file in ansible.cfg makes that the default.

That last combination is how a pipeline decrypts Larkspur's secrets without anyone typing a passphrase. The decision is always the same: a human running a one-off can be prompted, but anything repeated or automated needs the key to arrive without a keystroke — and the right mechanism depends on where the key is allowed to live.

Interactive Prompt

ansible-playbook site.yml --ask-vault-pass stops at the start of the run and asks for the passphrase once, then holds it in memory for the whole play. This is fine for a human running a one-off deploy from their laptop — type the passphrase, the run proceeds, nothing lands on disk. It is also completely useless for anything automated, because there is no human to answer the prompt, which is the trap that ends this topic.

Password File

--vault-password-file ~/.vault_pass reads the key from a file instead of asking. Ansible never writes to that file; you create it once, and its only job is to hold the passphrase. Crucially, you never commit it — it lives outside the repo, often in your home directory with tight permissions. This moves the secret-of-the-secret out of your shell history, where --ask-vault-pass typed inline would otherwise leave it.

# human at a terminal — prompted once
ansible-playbook site.yml --ask-vault-pass

# key read from a file outside the repo
ansible-playbook site.yml --vault-password-file ~/.vault_pass

# key read from an executable that prints it to stdout
ansible-playbook site.yml --vault-password-file ./vault-pass.sh

Vault Password Script

Point --vault-password-file at an executable instead of a flat file and Ansible runs it, then reads the passphrase from its stdout. That one indirection changes everything: the script can fetch the key from a system keychain, an environment variable, or a cloud secret manager rather than storing it on disk at all. The file Ansible reads is now a tiny program, and the actual passphrase lives wherever the program goes to get it.

#!/usr/bin/env bash
# CI injects ANSIBLE_VAULT_PASSWORD as a masked secret;
# this script echoes it to stdout and nowhere else.
echo "$ANSIBLE_VAULT_PASSWORD"

The same script works for a developer whose keychain exports the variable and for a runner that injects it as a masked secret. Nothing about the passphrase is hard-coded; the script is just a pipe from wherever the key lives to Ansible's stdin reader.

CI Without a Human

A pipeline run has no terminal, so the key has to arrive another way. The runner exports the passphrase as a masked secret into an environment variable, the one-line password script above echoes it, and ansible-playbook reads the value, decrypts in memory, and runs non-interactively. The passphrase exists only in the runner's secret store and, briefly, in the run's memory — it never touches the repo or a committed file, which is the whole point of doing it this way.

This is the model the spine demands at CI scale. The encrypted vault.yml is in git, the key is in the runner's vault, and the two meet only for the length of one job. Larkspur's deploy pipeline decrypts vault_db_password exactly this way: nothing decrypted persists past the job, and no engineer ever types the passphrase into the pipeline.

Defaulting It in ansible.cfg

Passing --vault-password-file on every invocation is repetitive and easy to forget, so push it into config. Set vault_password_file = ./vault-pass.sh under [defaults] in ansible.cfg, and every ansible and ansible-playbook run uses that source automatically. Engineers and CI both stop passing the flag, and the project has exactly one place that declares where the key comes from.

[defaults]
vault_password_file = ./vault-pass.sh     # relative to the repo, works everywhere
inventory = ./inventory/prod.ini

Make that path relative to the repo, not an absolute path into one engineer's home directory. A relative ./vault-pass.sh resolves the same way on every laptop and on the runner; an absolute /home/maria/.vault_pass works for Maria and fails for everyone else and every CI job, which is the last mistake in this topic.