# Ansible Vault: How to Securely Encrypt Sensitive Data

This blog post will explore Ansible Vault as a mechanism for keeping your sensitive values and secrets secure in your playbooks and other Ansible files. We will investigate different options for working with encrypted content and password management options.

If you are new to Ansible or interested in other Ansible concepts, [these Ansible tutorials](https://spacelift.io/blog/ansible) on Spacelift’s blog might be helpful.

What we will cover:

1. [What is Ansible Vault?](https://spacelift.io/blog/ansible-vault#what-is-ansible-vault)
2. [Ansible Vault password management](https://spacelift.io/blog/ansible-vault#ansible-vault-password-management)
3. [How to use ansible-vault command to encrypt sensitive data](https://spacelift.io/blog/ansible-vault#how-to-use-ansiblevault-command-to-encrypt-sensitive-data)
4. [Using Ansible Vault to work with encrypted content](https://spacelift.io/blog/ansible-vault#using-ansible-vault-to-work-with-encrypted-content)
5. [Using environment variable for Ansible Vault passwords](https://spacelift.io/blog/ansible-vault#using-environment-variable-for-ansible-vault-passwords)
6. [Ansible Vault best practices](https://spacelift.io/blog/ansible-vault#ansible-vault-best-practices)

## What is Ansible Vault?

**Ansible Vault** is an Ansible feature that provides a native way to handle sensitive information. It allows users to encrypt secrets and other sensitive data, such as API keys, passwords, and other credentials, to protect them at rest. Ansible Vault is designed to work with YAML files, but it can encrypt any type of text-based file.

Instead of storing secrets in plaintext, Ansible Vault provides a secure, native, and low-effort option for managing sensitive information by leveraging encryption. Encrypted content can be stored in [playbooks](https://spacelift.io/blog/ansible-playbooks), variable files, and roles, persisted under source control, and shared without exposure risks.

Ansible Vault protects sensitive content only at rest. Users are responsible for not exposing decrypted content in the console or in any other way. If necessary, check out the [`no_log`](https://docs.ansible.com/ansible/latest/reference_appendices/faq.html#keep-secret-data) option for tasks to hide their output.

## Ansible Vault password management

Passwords are required to encrypt and decrypt sensitive data with Ansible Vault. They are used to create encrypted variables or files, decrypt, and view or edit the encrypted content.

To supply the password for these operations, you can either leverage the `ansible-vault` command and get prompted for it, set up a location of a password file in your main configuration definition, `ansible.cfg`, or integrate with an external secret store solution that holds your passwords. There is a password management process for each of these cases.

### Password management for simple cases

For simple cases, small teams, and a few encrypted values, you might leverage the same password for all your encrypted content. This approach simplifies your password management process because you only have to deal with a single password. You should store and handle this password and other sensitive data in your secret management system.

### Password management for more complex systems

You might have to create and manage more vault passwords for complex systems and different access levels for different teams and people. For example, you might use a different password per team, per environment, per ansible role, application, directory, or any other pattern that fits your needs.

In such cases, you can specify a dedicated vault ID for every password. Whenever you generate newly encrypted content, you can pass the dedicated ID with the flag `--vault-id`. Store this ID along with the password and pass it with the password during decryption.

We will explore more examples of leveraging vault IDs in the section on how to encrypt sensitive values.

### Where to store your Ansible Vault passwords?

As discussed previously, storing passwords in a local file is a simple but not very secure option. If you decide to use this option, make sure the file has the correct permissions, store the password as a string in a single line, and don’t persist it in any code repositories.

A more secure and scalable way is to use an **external secret store** for storing passwords and fetch them dynamically with the help of a **vault password client script**. A vault password client script is responsible for connecting to the remote secret store, fetching the secret, and printing the password to standard output.

Check out the official documentation’s section on [storing passwords in third-party tools with Vault password client scripts](https://docs.ansible.com/ansible/latest/vault_guide/vault_managing_passwords.html#storing-passwords-in-third-party-tools-with-vault-password-client-scripts) for details on how to create and use such scripts.

## How to use ansible-vault command to encrypt sensitive data

Ansible Vault can help users encrypt mainly two types of data — [variables](https://spacelift.io/blog/ansible-variables) and files. This means we can encrypt either whole files or only specific values stored in encrypted variables.

**Encrypting specific variables** means content will be decrypted on demand only when needed. This option allows us to mix encrypted and plaintext content as required inside playbooks and roles. One drawback of this approach is that it works only with variables and that changing or rotating the password might be cumbersome because there is no command to support this.

On the other hand, **encrypting whole files** allows us to encrypt other content (tasks, for example) apart from variables, with decryption happening when the file is referenced. We can easily use the `rekey` command to change or rotate the password used for file encryption. In general, file-level encryption is easier to use and manage.

## Encrypting Ansible variables

To encrypt a string to use in an Ansible variable, you can leverage the `ansible-vault encrypt_string` command. The syntax is:

```bash
ansible-vault encrypt_string 'your_secret_value' --name 'your_variable_name'
```

### Encrypting Ansible files

To encrypt whole files that include structured data, you can leverage the `ansible-vault create` or the `ansible-vault encrypt` commands. Different encryptable files include group, host, defaults, roles, and other custom variable files, tasks files, handlers files, binary, or other arbitrary files.

#### Creating a new encrypted file

To create a new encrypted file with Ansible Vault, use:

```bash
ansible-vault create <file_name>
```

#### Encrypting an existing file

To encrypt an existing file with Ansible Vault, use:

```yaml
ansible-vault encrypt <file_name>
```

## Using Ansible Vault to work with encrypted content

In the previous section, we explained the process and reviewed several options for encrypting different content with Ansible Vault. Now, let’s look at how we can utilize and work with encrypted content.

## Viewing encrypted files

Viewing the contents of encrypted files without decrypting them permanently is quite simple with the `ansible-vault view` command:

```yaml
ansible-vault view encrypted_file.yml
```

### Editing encrypted files

Another handy option when working with encrypted files is the ability to edit the encrypted content with the `ansible-vault edit` command:

```yaml
ansible-vault edit encrypted_file.yml
```

### Decrypting encrypted files

To permanently decrypt an encrypted file, use the `ansible-vault decrypt` command. You will need to provide the encryption password:

```yaml
ansible-vault decrypt file_to_be_encrypted.yml
```

### Changing the password for encrypted files

Another common operation is to rotate or change the password used for encryption. As discussed briefly in the previous section, this can be achieved with the `ansible-vault rekey` command.

To change the password for an encrypted file, use the command:

```yaml
ansible-vault rekey file_to_be_encrypted.yml
```

## Using environment variable for Ansible Vault passwords

Ansible Vault supports using an environment variable to specify the password for encrypting and decrypting Vault files. This helps avoid passing the password directly as a command-line argument or typing it manually, making it useful for automation in CI/CD pipelines.

The environment variable used by Ansible Vault is `ANSIBLE_VAULT_PASSWORD_FILE`.

## Ansible Vault best practices

Here are best practices to consider when you are using Ansible Vault:

- **Use strong passwords for encryptions:** You should avoid easily guessed passwords, and ensure your passwords are strong and complex.
- **Avoid storing Vault passwords in VCS:** Never commit Vault passwords to a git repository because this will result in instant password breaches
- **Rotate secrets regularly:** Regularly rotate secrets stored in Ansible Vault to reduce the risk of unauthorized access in case of a breach.
- **Audit and review access:** Ensure only authorized people have access to Vault files and passwords.
- **Integrate with secret management Tools:** If you require advanced features and integrations, Integrate with external secret management tools such as HashiCorp Vault or AWS Secrets Manager.

## Key Points

In this blog post, we explored different options for encrypting sensitive information by leveraging Ansible Vault. We explained Ansible Vault’s main functionality and discussed various options for handling sensitive content, passwords, and files. Lastly, we reviewed examples and use cases of using encrypted content.