Encrypting Whole Files

This chapter covers the most common Vault workflow: encrypting an entire file, committing that encrypted result, and running a playbook that depends on it.

ansible-vault create: Encrypting A New File From Scratch

ansible-vault create secrets.yaml

Prompts for a new password (and confirmation), then opens your default editor with a blank, genuinely plaintext view — type ordinary YAML into it, exactly like any other vars file. The moment you save and close the editor, Ansible encrypts what you wrote before it ever touches disk.

ansible-vault encrypt: Encrypting An Existing File

For a file that already exists in plaintext:

ansible-vault encrypt existing_vars.yaml

Prompts for a password, then replaces the file’s content with its encrypted form, in place.

What An Encrypted File Actually Looks Like

$ANSIBLE_VAULT;1.1;AES256
66386439653236336462626566653063336164663966303231363934653561363964623530
...

$ANSIBLE_VAULT identifies this as vault-encrypted content; 1.1 is the vault format version; AES256 names the encryption algorithm. Everything after that is the actual ciphertext, hex-encoded and completely unreadable without the password. This — and only this — is what’s safe to commit to version control.

Running A Playbook Against Encrypted Content

ansible-playbook site.yaml --ask-vault-pass

--ask-vault-pass prompts interactively for the password when the playbook runs. If any task references a variable coming from an encrypted file, Ansible needs that password to decrypt it — without --ask-vault-pass (or another password-supplying method, covered in a later chapter), the run fails outright with an error about being unable to decrypt the vault content.

A Realistic Example: An Encrypted Secrets File

Combined with vars_files, from the variables section, exactly as you’d use any other external vars file:

ansible-vault create secrets.yaml

(inside the editor, type genuinely plain YAML)

db_password: "supersecret123"
api_key: "abc123xyz"

- name: Use Encrypted Secrets
  hosts: servers
  vars_files:
    - secrets.yaml
  tasks:
    - name: Use the secret
      ansible.builtin.debug:
        msg: "DB password starts with: {{ db_password[:3] }}..."

ansible-playbook site.yaml --ask-vault-pass

This works exactly like an ordinary vars_files reference — the encryption is completely transparent to the rest of the playbook, which simply sees db_password and api_key as normal variables once decrypted.

A Gotcha: An Encrypted File Is Still Just A Variables File

Worth stating plainly: Vault encryption changes how a file is stored on disk — it doesn’t change what the file fundamentally is. Once decrypted at runtime, an encrypted vars_files entry behaves exactly like any other one, subject to the exact same precedence rules covered back in the variable lookup order chapter.

Encryption is purely a storage and security concern, completely separate from Ansible’s variable resolution mechanics — don’t assume an encrypted file gets special treatment in how its variables are ranked or resolved, because it doesn’t.

Best Practices

• Use ansible-vault create for brand-new secrets files, ansible-vault encrypt for existing plaintext files you need to protect retroactively.
• Treat the $ANSIBLE_VAULT-headed format as the only version of the file that’s ever safe to commit — never let a plaintext copy sit alongside it or replace it in version control.
• Remember an encrypted vars file follows the exact same precedence rules as any other vars_files entry — encryption is a storage concern, not a variable-resolution one.