What Is Ansible Vault

In the previous module, we finished our exploration of the tag system, which allows you to run specific parts of a playbook. However, as playbooks grow to include real database setups, web server configurations, and application deployments, they inevitably need to handle sensitive information. Storing raw API tokens, TLS private keys, SSH credentials, or database passwords in plaintext files within a version control system like Git is a massive security vulnerability.

This is the exact problem that Ansible Vault is designed to solve. It is a built-in feature of Ansible that allows you to encrypt files, individual variables, or structured text values. Once encrypted, these files can be safely stored in public or private Git repositories. When the playbooks are executed, Ansible decrypts the secrets in memory using a password or key file provided at runtime, ensuring that your sensitive data is never written to disk in plaintext on the control node.

1. The Core Threat Model

Ansible Vault addresses specific security concerns in a GitOps or automated operations workflow:

• Repository Exposure: Developers and administrators often commit files to remote repositories. Plaintext secrets committed to public repositories are immediately harvested by bots. Vault ensures that even if a repository is public, the secrets are unreadable without the decryption key.
• Control Node Security: Secrets are decrypted dynamically in-memory on the control node during execution. They are not stored on target systems unless you explicitly write them to config files, and they are not saved as temporary plaintext files on the control node.
• Separation of Duties: Operational teams can maintain configuration logic (tasks, roles, templates) in Git, while the actual secrets remain encrypted. Only team members with access to the Vault password can view or modify the sensitive values.

2. Cryptographic Architecture

Ansible Vault uses symmetric encryption under the hood. It utilizes the AES-256 (Advanced Encryption Standard with a 256-bit key length) algorithm in Cipher Block Chaining (CBC) mode.

When you encrypt a file, Ansible Vault does the following:

1. PBKDF2 Key Derivation: It prompts for a password. It then derives a cryptographically strong 256-bit encryption key and a 256-bit HMAC key from your plaintext password using the PBKDF2 (Password-Based Key Derivation Function 2) algorithm with a SHA256 hashing function.
2. HMAC Integrity Verification: To prevent tampered ciphertext from being loaded, Vault generates a keyed-Hash Message Authentication Code (HMAC) using the derived HMAC key. If the file is altered by even one bit, the HMAC verification fails during decryption, preventing execution.
3. Vault Header Metadata: Every encrypted file starts with a plaintext header identifying it as an Ansible Vault payload, along with the format version and the vault identifier (if multiple vault passwords are used).

An encrypted Ansible Vault file looks like this:

$ANSIBLE_VAULT;1.1;AES256
3836373738393630323334353637383930313233343536373839303132333435
3637383930313233343536373839303132333435363738393031323334353637
3839303132333435363738393031323334353637383930313233343536373839

The header $ANSIBLE_VAULT;1.1;AES256 tells Ansible that this file is an encrypted payload using the 1.1 vault format with AES-256 encryption. The hex blocks that follow contain the salt, the ciphertext, and the HMAC integrity block.

3. What Can Be Encrypted?

Ansible Vault offers flexibility in how you secure your data. Depending on your needs, you can choose one of three levels of encryption:

Whole File Encryption

You can encrypt entire files. This is best for static secret assets, such as:

• TLS/SSL private keys (.key files).
• Private SSH identity keys.
• Complete .env files or application config dumps containing database strings.
• Binary credential files or third-party license assets.

Structured Variable File Encryption

You can encrypt entire YAML files containing lists or dictionaries of secret variables. This is the most common pattern for playbooks because it allows you to separate public configuration variables from private credentials:

# group_vars/production/vault.yml (This entire file is encrypted)
vault_db_password: "super-secure-production-password"
vault_api_token: "api-secret-token-value-here"
vault_ssh_private_key: |
  -----BEGIN RSA PRIVATE KEY-----
  MIIEowIBAAKCAQEA0y8g...
  -----END RSA PRIVATE KEY-----

Inline Variable Encryption

If you only have one or two secrets and do not want to encrypt an entire file, Ansible Vault allows you to encrypt individual variable values inline. This leaves the surrounding YAML structure completely readable:

# group_vars/production/vars.yml
db_port: 5432
db_user: app_user
# Only the password string is encrypted
db_password: !vault |
          $ANSIBLE_VAULT;1.1;AES256
          3637653434653639373966373336333535646138656262333161393665333536
          6266613837313038623635393165313939633834396131363939336130353432

This hybrid style keeps non-sensitive parameters open for review and pull request comments, while keeping secrets secure.

4. Operational Best Practices

When integrating Ansible Vault into your configuration workflow:

• Use the vault_ prefix: Always prefix encrypted variable names with vault_. For example, use vault_db_password instead of db_password. This makes it obvious in playbooks and templates when a variable is coming from an encrypted source.
• Keep secrets in separate files: Store non-sensitive configuration values in standard YAML files (e.g., vars.yml) and secrets in a dedicated vault file (e.g., vault.yml). This makes code reviews clean, as git diffs will only show modifications to the open variables while the encrypted binary block remains unchanged unless you rotate passwords.
• Never commit the password: Keep your vault password out of the git repository. Add any password files to .gitignore and enforce password safety rules within your team.

Now that we have established what Ansible Vault is, its cryptographic backend, and the different levels of encryption it provides, the next step is learning the hands-on commands. In the next section, we will cover how to use the command line to encrypt new or existing plaintext files.