ansible-vault

Create a new encrypted vault file with a prompt for a password

$ ansible-vault create [vault_file]

$ ansible-vault create --vault-password-file [password_file] [vault_file]

$ ansible-vault encrypt --vault-password-file [password_file] [vault_file]

$ ansible-vault encrypt_string

$ ansible-vault view --vault-password-file [password_file] [vault_file]

$ ansible-vault rekey --vault-password-file [old_password_file] --new-vault-password-file [new_password_file] [vault_file]

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

--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.

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.

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.

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.

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.

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.

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.

ansible(1), ansible-playbook(1), gpg(1)