Skip to content
Tutorials Center
My learning

Topics

Lesson 16 of 29 ยท Secrets and Security

Ansible Vault and Secrets

Keep passwords and keys safe in Ansible: ansible-vault create, encrypt and edit, encrypt_string, vault IDs, password files, no_log, secret lookups and git hygiene.

Automation needs secrets: database passwords, API tokens, private keys. Playbooks also live in git, are shared with teammates and run in CI logs. Ansible gives you a built-in answer, Ansible Vault, which encrypts files or single values so that you can commit them safely, plus a few habits (no_log, lookups, careful file layout) that stop secrets leaking in other ways.

In this lesson you will learn the ansible-vault commands, how to encrypt a whole file or a single string, how vault IDs and password files work, how to hide secrets from task output, and how to keep them out of git. The real Vault needs the ansible-vault program, so its commands are read-only. A Node.js stand-in shows how password-based encryption behaves, and says clearly that it is not Vault's real format.

The core idea

Vault encrypts data with a key derived from a password you provide. The encrypted text is stored in your repository. When a playbook runs, Ansible decrypts the data in memory using the same password, so tasks and templates see ordinary variables. Anyone who clones the repository sees only ciphertext.

flowchart LR
  P["Plain secret<br/>db_password: s3cret"] --> E["ansible-vault encrypt<br/>password + salt"]
  E --> G["Encrypted file in git<br/>header line: $ANSIBLE_VAULT"]
  G --> R["ansible-playbook<br/>--vault-password-file"]
  R --> M["Decrypted in memory<br/>only while running"]

Secrets are encrypted at rest in git and decrypted only inside the running play.

Working with encrypted files

These are the everyday commands. Each prompts for a password unless you pass one of the options described later.

CONSOLE
$ ansible-vault create group_vars/prod/vault.yml    # opens your editor, saves encrypted
$ ansible-vault encrypt group_vars/prod/secrets.yml # encrypts an existing file in place
$ ansible-vault view group_vars/prod/vault.yml      # prints decrypted content
$ ansible-vault edit group_vars/prod/vault.yml      # decrypt, edit, re-encrypt
$ ansible-vault decrypt group_vars/prod/vault.yml   # turn it back into plain text (use with care)
$ ansible-vault rekey group_vars/prod/vault.yml     # change the password

An encrypted file starts with a header line and then hexadecimal text. The first line is how tools (and you) can tell that a file is protected:

TEXT
$ANSIBLE_VAULT;1.1;AES256
66386439653236336462626566653063336164663966303231363934653561363964363833313662
...

A good project layout keeps names readable and secrets separate. Put plain variables in vars.yml, and secret ones in vault.yml with a vault_ prefix. Then point the plain variable at the secret:

YAML
# group_vars/prod/vars.yml  (plain text, reviewed in pull requests)
db_user: appuser
db_password: "{{ vault_db_password }}"

# group_vars/prod/vault.yml  (encrypted)
vault_db_password: "correct-horse-battery-staple"

This way a reviewer can still search for db_password and see where it is used, without ever seeing the value. Playbooks and templates use db_password and need no changes. You can read more about variable files in Variables, Facts and Precedence.

Encrypting a single value

Encrypting a whole file hides everything in it, including variable names, which makes diffs useless. For one or two values among plain ones, use encrypt_string:

CONSOLE
$ ansible-vault encrypt_string 'correct-horse-battery-staple' --name 'db_password'
db_password: !vault |
          $ANSIBLE_VAULT;1.1;AES256
          38363539343962...

Paste the output into any YAML variable file. The !vault tag tells Ansible to decrypt that value when it loads the file. Typing the secret on the command line saves it in your shell history, so for real secrets prefer reading it from standard input with --stdin-name db_password.

Passwords, password files and vault IDs

Ansible needs the vault password every time it must decrypt something. You have three ways to provide it:

CONSOLE
$ ansible-playbook site.yml --ask-vault-pass                       # prompts you
$ ansible-playbook site.yml --vault-password-file ~/.vault_pass    # reads the first line of a file
$ ansible-playbook site.yml --vault-password-file ./vault-pass.sh  # an executable script prints it

The script form is the most flexible: it can ask a password manager or a CI secret store and print the answer. The same setting can go in ansible.cfg (vault_password_file = ~/.vault_pass) so you do not retype it. The password file itself must never be committed (see the git section below).

A vault ID is a label attached to a password. It lets one project use different passwords for different environments, so a developer can hold the dev password without ever being able to read prod:

CONSOLE
$ ansible-vault encrypt --vault-id dev@prompt group_vars/dev/vault.yml
$ ansible-vault encrypt --vault-id prod@~/.vault_prod group_vars/prod/vault.yml
$ ansible-playbook site.yml --vault-id dev@prompt --vault-id prod@~/.vault_prod

The format is label@source, where the source is prompt or a path to a password file or script. The label is recorded in the file header (a 1.2 header with the ID), and when several IDs are given Ansible tries them to find the one that opens each file.

What a password-based vault does

Real Vault uses a key derivation function with a random salt, then AES encryption with an integrity check, so a wrong password or a tampered file is detected rather than producing garbage. The stand-in below shows those ideas with Node's built-in crypto module: scrypt to derive a key from the password, AES-256-GCM to encrypt and authenticate, and a random salt and nonce so the same secret encrypts differently each time.

This stand-in is NOT Ansible Vault. Its format ($STAND_IN;...) is invented for this lesson, and real Vault files use a different cipher construction and layout. Never use it to protect real data, and never expect ansible-vault to read it.

Node.js Password-based encryption stand-in

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Notice that two encryptions of the same text differ (because of the random salt and nonce), and that the wrong password fails loudly instead of returning nonsense.

Keeping secrets out of the output: no_log

Encrypting files protects secrets at rest. Ansible can still print them while it runs: in task results, in -v output, in a failure message, in CI logs. Add no_log: true to any task that handles a secret:

YAML
- name: Create the database user
  community.mysql.mysql_user:
    name: "{{ db_user }}"
    password: "{{ db_password }}"
    priv: "appdb.*:ALL"
    state: present
  no_log: true

With no_log, the result is replaced by a notice that the output is hidden. The downside is that real errors are hidden too. When you must debug such a task, remove no_log briefly on a test system, never on production and never in a pipeline that records output. Also be careful with debug: var=db_password, with -vvv, and with commands that put secrets in a command line, because process lists can show them.

This stand-in masks secret values in a result object, the way no_log conceptually hides them, and shows why a debug message that includes a secret is still a leak.

JS What no_log hides

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Other places for secrets: lookups and external stores

Vault is good for a small team and a git repository. Larger setups keep secrets in a dedicated store and fetch them when needed with a lookup plugin, which runs on the control node:

YAML
vars:
  api_token: "{{ lookup('ansible.builtin.env', 'DEPLOY_API_TOKEN') }}"
  tls_key: "{{ lookup('ansible.builtin.file', '/secure/keys/site.key') }}"
  admin_pass: "{{ lookup('ansible.builtin.pipe', 'pass show prod/admin') }}"

The env lookup reads an environment variable (convenient in CI), file reads a file from the control node, and pipe runs a command such as a password manager. Collections add lookups for HashiCorp Vault, AWS Secrets Manager and others, such as community.hashi_vault.hashi_vault. Lookups do not hide anything by themselves: pair them with no_log on tasks that use the values.

Keeping secrets out of git

  • Commit encrypted files only, and check the header before committing: head -1 file should show $ANSIBLE_VAULT. A pre-commit hook can check this automatically.
  • Add password files to .gitignore (.vault_pass, *.vault-pass, vault-pass.sh if it contains the secret itself).
  • Never put a password in ansible.cfg as plain text, only the path to a password file.
  • Use separate vault IDs for different environments.
  • If a secret ever reached git history, change it: removing the commit later does not undo the exposure. Rotate the password and rekey the files with ansible-vault rekey.
  • Do not assume --diff is safe: it may show template content. Use no_log: true or diff: false on tasks that render secret files.

For how SSH keys and privilege escalation fit into a secure setup, continue with SSH, Privilege Escalation and Hardening.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. What does the first line of a vault-encrypted file look like?

    The header marks the file as Vault data and names the format version and cipher, so tools can recognize it.
  2. 2. Why use a vault.yml file with vault_-prefixed variables and plain variables that reference them?

    A plain vars.yml with db_password: "{{ vault_db_password }}" keeps names searchable in diffs while the values stay encrypted.
  3. 3. What is a vault ID for?

    A vault ID (label@source) lets you give developers the dev password without giving them the prod password.
  4. 4. A task with no_log: true runs on CI. Which statement is true?

    no_log only censors that task's result. Other tasks, -vvv output and command lines can still expose a secret.
  5. 5. A teammate accidentally committed a plain-text password to git. What is the right fix?

    Git history keeps the old content. Once a secret is exposed, change it, then keep the new value in Vault or a secret store.

Summary

  • Vault encrypts files (create, encrypt, edit, view, rekey) or single values (encrypt_string) so they can live in git.
  • Keep plain variables in vars.yml and secret ones in an encrypted vault.yml with a vault_ prefix.
  • Supply the password with --ask-vault-pass, --vault-password-file (a file or an executable script) or ansible.cfg; vault IDs (label@source) separate environments.
  • no_log: true hides a task's output, but debug messages, -vvv and command lines can still leak secrets.
  • Lookups (env, file, pipe and collection lookups) fetch secrets from outside the repository.
  • Never commit password files, and rotate any secret that reached git history.

Next: SSH, Privilege Escalation and Hardening.