Ansible Vault Tutorial and Best Practices [Zero to Hero]

Ansible Tutorial

Introduction to Ansible Vault

Ansible Vault is a pivotal feature within the Ansible automation tool, expressly designed to secure sensitive data. It acts as a protective layer, safeguarding crucial information such as passwords, SSH keys, and any confidential data incorporated within your Ansible playbooks or roles. By leveraging Ansible Vault, users are empowered to encrypt and decrypt files, ensuring that sensitive information remains inaccessible to unauthorized users, thus maintaining the integrity and confidentiality of the data.

In this tutorial, our exploration into the world of "Ansible Vault" will be broad and detailed. We plan to navigate through its fundamental aspects, practical implementations, advanced features, and common best practices. By delving deep into these domains, this guide aims to furnish you with a profound understanding of Ansible Vault’s capabilities, usage, and the invaluable role it plays in fortifying your automation tasks against potential vulnerabilities.


Creating Encrypted Files (ansible-vault create)

Creating an encrypted file is the cornerstone of safeguarding sensitive data using "Ansible Vault". The ansible-vault create command is employed to generate a new encrypted file. This command initiates a new file and opens it in your default text editor, allowing you to enter the sensitive content you wish to encrypt.

ansible-vault create secret.yml

In executing the command, you will be prompted to set a password. This password is vital for decrypting the file in the future, and it’s essential to keep it secure.

Setting a strong password is a critical aspect of using "Ansible Vault". The password acts as a key, locking and unlocking the encrypted content. Choose a password that aligns with best practices for password security—complex, not easily guessable, and adequately lengthy.

After setting a password, you can start adding content to the file. Once saved and closed, the content becomes encrypted, and the file is secure.

New Vault password: ********
Confirm New Vault password: ********

Post this, your default text editor opens, and you can add your sensitive data into the file. When you save and exit the editor, "Ansible Vault" encrypts the file.

Example of Adding Content:

db_password: "SensitiveDatabasePassword"
api_key: "SensitiveAPIkey"

When you view the content of the file after saving it, you'll see that the data is encrypted and not human-readable, ensuring the security of your sensitive information with "Ansible Vault".


Editing Encrypted Files (ansible-vault edit)

Editing encrypted files is a common operation when managing sensitive data with "Ansible Vault". The ansible-vault edit command is utilized for this purpose. It decrypts the file temporarily, opens it in a text editor for modifications, and re-encrypts it upon saving and closing the file.

ansible-vault edit secret.yml

Executing this command prompts you to enter the vault password. Upon successful password entry, the file secret.yml will be decrypted temporarily, and your default text editor will open, allowing for modifications.

When the file is open in the text editor, you can modify its content as needed. "Ansible Vault" ensures that the file remains encrypted outside of the editing process, adding a layer of security.

Execute the ansible-vault edit command:

ansible-vault edit secret.yml

Enter the vault password at the prompt to proceed with editing.

Modify the content within the file:

db_password: "NewSensitiveDatabasePassword"
api_key: "NewSensitiveAPIkey"

Save and exit the editor. "Ansible Vault" automatically re-encrypts the file, ensuring that the modified content remains secure.


Encrypting Existing Files (ansible-vault encrypt)

Encrypting existing files is a quintessential application of "Ansible Vault", allowing users to secure pre-existing files containing sensitive data. The ansible-vault encrypt command is instrumental in this regard. It takes an already existing plain-text file and encrypts it, making the content secure and unreadable without the appropriate decryption password.

ansible-vault encrypt existing_file.yml

Upon execution of this command, you’ll be prompted to enter a new vault password, which will be used to encrypt the specified file.

Multiple Files Encryption

"Ansible Vault" also facilitates the encryption of multiple files simultaneously. You can specify multiple files in the ansible-vault encrypt command, and all specified files will be encrypted using the same password.

ansible-vault encrypt file1.yml file2.yml file3.yml

Input a robust password when prompted, and confirm it:

New Vault password: ********
Confirm New Vault password: ********

The specified files are now encrypted by "Ansible Vault", ensuring that their contents are secured against unauthorized access. The content of the files will now appear as encrypted data, unreadable without the correct vault password.


Decrypting Files (ansible-vault decrypt)

Decrypting files is an essential operation when working with "Ansible Vault" encrypted data. The ansible-vault decrypt command is used to revert encrypted files back to their plain text format, making them accessible for viewing or editing outside the vault-encrypted environment.

ansible-vault decrypt encrypted_file.yml

Executing this command will prompt you for the vault password. Upon entering the correct password, the specified file will be decrypted, revealing its original plain text content.

Decryption should be handled with caution and typically performed when there is a necessity to edit, view, or share the file outside the "Ansible Vault" environment. However, it's vital to minimize the time that sensitive data remains in an unencrypted state to mitigate potential security risks.

Execute the ansible-vault decrypt command targeting the desired encrypted file:

ansible-vault decrypt encrypted_file.yml

Enter the correct vault password when prompted:

Vault password: ********

"Ansible Vault" will decrypt the file, reverting it to its original plain text state, enabling further actions such as viewing or editing the sensitive content.


Rekeying Encrypted Files (ansible-vault rekey)

"Ansible Vault" encompasses a feature known as rekeying, enabled through the ansible-vault rekey command. Rekeying refers to the process of changing the password of an encrypted file without altering the content within the file itself. This feature is vital for maintaining the security and integrity of the encrypted data.

ansible-vault rekey encrypted_file.yml

Executing this command prompts you for the current vault password, followed by the new password you wish to set. This changes the encryption key, effectively rekeying the file.

Rekeying is instrumental in enhancing the security posture of your "Ansible Vault" encrypted files. It is especially crucial when there is a change in personnel, suspicion of password compromise, or as a periodic best practice to rotate secrets. Regularly updating the passwords of encrypted files ensures that they are safeguarded against unauthorized access.

Utilize the ansible-vault rekey command, specifying the file to rekey:

ansible-vault rekey encrypted_file.yml

Enter the current vault password, followed by the new password and its confirmation:

Vault password: ********
New Vault password: ********
Confirm New Vault password: ********

"Ansible Vault" will then apply the new password to the file, completing the rekeying process.


Running Playbooks with Vaulted Files

1. Passing Vault Passwords

Executing playbooks that encompass "Ansible Vault" encrypted files necessitates the passage of vault passwords. This enables Ansible to decrypt the vault-encrypted files during runtime, facilitating seamless playbook execution with the incorporated secure data.

1.1 Using --ask-vault-pass

The --ask-vault-pass option prompts you for the vault password interactively when running a playbook. It ensures that the necessary decryption key is available for decrypting any vault-encrypted files or variables used within the playbook.

ansible-playbook playbook.yml --ask-vault-pass

Upon executing this command, you'll be prompted to enter the vault password, enabling the decryption of the vaulted content within the playbook execution process.

1.2 Using Vault Password Files

Alternatively, vault password files can be used to pass the vault password non-interactively. This method involves specifying a file containing the vault password using the --vault-id or --vault-password-file option.

ansible-playbook playbook.yml --vault-id /path/to/vault_password_file

 2. Configuring vault_password_file in ansible.cfg

Locate or create the ansible.cfg file in your project directory or another appropriate location.

Edit the ansible.cfg file and specify the vault_password_file directive under the [defaults] section. Provide the path to your vault password file.

vault_password_file = /path/to/vault_password_file

Execute the playbook as you normally would. Due to the configuration, Ansible automatically knows where to find the vault password.

ansible-playbook playbook.yml

By configuring the vault_password_file directive in the ansible.cfg, you're instructing Ansible to automatically use the specified file for the vault password when decrypting vault-encrypted data. This method eliminates the need to manually specify the vault password or password file each time you run a playbook, thereby enhancing efficiency and ease of use in managing "Ansible Vault" encrypted content.


Using Vault to Encrypt Inventory Files

"Ansible Vault" can be employed to encrypt inventory files, ensuring the confidentiality and integrity of sensitive inventory data. Encrypted inventory files remain secure, and their contents are not exposed unless decrypted using the appropriate vault password.


Encrypting an inventory file:

ansible-vault encrypt inventory.yml

When you have encrypted inventory files, you can still use them seamlessly in your playbooks. Ansible, when provided with the correct vault password, will decrypt the inventory file on-the-fly during playbook execution, enabling the access and utilization of the inventory data within the playbook.

Running a playbook with an encrypted inventory:

ansible-playbook -i inventory.yml playbook.yml --ask-vault-pass


Common Errors and Troubleshooting

1. Password Issues

Password-related problems are prevalent when dealing with "Ansible Vault." An incorrect password or a missing password can prevent the decryption of vault-encrypted files, hindering the execution of playbooks or tasks.

ERROR! Attempting to decrypt but no vault secrets found

Solution: Ensure that you are providing the correct password. You might use the --ask-vault-pass flag to enter the password interactively or ensure that the vault password file specified contains the correct password.

2. File Corruption

File corruption issues can occur due to various reasons such as improper shutdowns or disk failures, making the encrypted files unreadable by "Ansible Vault."

ERROR! Decryption failed (no vault secrets were found)

Solution: You might have to restore the corrupted file from a backup or re-create the file. Regular backups of essential encrypted files are advisable to prevent data loss due to corruption.

3. Vault Id Mismatches

Vault ID mismatches happen when the vault ID used during encryption does not match the vault ID provided during decryption or playbook execution.

ERROR! The vault-id 'dev@ansible_vault' does not match the input vault-id 'prod@ansible_vault'

Solution: Ensure that you are using the correct vault ID when decrypting or running playbooks with vault-encrypted files. You might need to specify the correct vault ID using the --vault-id option followed by the vault ID and associated password or password file.


Advanced Topics

1. Automating Vault Password Retrieval

Automation in retrieving vault passwords can streamline the workflow, enhancing the efficiency of working with "Ansible Vault." By leveraging automated methods such as scripts or environment variables, you can manage vault passwords dynamically and securely.


Creating a script that outputs the vault password and configuring Ansible to use that script:

echo "your_vault_password"

In ansible.cfg, you can specify the script to retrieve the vault password:

vault_password_file = /path/to/


2. Using Multiple Vaults

"Ansible Vault" allows the use of multiple vaults with different passwords, enabling more granular control over encrypted data. You can specify different vault IDs to distinguish between various vaults.


Encrypting a file with a specific vault ID:

ansible-vault encrypt --vault-id dev@prompt secret.yml

Running a playbook using multiple vault IDs:

ansible-playbook --vault-id dev@prompt --vault-id prod@/path/to/vault_password_file playbook.yml


Frequently Asked Questions on Ansible Vaults

What is Ansible Vault?

Ansible Vault is a feature in Ansible that allows you to encrypt sensitive data within your playbooks and roles. It ensures the confidentiality and security of sensitive information like passwords, API keys, and other secrets.

How do I encrypt a file using Ansible Vault?

You can encrypt a file using Ansible Vault by using the ansible-vault encrypt command, like this: ansible-vault encrypt secret_file.yml.

How can I decrypt a file encrypted with Ansible Vault?

To decrypt a file encrypted with Ansible Vault, use the ansible-vault decrypt command, like this: ansible-vault decrypt secret_file.yml.

Can I automate the retrieval of Ansible Vault passwords?

Yes, you can automate the retrieval of Ansible Vault passwords using scripts or environment variables. This allows for more streamlined and secure management of vault passwords.

What is the purpose of using multiple vaults in Ansible Vault?

Using multiple vaults allows you to segregate and control access to different sets of encrypted data with different vault IDs and passwords. It provides a way to manage sensitive information more granularly.

How do I run an Ansible playbook with a vault-encrypted file?

You can run an Ansible playbook with a vault-encrypted file by using the --ask-vault-pass option or specifying a vault password file using --vault-id, like this: ansible-playbook playbook.yml --ask-vault-pass.

What should I do if I forget the vault password for an encrypted file?

If you forget the vault password, there is no built-in way to recover the data. It's important to keep your vault passwords secure and consider having a backup plan in place.

Can I use Ansible Vault in a version-controlled environment like Git?

Yes, you can use Ansible Vault in a version-controlled environment. It's common to version-control encrypted files, but make sure not to expose sensitive data in your repositories.



In our exploration of "Ansible Vault," we've delved into various aspects that foster the secure management of sensitive data within Ansible projects. Key takeaways include:

  • Understanding the essence of "Ansible Vault" and its application in encrypting files and variables.
  • Mastery over fundamental operations such as encryption, decryption, and editing of vault-encrypted content.
  • Insights into advanced topics like automated password retrieval and managing multiple vaults, enhancing flexibility and security in handling encrypted data.

Diving into Ansible's official documentation offers comprehensive insights and up-to-date information on "Ansible Vault."

Next in our Ansible Tutorial we will provision AWS EC2 instances using Ansible where we will launch and manage EC2 instances using ansible playbook


Views: 1,406
Deepak Prasad

Deepak Prasad

He is the founder of GoLinuxCloud and brings over a decade of expertise in Linux, Python, Go, Laravel, DevOps, Kubernetes, Git, Shell scripting, OpenShift, AWS, Networking, and Security. With extensive experience, he excels in various domains, from development to DevOps, Networking, and Security, ensuring robust and efficient solutions for diverse projects. You can connect with him on his LinkedIn profile.

Can't find what you're searching for? Let us assist you.

Enter your query below, and we'll provide instant results tailored to your needs.

If my articles on GoLinuxCloud has helped you, kindly consider buying me a coffee as a token of appreciation.

Buy GoLinuxCloud a Coffee

For any other feedbacks or questions you can send mail to

Thank You for your support!!

6 thoughts on “Ansible Vault Tutorial and Best Practices [Zero to Hero]”

  1. You are awesome and the content was so good.
    Clearly explained what is Ansible. So nice of you having this. This page is kept in my book mark in my browser. Whenever I got a doubt will come and check the notes.

    Thanks you so much sir.

  2. I agree with the other comments. Great examples, easy to understand, and all in one place. Exactly what I was looking for. Keep up the great work.

    One question about #9 (vault password file). We can or put the plain text password in the playbook, or we put the plain text password in the password file. How would this be any more secure on a single system (control node)? Noob here so excuse me if this is a dumb question.

    Is there not an option to do something to encrypt the password_file (like an system bound encryption key) and as long as the playbook is run on the system the pasword_file was encrypted on you do not have to enter the password? As soon as you move the playbook and password_file to another system the password_file is no longer useable. -Thanks.

    • This would be a good implementation but I a afraid I am not aware of any such feature currently with ansible vault. If we want secure then we have to encrypt the playbook itself.

  3. Finally a tutorial that explains everything clearly and in short. Unlike others you have keep yourself to the real world usage and left the unnecessary things. Very nicely written.


Leave a Comment