ansible-vault
Encrypt and decrypt Ansible variables/files
TLDR
Create a new encrypted vault file with a prompt for a password
Create a new encrypted vault file using a vault key file to encrypt it
Encrypt an existing file using an optional password file
Encrypt a string using Ansible's encrypted string format, displaying interactive prompts
View an encrypted file, using a password file to decrypt
Re-key already encrypted vault file with a new password file
SYNOPSIS
ansible-vault action [options] file [file ...]
Common Actions:
ansible-vault create [--vault-id id] file
ansible-vault edit [--vault-id id] file
ansible-vault encrypt [--vault-id id] file [file ...]
ansible-vault decrypt file [file ...]
ansible-vault rekey [--new-vault-id id] file [file ...]
ansible-vault view file [file ...]
ansible-vault encrypt_string [--name variable_name] [--encrypt-vault-id id] string
PARAMETERS
--vault-password-file path
Specify a file containing the vault password(s). This is a secure way to provide passwords programmatically.
--vault-id id[@path]
Specify a vault ID, optionally linked to a password file. This allows managing multiple vaults with different passwords.
--ask-vault-pass
Prompt for the vault password interactively at the command line.
--new-vault-password-file path
Used with 'rekey' action to specify a file containing the new vault password.
--ask-new-vault-pass
Used with 'rekey' action to prompt for the new vault password interactively.
--output file
Write command output to the specified file instead of standard output.
--encrypt-vault-id id
Used with 'encrypt_string' to specify which vault ID to use for encryption.
--name variable_name
Used with 'encrypt_string' to output the encrypted string as a YAML variable with the given name.
--dry-run
Perform a trial run without making actual changes (primarily for 'rekey' action).
-v, --verbose
Enable verbose output. Use multiple '-v' (e.g., -vvv) for more detailed debugging information.
--version
Show program's version number and exit.
-h, --help
Show a help message and exit.
DESCRIPTION
ansible-vault is a command-line utility for Ansible that facilitates the secure storage and management of sensitive information such as passwords, API keys, and other confidential data. It allows you to encrypt files or strings within your Ansible projects, making it safe to commit them to version control systems like Git. When Ansible executes playbooks, it can automatically decrypt vaulted content on the fly, provided the correct vault password. This tool uses AES256 encryption and supports various actions, including creating new encrypted files, editing existing ones, encrypting or decrypting arbitrary files or strings, viewing content without permanent decryption, and rekeying (changing) vault passwords. It is an essential component for maintaining security best practices in Ansible automation.
CAVEATS
Password Management: The security of your vaulted data is entirely dependent on the vault password. It is critical to manage this password securely, avoiding hardcoding it directly in scripts or exposing it in logs.
No Partial Decryption: ansible-vault encrypts entire files. You cannot decrypt or access only a portion of an encrypted file; the entire file must be decrypted.
Editor Integration: When using ansible-vault edit, the command invokes your default text editor (controlled by the EDITOR environment variable). Ensure this editor is configured securely and that temporary files created during editing are handled properly to prevent accidental data exposure.
MULTIPLE VAULTS AND VAULT IDS
Ansible 2.4 introduced support for managing multiple vault passwords using the --vault-id option or the ANSIBLE_VAULT_IDENTITY_LIST environment variable. This feature allows users to organize sensitive data into different 'vaults,' each secured by a unique password. For example, you can have separate vaults for development, staging, and production environments, each with its own access credentials.
<I>ENCRYPT_STRING</I> FOR AD-HOC ENCRYPTION
The encrypt_string action is particularly useful for encrypting small, single pieces of sensitive data (like a specific password or API key) directly into a YAML file, rather than encrypting an entire file. This eliminates the need for separate vault files for every small secret, making it convenient for embedding sensitive variables directly within variable files (e.g., group_vars or host_vars) or even playbooks.
INTEGRATION WITH <I>ANSIBLE.CFG</I>
Default vault password files or vault IDs can be configured in the ansible.cfg file. This allows users to set up a primary vault password file or specific vault identities that Ansible will automatically use, reducing the need to specify them on the command line for every operation.
HISTORY
ansible-vault was introduced in Ansible 1.5 (released February 2014), marking a significant enhancement to Ansible's security capabilities. Prior to its existence, users often resorted to less secure methods for handling sensitive data within their automation projects. Its development addressed a critical need for securely storing credentials and other confidential information directly within Ansible codebases, thereby allowing projects to be safely committed to version control systems. Subsequent Ansible versions have improved ansible-vault's functionality, most notably with the introduction of multiple vault IDs in Ansible 2.4, which allows for more granular control and management of different sets of sensitive data with distinct passwords.
SEE ALSO
ansible(1), ansible-playbook(1), gpg(1)