Skip to main content

Recursively rekey ansible-vault encrypted files and in-line variables

Project description


Like ansible-vault rekey but works recursively on encrypted files and in-line variables

CI Status PyPI Version License Python Supported Versions Code style: black

⚠️ This project is alpha software and is under active development ⚠️

What is this?

If you use Ansible Vault then you may have encountered the problem of needing to roll your vault password. Maybe you found it written down on a sticky note, maybe a coworker who knows it left the company, maybe you accidentally typed it into Slack when you thought the focus was on your terminal. Whatever, these things happen.

The built-in tool Ansible provides, ansible-vault rekey, suffers from two main drawbacks:

  1. It only works on vault encrypted files and not on vault encrypted YAML data
  2. It only works on a single vault encrypted file at a time.

To rekey everything in a large project you'd need to write a script that goes through every file and rekeys everything in every format it can find.

This is that script.


If you're using Poetry or Pipenv to manage your Ansible runtime environment, you can just add vault2vault to that same environment:

# using poetry
poetry add vault2vault --dev

# using pipenv
pipenv install vault2vault

If you're using Ansible from your system package manager, it's probably easier to just install vault2vault using PipX and the ansible extra:

pipx install vault2vault[ansible]

Note: vault2vault requires an Ansible installation to function. If you are installing to a standalone virtual environment (like with PipX) then you must install it with the ansible extra to ensure a version of Ansible is available to the application.


These docs are pretty sparse, largely because this project is still under active design and redevelopment. Here are the command line options:

> vault2vault --help
usage: vault2vault [-h] [--version] [--interactive] [-v] [-b] [-i VAULT_ID] [--ignore-undecryptable]
                   [--old-pass-file OLD_PASS_FILE] [--new-pass-file NEW_PASS_FILE]
                   [paths ...]

Recursively rekey ansible-vault encrypted files and in-line variables

positional arguments:
  paths                 Paths to search for Ansible Vault encrypted content

  -h, --help            show this help message and exit
  --version             Show program version and exit
  --interactive         Step through files and variables interactively, prompting for confirmation before making
                        each change
  -v, --verbose         Increase verbosity; can be repeated
  -b, --backup          Write a backup of every file to be modified, suffixed with '.bak'
  -i VAULT_ID, --vault-id VAULT_ID
                        Limit rekeying to encrypted secrets with the specified Vault ID
                        Ignore any file or variable that is not decryptable with the provided vault secret instead
                        of raising an error
  --old-pass-file OLD_PASS_FILE
                        Path to a file with the old vault password to decrypt secrets with
  --new-pass-file NEW_PASS_FILE
                        Path to a file with the new vault password to rekey secrets with

Please report any bugs or issues you encounter on Github.

Developer Documentation

All project contributors and participants are expected to adhere to the Contributor Covenant Code of Conduct, v2 (external link).

The devel branch has the latest (and potentially unstable) changes. The stable releases are tracked on Github, PyPi, and in the Changelog.

Developing this project requires Python 3.7+ and Poetry 1.0 or later. GNU Make can optionally be used to quickly setup a local development environment, but this is not required.

To setup a local development environment:

# Clone the repository...
# ...over HTTPS
git clone
# ...over SSH
git clone

cd vault2vault/

# Create and configure the local development environment...
make dev

# Run tests and CI locally...
make test

# See additional make targets
make help

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

vault2vault-0.1.1.tar.gz (12.9 kB view hashes)

Uploaded source

Built Distribution

vault2vault-0.1.1-py3-none-any.whl (10.2 kB view hashes)

Uploaded py3

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring Fastly Fastly CDN Google Google Object Storage and Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page