{"id":5450,"date":"2026-10-05T16:53:22","date_gmt":"2026-10-05T16:53:22","guid":{"rendered":"https:\/\/geekmungus.co.uk\/?p=5450"},"modified":"2026-10-05T16:53:22","modified_gmt":"2026-10-05T16:53:22","slug":"ansible-vault-simple-example","status":"publish","type":"post","link":"https:\/\/geekmungus.co.uk\/?p=5450","title":{"rendered":"Ansible Vault – Simple Example"},"content":{"rendered":"\n

Ansible Vault encrypts secret variables or entire YAML files inside the repository. To unlock (see) these at the point of running the Ansible Playbook you need the Vault Password to unlock them.<\/p>\n\n\n\n

We’re going to create a simple example to illustate how it can be used. <\/p>\n\n\n\n

Ensure you have added the SSH Key to your github so when you are trying to use your own repository you can access it from your machine. In my example below, i’m creating a new repository from scratch, then copying in my simple example Ansible playbook from another project, but in your case you may want to write one from scratch.<\/p>\n\n\n\n

Scenario<\/h1>\n\n\n\n

We have a simple Ansible playbook that deploys a simple Web Server configuration to a Fedora (RedHat) virtual machine. To illustate how a Secret can be retrieved at Ansible Playbook runtime and then written into a file on the webserver (akin to a configuration file for example). So this illustates how this secret value can be stored within the GitHub repository safely, and unlocked and used at runtime only.<\/p>\n\n\n\n

We’ll first need to get a repository setup which will contain our simple Ansible example.<\/p>\n\n\n\n

Or you can clone my example here: https:\/\/github.com\/tristanhself\/ansible-vault<\/a> if you want to get a simple setup ready quickly.<\/p>\n\n\n\n

Prerequistes<\/h1>\n\n\n\n

There are some steps to complete first.<\/p>\n\n\n\n

You need to have your Ansible Management Workstation prepared with a SSH Key pair created and ready for use to both access Github, but also to access our target Web Server which we’ll be managing with Ansible and applying the Secret from Ansible Vault to. I’ve not provided instructions for this, but essentially as long as you can logon as a user on the Web Server (which has sudo) without a password (SSH Key authentication), then you are all set.<\/p>\n\n\n\n

Install Packages<\/h2>\n\n\n\n

Install some things.<\/p>\n\n\n\n

sudo apt update\nsudo apt install -y python3 python3-venv python3-pip openssh-client git\nsudo apt install ripgrep<\/code><\/pre>\n\n\n\n
Load SSH Key into SSH Agent<\/h2>\n\n\n\n
We first need to load in the SSH Private key into your SSH Agent, obviously this will be other half of your SSH Public Key that you have loaded into your Git Repository trusted key store, (i.e. Profile \u2192 SSH and GPG Keys \u2192 Authentication Keys.)<\/p>\n\n\n\n
eval $(ssh-agent -s)\nssh-add ~\/.ssh\/id_ed25519\nssh-add -l<\/code><\/pre>\n\n\n\n
Clone Repository<\/h2>\n\n\n\n
Next we’re cloning the repository, if however you are creating one from scratch, then do that instead.<\/p>\n\n\n\n
git config --global user.name \"My Name\"\n\ngit config --global user.email \"me@mydomain.com\"\n\ncd ~\/projects\ngit clone git@github.com:tristanhself\/ansible-vault.git<\/code><\/pre>\n\n\n\n
If you are copying in some sample Ansible Playbook files then do that now, otherwise in the cloned repository you’ll find the example Ansible Playbook.<\/p>\n\n\n\n
Create a Python Virtual Environment (for Ansible)<\/h2>\n\n\n\n
We now create and source a Python Virtual Environment we can use for Ansible.<\/p>\n\n\n\n
mkdir ~\/virtualenvs\ncd ~\/virtualenvs\npython3 -m venv ansible-venv\nsource ~\/virtualenvs\/ansible-venv\/bin\/activate<\/code><\/pre>\n\n\n\n
Install all the requirements we need from the project:<\/p>\n\n\n\n
cd ~\/projects\/ansible-vault\npip install -r requirements.txt<\/code><\/pre>\n\n\n\n
Once installed, check Ansible is there with a version and we’re all set.<\/p>\n\n\n\n
ansible --version<\/code><\/pre>\n\n\n\n
Step 1 – Run Ansible Playbook<\/h1>\n\n\n\n
We’ll run the Ansible Playbook to ensure everything is all up to date and working as expected.<\/p>\n\n\n\n
ansible-playbook site.yml -u web01-admin -i hosts -l web01<\/code><\/pre>\n\n\n\n
\"\"<\/figure>\n\n\n\n
Assuming that you’ve cloned the repository, you’ll find that its expecting the Ansible Vault password, if however you have not done this and are instead adding it, as per step 3. Then just carry on for now.<\/p>\n\n\n\n
Step 2 – Create Encrypted Variables File<\/h1>\n\n\n\n
Now we are happy our Ansible is working, we can then create an encrypted variables file within our repository.<\/p>\n\n\n\n
cd ~\/projects\/ansible-vault\/\nansible-vault create hosts\/group_vars\/all\/vault.yml<\/code><\/pre>\n\n\n\n
Enter your Ansible Vault Password<\/strong>, this is the secret that is used to protect the Ansible Vault, you’ll need to provide this going forward to gain access to the Ansible Vault to extract the secrets when you run the Ansible Playbook.<\/p>\n\n\n\n
\"\"<\/figure>\n\n\n\n
We’ll just use “Password1234!” as this is an example. Obviously enter twice to confirm.<\/p>\n\n\n\n
Enter the secrets within the editor when prompted, remember this is YAML, so you need to enter in this format:<\/p>\n\n\n\n
vault_database_username: appuser\nvault_database_password: SuperSecretPassword123!<\/code><\/pre>\n\n\n\n
Your Ansible Vault has now been created:<\/p>\n\n\n\n
\"\"<\/figure>\n\n\n\n
To verify it is there, you can run the following, which will show one or more of your Ansible Vault files present in the repository, in our case we only have one.<\/p>\n\n\n\n
rg -n '\\$ANSIBLE_VAULT|!vault' .<\/code><\/pre>\n\n\n\n
\"\"<\/figure>\n\n\n\n
If you were to open it, you’d just see the encrypted text, which means its “safe” to be kept in your Git Repository because without the Ansible Vault password, you can’t see the secrets hidden within.<\/p>\n\n\n\n
\"\"<\/figure>\n\n\n\n
To get the output you can run:<\/p>\n\n\n\n
ansible-vault view hosts\/group_vars\/all\/vault.yml --ask-vault-pass<\/code><\/pre>\n\n\n\n
\"\"<\/figure>\n\n\n\n
Step 3 – Create Application Template Referring to Ansible Vault and Ansible Task<\/h1>\n\n\n\n
We’re going to add a Jinja template file to the “webservers” role which will be our example pretend application configuration file.<\/p>\n\n\n\n
~\\ansible-vault\\roles\\webservers\\templates\\application.cfg.j2<\/strong><\/p>\n\n\n\n
# Example Configuration File\nusername: {{ vault_database_username | to_json }}\npassword: {{ vault_database_password | to_json }}<\/code><\/pre>\n\n\n\n
Now we need to add to the task to the role, so within the main.yml for the tasks we need to add the following section:<\/p>\n\n\n\n
~\/ansible-vault\/roles\/webservers\/tasks\/main.yml<\/strong><\/p>\n\n\n\n
...\n- name: Create application configuration directory\n\tansible.builtin.file:\n\t\tpath: \/etc\/myapp\n\t\tstate: directory\n\t\towner: root\n\t\tgroup: root\n\t\tmode: \"0750\"\n\n- name: Install application configuration\n\tansible.builtin.template:\n\t\tsrc: application.cfg.j2\n        dest: \/etc\/myapp\/application.cfg\n        owner: root\n        group: root\n        mode: \"0600\"\n\tdiff: false<\/code><\/pre>\n\n\n\n
Note that the “diff” means it prevents the generated file contents including the secrets from appearing if someone runs the playbook with the “\u2013diff” argument.<\/p>\n\n\n\n
Because the Ansible Vault is within the hosts\/group_vars\/all<\/strong> directory, it should just load it all automatically, although you may with to specify this explicitly for clarity.<\/p>\n\n\n\n
Right, we are all set to use the Ansible Playbook, let’s give it a whirl.<\/p>\n\n\n\n
Step 4 – Try to Run Ansible Playbook <\/h1>\n\n\n\n
If we just try to run the Ansible Playbook without specifying any Ansible Vault Password, we’ll get the following saying it can’t decrypt an Ansible Vault file that is being referred to within the Ansible Playbook.<\/p>\n\n\n\n
ansible-playbook site.yml -u web01-admin -i hosts -l web01<\/code><\/pre>\n\n\n\n
\"\"<\/figure>\n\n\n\n
To be able to access the Ansible Vault, we have a few options at our disposal, which one you use just depends on what you need to do, your security appitite, or if this Ansible Playbook will be automated into a CI\/CD pipeline for example, i.e. not used interactively.<\/p>\n\n\n\n
Ask for Password<\/h2>\n\n\n\n
The first way we can try is to just make Ansible ask us for the Ansible Vault Password at runtime.<\/p>\n\n\n\n
ansible-playbook site.yml -u web01-admin -i hosts -l web01 --ask-vault-pass<\/code><\/pre>\n\n\n\n
\"\"<\/figure>\n\n\n\n
And now it just runs as you would expect, and as you can see our new Role tasks are being run to deploy the file and hopefully the secrets from the Ansible Vault being written into the application.cfg file generated via the Jinja template!<\/p>\n\n\n\n
\"\"<\/figure>\n\n\n\n
If we check our web server via SSH:<\/p>\n\n\n\n
ssh web01-admin@192.168.102.201<\/code><\/pre>\n\n\n\n
Then check for the application.cfg<\/strong> file and its contents:<\/p>\n\n\n\n
\"\"<\/figure>\n\n\n\n
As we can see, great success! We have the username<\/strong> and password<\/strong> written into the file. Which shows that the Ansible Playbook is able to successfully unlock and retrieve the secret at runtime.<\/p>\n\n\n\n
Store in a File<\/h2>\n\n\n\n
So to store in a file, we can do the following steps. We must first create a file outside of our Git Repository, ideally somewhere “safe” within our home directory, let’s create a directory for this:<\/p>\n\n\n\n
mkdir ~\/.vault-password\ncd ~\/.vault-password\ntouch vault-password\nchmod 600 vault-password<\/code><\/pre>\n\n\n\n
Now let’s edit the vault-password<\/strong>\u00a0file and add the just the password, as it is nothing else is required.<\/p>\n\n\n\n
vi vault-password<\/code><\/pre>\n\n\n\n
Now when we run, we can refer to this file and it will read the contents and use them in to inject the Ansible Vault password from the file.<\/p>\n\n\n\n
cd ~\/projects\/ansible-vault\nansible-playbook site.yml -u web01-admin -i hosts -l web01 --vault-password-file ~\/.vault-password\/vault-password<\/code><\/pre>\n\n\n\n
What you can also do is set an Environment Variable, you can’t put the actual Ansible Vault password into the environment variable (so you don’t have to keep referring to it), but you can do the next best thing and refer to the vault password file path instead,<\/p>\n\n\n\n
cd ~\/projects\/ansible-vault\nexport ANSIBLE_VAULT_PASSWORD_FILE=\"~\/.vault-password\/vault-password\"\nansible-playbook site.yml -u web01-admin -i hosts -l web01<\/code><\/pre>\n\n\n\n
So you can now run it, without refering to the file, because its implied by the ANSIBLE_VAULT_PASSWORD_FILE<\/strong> environment variable.<\/p>\n\n\n\n
Store in an Environment Variable (within CI\/CD)<\/h2>\n\n\n\n
Although exactly how is beyond the scope of this document, you can store your Ansible Vault password within your CI\/CD solution, for example within Git. As an Environment Variable it is held outside of the Git Repository thus is reasonably secure. But it can be referred to by your CI\/CD configuration, for example from within the .gitlab-ci.yml<\/strong> file. A snippet is shown below of referring to this Environment Variable and then dumping it to a file within the environment, which is then referred to by Ansible via the special ANSIBLE_VAULT_PASSWORD_FILE environment variable we saw just a moment ago above.<\/p>\n\n\n\n
.gitlab-ci.yml<\/strong><\/p>\n\n\n\n
...\nwebserver-update:\n  stage: deploy\n  script:\n   - if [ \"${BUILD_NEW_CONTAINER}\" == \"Yes\" ] ; then exit 0 ; fi\n   - chmod 700 -R Ansible\n   - cd Ansible\n   - echo ${VAULT_PASSWORD} >.vault_password\n   - export ANSIBLE_VAULT_PASSWORD_FILE=${PWD}\/.vault_password\n   - ansible-playbook site.yml\n   - rm -f .vault_password\n  only:\n   - main\n  artifacts:\n    expire_in: 1 week\n    paths:\n      # Should be relative to your root directory\n      - things<\/code><\/pre>\n\n\n\n
Within Git, open your Repository, Settings \u2192 CI\/CD \u2192 Variables, then here you can add it, for example VAULT_PASSWORD, if you are then referring to it within your CI\/CD configuration, you need to ensure that it is referred to as per this variable name.<\/p>\n\n\n\n
\"\"<\/figure>\n\n\n\n
Update the Secrets in Ansible Vault<\/h1>\n\n\n\n
So let’s say we need to update these credentials, what do we do? <\/p>\n\n\n\n
ansible-vault edit --ask-vault-pass ~\/projects\/ansible-vault\/hosts\/group_vars\/all\/vault.yml<\/code><\/pre>\n\n\n\n
We now update the file with whatever change of password, let’s change the password to: CHANGEME! then just save and it will automatically re-encrypt the file for us.<\/p>\n\n\n\n
Now if we were to re-run the Ansible Playbook, we would see the following because the file has been updated, so Ansible pushes in the change to the web server.<\/p>\n\n\n\n
\"\"<\/figure>\n\n\n\n
And inspecting the file on the server, we can see it has indeed been updated:<\/p>\n\n\n\n
\"\"<\/figure>\n\n\n\n
Conclusion<\/h1>\n\n\n\n
So, what have we done? We have created an Ansible Vault, added our secrets to it, referred to those secrets from within our Ansible Playbook, then at runtime provided the Ansible Vault password in order to decrypt its contents and use it has the Ansible is rendering. We also looked into how you can supply this at runtime, e.g. via a file or Environment Variable injected with CI\/CD Pipeline, but also via a file referred to at runtime. Finally we looked at how we can update the secret in the Ansible Vault for any changed, essentially unlocking, updating and re-encrypting.<\/p>\n\n\n\n
<\/p>\n","protected":false},"excerpt":{"rendered":"
Ansible Vault encrypts secret variables or entire YAML files inside the repository. To unlock (see) these at the point of running the Ansible Playbook you need the Vault Password to unlock them. We’re going to create a simple example to illustate how it can be used.  Ensure you have added the SSH Key to your … Read more<\/a><\/p>\n","protected":false},"author":4,"featured_media":4522,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[49],"tags":[],"class_list":["post-5450","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-ansible"],"_links":{"self":[{"href":"https:\/\/geekmungus.co.uk\/index.php?rest_route=\/wp\/v2\/posts\/5450","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/geekmungus.co.uk\/index.php?rest_route=\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/geekmungus.co.uk\/index.php?rest_route=\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/geekmungus.co.uk\/index.php?rest_route=\/wp\/v2\/users\/4"}],"replies":[{"embeddable":true,"href":"https:\/\/geekmungus.co.uk\/index.php?rest_route=%2Fwp%2Fv2%2Fcomments&post=5450"}],"version-history":[{"count":1,"href":"https:\/\/geekmungus.co.uk\/index.php?rest_route=\/wp\/v2\/posts\/5450\/revisions"}],"predecessor-version":[{"id":5464,"href":"https:\/\/geekmungus.co.uk\/index.php?rest_route=\/wp\/v2\/posts\/5450\/revisions\/5464"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/geekmungus.co.uk\/index.php?rest_route=\/wp\/v2\/media\/4522"}],"wp:attachment":[{"href":"https:\/\/geekmungus.co.uk\/index.php?rest_route=%2Fwp%2Fv2%2Fmedia&parent=5450"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/geekmungus.co.uk\/index.php?rest_route=%2Fwp%2Fv2%2Fcategories&post=5450"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/geekmungus.co.uk\/index.php?rest_route=%2Fwp%2Fv2%2Ftags&post=5450"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}