Encrypting one variable, not the whole file · Ansible

Encrypting a whole vars file is the obvious move and it has a cost that shows up in code review rather than in operations.

Here is a pull request against a fully encrypted file:

-      33366230663736616532653338336334323164646334383532303638653236
-      3134383233333737623436383336616135646131393934300a616162663064
+      62643339373436616566346666306130666165363637326339653730613563
+      3630333832306239650a663332643664316630346639373336666636393939

What changed? A password rotated? A new host added to a list? A production endpoint pointed at a test system? An entire credential set replaced?

The reviewer cannot tell. If they have the vault password they can decrypt both sides and diff them — which nobody does routinely, and which puts plaintext on their disk when they do. If they do not have it, they can only approve on trust.

A change that cannot be reviewed is a change that gets rubber-stamped. That is not a criticism of the reviewer; it is what the format leaves them.

`encrypt_string`

The alternative encrypts individual values, so the file stays readable and only the secrets are opaque.

Read-only / Safeencrypt one value under a vault ID— Executed on ansible-core 2.21.3. The value is the literal string REPLACE_ME.

$ ansible-vault encrypt_string --vault-id dev@.dev-pass 'REPLACE_ME' --name 'db_password'

db_password: !vault |
        $ANSIBLE_VAULT;1.2;AES256;dev
        33366230663736616532653338336334323164646334383532303638653236366637366265643335
        3134383233333737623436383336616135646131393934300a616162663064346263666264636165
        62643339373436616566346666306130666165363637326339653730613563643265616365393631
        3630333832306239650a663332643664316630346639373336666636393939333536613634396266
        6664

That output is valid YAML you paste straight into a vars file. !vault is a YAML tag telling Ansible the scalar needs decrypting; the | is an ordinary block scalar carrying the same envelope a vault file has, indented under the key.

The result is a file a reviewer can actually read:

Read-only / Safeeverything visible except the value that must not be

# inventory/production/group_vars/app/main.yml
app_name: billing
app_port: 8443
db_host: db1.example.com
db_user: billing_ro
db_password: !vault |
        $ANSIBLE_VAULT;1.2;AES256;prod
        33656432323139626338306532383365366262333432313935643735336539393735303161336162
        3231356435333833396238353463326461386137313464390a386537383365353563363063366338
        65626662383136346264366235393863316437393336646232323631383163353162383362353534
        6161316335623666620a373636383934383135326433353862623030643837353335306163656462
        6339

Now the pull request tells a story. Changing db_host from db1 to db2 is visible. Changing app_port is visible. Only db_password is opaque, and the fact that it is what changed is itself visible — which is often all a reviewer needs to know.

Verified end to end on 2.21.3: the play reads that file and the value decrypts to the original string.

Read-only / Safeit round-trips— Executed on 2.21.3. The assert compares the decrypted value without printing it - deliberately, since printing it would be the leak the first lesson of this part enumerated.

$ ansible-playbook -i localhost, readvar.yml --vault-id prod@.prod-pass

ok: [localhost] => {
  "changed": false,
  "msg": "decrypted and matched"
}

PLAY RECAP ****************************************************
localhost   : ok=1  changed=0  unreachable=0  failed=0

Keep the secret out of your shell history

The form in the documentation puts the plaintext on the command line, which puts it in ~/.bash_history and in the process table while it runs. For a real credential, do not do that.

Read-only / Safethree ways, worst to best

# Worst: the secret is now in shell history and was in the process table
ansible-vault encrypt_string --vault-id prod@prompt 'REPLACE_ME' --name 'db_password'

# Better: prompt for the value, and hide it while typing (the default)
ansible-vault encrypt_string --vault-id prod@prompt --prompt --name 'db_password'

# Best when the value comes from elsewhere: read it from stdin
generate-token | ansible-vault encrypt_string --vault-id prod@prompt \
--stdin-name 'db_password'

--prompt reads the value interactively and does not echo it unless you add --show-input. --stdin-name takes the value on standard input and names it in one step, which is what to use in any pipeline where another tool produces the credential.

The --stdin-name form was used to generate the file above:

Read-only / Safestraight into the vars file, nothing on the command line— Executed on 2.21.3. The value never appears as an argument.

$ printf 'REPLACE_ME' | ansible-vault encrypt_string --vault-id prod@.prod-pass --stdin-name 'db_password' >> main.yml

Reading plaintext input from stdin. (ctrl-d to end input, twice if your content does not already have a newline)

Note printf rather than echo: echo appends a newline, and a trailing newline inside a credential is a genuinely miserable bug to chase — the value looks right in every diagnostic and the far end rejects it.

Indentation is part of the value

encrypt_string emits the payload indented under the key, and YAML block scalars take their content from the indentation of the first line.

If you paste it and your editor reindents — or you paste it inside a structure at a different depth and adjust it by eye — you can silently change what the block contains. The usual result is a parse error, which is the good case. The bad case is a value that parses and fails to decrypt, producing an error about the vault payload that sends you looking at passwords.

Two habits that avoid it:

Append with >> rather than pasting, as above. The output is written verbatim.

Put inline vault values at the top level of the file, never nested inside a dictionary or list. Top level means one indentation context, which is the one encrypt_string produced.

The trade-off nobody mentions: when it fails

File-level and variable-level encryption fail at different moments, and the difference is measurable. Both runs below supply no vault password.

Read-only / Safefile-level: fails before any task runs— Executed on ansible-core 2.21.3 with vars_files pointing at a fully encrypted file.

$ ansible-playbook -i localhost, readfile.yml; echo exit=$?

[ERROR]: Invalid vars_files file '.../prod-secrets.yml':
Attempting to decrypt but no vault secrets found.
exit=1

Read-only / Safeinline: the play starts, and fails at the point of use— Executed on 2.21.3 with the same two tasks, against a vars file carrying an inline !vault value.

$ ansible-playbook -i localhost, readinline.yml; echo exit=$?

TASK [A task that runs BEFORE anything touches the secret] ******
  "msg": "reached task 1"

TASK [The task that uses it] ***********************************
[ERROR]: Task failed: Error rendering expression: Attempt to use
undecryptable variable: Attempting to decrypt but no vault secrets found.
fatal: [localhost]: FAILED! => ...
exit=2

Read that carefully, because it is the real cost of the reviewability you gained.

File-level encryption fails fast. The vars file cannot be loaded, so the run stops at exit code 1 before a single task executes. Nothing was changed on any host.

Inline values fail lazily. They are decrypted when the expression is rendered, so the play starts, task 1 runs to completion, and the failure arrives at the first task that actually uses the variable — with exit code 2, the ordinary task-failure code.

At fleet scale that is a materially different outcome. A play whose secret is unavailable can now run its first fifteen tasks against 400 hosts before discovering the problem, leaving those hosts partially configured. The file-level version would have refused to start.

Get the fail-fast back with an explicit assertion

You do not have to accept the trade. Put the check where the fail-fast used to be, at the top of the play:

  pre_tasks:
    - name: Fail before touching anything if the vault is not available
      ansible.builtin.assert:
        that:
          - db_password is defined
          - db_password | length > 0
        fail_msg: 'Vault material unavailable - check --vault-id'
      run_once: true
      no_log: true

no_log: true because the assertion touches the value, and the no_log lesson later in this part explains why a failing message must not name it. run_once: true because one host proving the vault opened is enough — the secret is decrypted on the controller, not per host.

This is worth having in any play that carries an inline vault value. It converts a partial fleet change into a refusal to start, which is the behaviour file-level encryption gave you for free.

Choosing between the two styles

	File-level (`encrypt`)	Variable-level (`encrypt_string`)
Reviewable in a pull request	no	yes, except the values
Fails when the password is missing	at load, before any task	at first use of the variable
Rotating the vault password	one `rekey` per file	re-encrypt every value individually
Mixing secret and non-secret data	discouraged; makes the whole file opaque	that is the point
Somebody adding a secret by accident	it is encrypted either way	a plaintext value is visible in review
Suitable for large amounts of secret data	yes	tedious past a handful of values

The last row on rotation is the one that decides it for many estates. A rekey is one command per file. Re-encrypting inline values is one command per value, and if you have them scattered across thirty group_vars files you will not enjoy the afternoon.

A pragmatic layout that gets most of both:

Read-only / Safesplit by rate of change, not by secrecy

inventory/production/group_vars/app/
  main.yml     # plaintext; ordinary settings, plus a few inline !vault
               # values that change rarely and benefit from review context
  vault.yml    # fully encrypted; bulk credential material, rekeyable
               # in one command

Inline values for the handful of secrets whose context matters to a reviewer — the ones sitting next to the host and user they belong to. A file-level vault for the bulk material that is just a list of credentials and gains nothing from being read alongside anything.

Under the hood

!vault is a YAML tag, and Ansible registers a constructor for it in its YAML loader. When the parser meets the tag it produces an AnsibleVaultEncryptedUnicode object rather than a string: an object that holds the ciphertext and decrypts when its value is requested.

That is the whole mechanism behind the lazy failure above. The variable exists and is loaded successfully whether or not you have the password; the decryption attempt happens at the moment something asks for the text, which is when the template engine renders the expression. Hence the error wording — “Error rendering expression: Attempt to use undecryptable variable” — which names the rendering step rather than the loading step.

Two consequences that are easy to miss:

A variable you never use never fails. A play carrying an inline vault value it does not reference will run happily without the password. The missing password is discovered by whoever first writes a task that uses it, which may be weeks later and in a different play.

vars_files with a fully encrypted file is a different code path. The whole file must be decrypted to be parsed at all, so there is nothing lazy about it. This is why the two behaviours differ despite both being “Vault”.

What happens if you need to rotate the vault password and the repository mixes both styles?

You have two rotations, not one, and only one of them is a single command.

File-level: rekey each vault file. Scriptable, quick, and it does not require the plaintext to pass through your hands.

find inventory/ -name 'vault.yml' -exec \\
  ansible-vault rekey --vault-id prod@prompt --new-vault-id prod@prompt {} +

Inline values: rekey does not touch them. They are encrypted scalars inside plaintext YAML files, and there is no vault file for it to operate on. Each one must be decrypted under the old password and re-encrypted under the new one, individually.

Which means the rotation exposes every one of those secrets in plaintext at some point in the process — in a variable, a temporary file or a pipeline — on whichever machine you do it on. That is the moment to be careful, and it is the moment people are least careful because it is tedious and they are halfway through a long list.

Three things that make it survivable:

Inventory the inline values first. grep -rn '!vault' inventory/ gives you the complete list. Rotating what you did not know about is not possible; discovering it later, when a play fails, is the alternative.
Do it on a machine you would trust with the credentials anyway — not a shared controller, not a CI runner — and clear the shell history afterwards.
Consider whether it is the right moment to consolidate. If a password rotation has become a multi-hour manual job, that is the repository telling you the split between the two styles was made by accretion rather than by decision.

And the point that outranks all three: if you are rotating because the vault password leaked, the password rotation is the smaller half of the work. Every credential inside those files must be rotated at its source too, because anyone who had the password has already read them.

Knowledge check

Why this matters

The choice between these two styles is usually made once, early, by whoever set the repository up, and then never revisited. It deserves more thought than that, because it determines whether your secrets changes get reviewed.

An encrypted blob in a pull request is not reviewed. It is approved. Every team says otherwise and every team behaves this way, because the alternative asks a reviewer to decrypt two versions of a file onto their own disk to check one line. Nobody sustains that.

Inline values are the format that lets review do its job — with a real cost in fail-fast behaviour and a real cost at rotation time, both of which this lesson measured rather than asserted. Knowing both numbers is what lets you put the bulk material in a vault file and the context-carrying secrets inline, on purpose, instead of picking one and discovering the cost later.