Ansible Rekey Encrypted Variables

There are options that you can encrypt the file or variables itself in Ansible vault. When the file is encrypted all variables will be part of it. Encryption variables allow you to have this encryption for each variable that has sensitive content. It is not easy to rekey all encryption variables while encrypt_string does not have this option. This collection will help you during the rotation of the vault password and re-encrypt the variables.

Use case of ansible_rekey_variables

It is a collection for managing vaulted Ansible inventories. It helps to rekey all encrypted variables in the inventory repository. Can also be used to encrypt variables from clear text. Thus, without having to encrypt each variable separately, it does this for you in the file where the variable is located.

We demonstrate in this document how to run this collection locally. Don't forget, this role also can be part of a pipeline or run from Ansible Automation Platform. This pipeline / AAP template also can create the Pull Request that includes all the changes.

Information for Encrypted Variables

While ansible-vault has a rekey option to change the vault password, ansible-vault encrypt_string doesn't have an option. The goal of this collection is to automate changing vault passwords for all encrypted variables under the inventory group_vars and host_vars.

More details can be found in this link on encrypted variables.

Example for encrypted variable

---

Simply run the command below for the variable you want to encrypt, then enter the new vault password. You can use this output in your inventory to store variables as encrypted.

----
#$ ansible-vault encrypt_string '<Put the Password here>' --name 'aap_admin_password'
New Vault password:
Confirm New Vault password:
aap_admin_password: !vault |
          $ANSIBLE_VAULT;1.1;AES256
          30626132326231383238356635353339313136353137333864626365636537303930303464633035
          3536646163396235623035396262663662643762333061340a313435633034373439653638396264
          36613135326136643866363039363966333164333862633335303661373033333733623361666630
          6335386436363731640a306635666261356131393031383266333361623633303064303063323835
          3433
Encryption successful
----

Prerequisites

• Ansible version 2.14+ should be available locally. Ansible-core package installation is enough.
• Inventory repositories that hold the encrypted variables should be cloned to the local directory before performing the vault password change.
• Git also should be available on your local command line.

Requirements

The following package is required to use this collection.

Name	Minimum Version
ansible-core	2.14+

Installation

You should install this collection on your local environment.

ansible-galaxy collection install aliakkaya7.ansible_rekey_variables

Role Variables

Role variables are defined in defaults/main.yml.

• rekey_variable_vault_file_patterns: It will search in the inventory file for this regex. You can change it if you have different file naming convention.

Basically, rekey_variable_new_vault_password and rekey_variable_inventory_repo_name should be defined to be able to change the vault password.

Role Tags

This role accepts the following tags to customize which part of the deployment is executed.

• aap_vault_change
• aap_post_tasks

Inventory Repository

Clone the inventory repository to your local directory.

git clone <inventory_repository>

Example for Encrypted Variables in inventory repository

These variables are stored in vault_ prefix named files.

my_username: !vault |
          $ANSIBLE_VAULT;1.1;AES256
          32326637336636383161643138323532376466633661343039313733643835613930333965343638
          3331323838646363363437666638353634383431613836610a316566663564333432336561666635
          36663565646635366261353137316561623036393530346532373866643130353561623730373463
          6533393861333734340a396439323535353338623333393836623832396431373162653066386164
          6434
my_password: !vault |
          $ANSIBLE_VAULT;1.1;AES256
          62623139623035303335643634356536373464353063656264353262346464656231386661343034
          3438343838373062633666396438613632393237633063660a653432633763373736343734613762
          62386338356333363061626165633138346262643239376332623065663863373166363935363838
          6534383737633732340a636234643235656263666634396138636665306663633338393439353132
          3535
my_key_passphrase: !vault |
          $ANSIBLE_VAULT;1.1;AES256
          32623236633233646331376661633733653232356636646562663630333639366362666534333132
          3434383633393962393131326535373635393834366238330a373731656365613962643633323863
          39613036666635643664326437623534353437663031633733303666393730643064663365633236
          3133626231353536390a363439623330636130316362376638623236623563323337643664626330
          6366

How to run the playbook

This test.yml can be tested in the tests directory.

Example Playbook

---
- name: Change vault password for all encrypted variables in Roles
  hosts: localhost
  connection: local
  gather_facts: false
  tasks:
    - name: Replace encryption key for encrypted variables
      ansible.builtin.include_role:
        name: aliakkaya7.ansible_rekey_variables.rekey_variable
      when:
        - rekey_variable_vault_change | default('true') | bool
      tags: aap_vault_change

Run the playbook locally

An option such as --vault-id new_vault_password@prompt can be passed while running the playbook. It will prompt for a new vault password, and a new password can be entered. This prevents variables from being decrypted during the rerun if the playbook was interrupted during the previous run. If it is interrupted, some variables may be rekeyed with the new variables and some may remain with the old encryption key.

Note : The encryption password for the encrypted test variables is test

ansible-playbook test.yml -i example-inventory-repo --ask-vault-pass  -e rekey_variable_new_vault_password=test12 \
-e rekey_variable_inventory_repo_name=example-inventory-repo --vault-id new_vault_password@prompt

How to check the variables with new key

These variables are stored in vault_ prefix named files.After the rekey variables are completed you can test to view the encrypted variables with the new vault password. You just need to point the file and encrypted variable as shown in the below command.

DESCRIPTION

ansible localhost -m ansible.builtin.debug -a var="rekey_variable_encrypted_var1" \
-e "@example-inventory-repo/group_vars/aap/vault_test_data.yml" --ask-vault-pass
Vault password:
localhost | SUCCESS =>
    "encrypted_var1": "test1"

It can be tested with the debug module as described in this example.

Releasing, Versioning and Deprecation

This collection follows Semantic Versioning. More details on versioning can be found in the Ansible docs.

We plan to regularly release new minor or bugfix versions once new features or bugfixes have been implemented.

Releasing the current major version happens from the main branch.

Contributing to this collection

We welcome community contributions to this collection. More information about contributing can be found in our Contribution Guidelines.

License

GNU General Public License (https://www.gnu.org/licenses/gpl-3.0.en.html#license-text)