Why Secrets Management Matters in Ansible

Ansible is widely adopted for orchestration and configuration management because of its low barrier to entry and readable YAML syntax. However, one of the most common — and costly — mistakes teams make is storing sensitive data such as passwords, API keys, and SSL certificates as plaintext inside playbooks, roles, or inventory files. Once those files land in a source control repository like GitHub, the exposure risk becomes immediate and very real.

Ansible Vault is the built-in solution to this problem. It lets you encrypt sensitive data using AES-256, so secrets can be safely committed alongside your playbooks and inventory without exposing their plaintext values.

What Is Ansible Vault?

Ansible Vault is a feature included with Ansible that allows you to keep sensitive data — such as passwords, tokens, and private keys — in encrypted files rather than as plaintext. Encrypted vault files can be safely distributed or committed to source control. Decryption happens at runtime when Ansible executes the playbook, provided the correct vault password is supplied.

Vault files are encrypted with AES-256, which is considered cryptographically strong for this use case.

Creating and Editing Vault Files

Getting started with Ansible Vault is straightforward. To create a new encrypted file, run:

ansible-vault create vault.yml

Ansible will prompt you to set a vault password and then open the file in your default editor. Everything you type will be encrypted on save.

To edit an existing vault file later:

ansible-vault edit vault.yml

Ansible decrypts the file into a temporary location, opens it for editing, and re-encrypts it on exit. The plaintext is never written to disk in a persistent location.

Using a Vault Password File

Typing your vault password manually every time you run a playbook or edit a vault file becomes tedious quickly. You can configure Ansible to read the password from a file by adding the following to your ansible.cfg:

vault_password_file = ~/.ansible_vault

The file ~/.ansible_vault should contain only your vault password as a single line. Keep this file outside your repository and protect it with appropriate filesystem permissions (e.g., chmod 600 ~/.ansible_vault). This approach is particularly useful in CI/CD pipelines where interactive password prompts are not feasible.

Searching Across Multiple Vault Files

When working with host_vars and group_vars, you may end up with many vault files spread across your project. If you need to track down where a specific variable is defined, you can grep across all vault files in a directory by decrypting each one on the fly:

ls -1 | while read N ; do echo -n $N: ; ansible-vault --vault-password-file ~/.ansible_vault view $N | grep STRING ; done

Replace STRING with the variable name or value you are searching for. This loops over every file in the current directory, decrypts it using your stored password file, and pipes the output through grep.

Encrypting SSL/TLS Private Keys

One of the most practical applications of Ansible Vault is encrypting SSL/TLS private keys so they can be stored in version control alongside the configurations that reference them. To encrypt an existing private key file:

ansible-vault encrypt private.pem

The file is encrypted in place. To use the key in a playbook, reference it via a lookup and deploy it to the target system using the copy module:

---
- hosts: host.domain.tld
  vars:
    - private_key: "{{ lookup('file', 'files/private.pem') }}"
  tasks:
    - name: Place certs on systems
      copy:
        content: "{{ item.content }}"
        dest: /etc/pki/tls/certs/{{ item.dest }}
        owner: root
        group: root
        mode: "{{ item.mode }}"
      with_items:
        - { content: "{{ private_key }}", dest: 'private.pem', mode: '0600' }

When the playbook runs with the correct vault password, the key is decrypted in memory and written to the target path with the specified permissions. The private key never exists as plaintext on the control node’s filesystem.

Best Practices Summary

• Never commit plaintext secrets. Use ansible-vault encrypt on any file containing passwords, keys, or tokens before adding it to source control.
• Store the vault password file outside the repository. Reference it via vault_password_file in ansible.cfg and restrict its permissions with chmod 600.
• Use per-environment vault passwords. Consider using separate vault passwords for development, staging, and production environments to limit blast radius if a password is compromised.
• Audit vault file access. In team environments, treat vault passwords like any other privileged credential and rotate them if team membership changes.
• Prefer ansible-vault encrypt_string for inline secrets. For individual variables rather than entire files, encrypt_string allows you to embed encrypted values directly inside a plaintext YAML file.

Conclusion

Ansible Vault is a mature, well-integrated solution for secrets management that requires minimal overhead to adopt. Whether you are protecting API credentials, database passwords, or SSL private keys, encrypting them with Ansible Vault means you can safely commit all of your automation artifacts to version control without creating a security liability. If you are already using Ansible and not using Vault, there is little reason to wait — the tooling is already available and the learning curve is shallow.