HashiCorp Vault Collection

This repository contains the hashicorp.vault Ansible Collection.

Description

The primary purpose of this collection is to provide seamless integration between Ansible Automation Platform and HashiCorp Vault. It contains modules and plugins that support managing secrets, namespaces, authentication, and other Vault operations by using Ansible automation.

Requirements

Some modules and plugins require external libraries. Please check the requirements for each plugin or module you use in the documentation to find out which requirements are needed.

Ansible version compatibility

Tested with the Ansible Core >= 2.16.0 versions.

Python version compatibility

Tested with the Python >= 3.10 versions.

Included content

Lookup plugins

Modules

ACL & Authentication

Database Secrets Engine

KV Secrets

PKI

Namespaces

Installation

To install this collection from Automation Hub, the following needs to be added to ansible.cfg:

[galaxy]
server_list=automation_hub

[galaxy_server.automation_hub]
url=https://console.redhat.com/api/automation-hub/content/published/
auth_url=https://sso.redhat.com/auth/realms/redhat-external/protocol/openid-connect/token
token=<SuperSecretToken>

To download contents from Automation Hub using ansible-galaxy CLI, you would need to generate and use an offline token. If you already have a token, please ensure that it has not expired. Visit Connect to Hub to obtain the necessary token.

With this configured and Ansible Galaxy command-line tool installed, run the following command:

ansible-galaxy collection install hashicorp.vault

You can also include it in a requirements.yml file and install it via ansible-galaxy collection install -r requirements.yml using the format:

collections:
  - name: hashicorp.vault

To upgrade the collection to the latest available version, run the following command:

ansible-galaxy collection install hashicorp.vault --upgrade

You can also install a specific version of the collection, for example, if you need to downgrade when something is broken in the latest version (please report an issue in this repository). Use the following syntax where X.Y.Z can be any available version:

ansible-galaxy collection install hashicorp.vault:==X.Y.Z

See Ansible Using Collections for more details.

Use Cases

Modules in this collection can be used for various operations on HashiCorp Vault. Currently the collection supports: - Managing KV1 and KV2 secrets in HashiCorp Vault (create, read, update, delete) - Managing ACL policies in HashiCorp Vault - Authentication and token management - Managing database secrets engine connections, dynamic roles, and static roles - Generating credentials for database dynamic and static roles - Rotating database credentials - Managing PKI certificates (issue, sign, revoke, read) - Managing Vault Enterprise namespaces

Environment Variables

The collection supports environment variables for common connection and authentication parameters. This allows you to configure site-wide defaults and reduce repetition in playbooks.

Supported Environment Variables

The following environment variables are supported across all modules and plugins:

The following environment variable is supported by KV and PKI modules/plugins only:

Note: VAULT_ENGINE_MOUNT_POINT is shared by KV and PKI modules/lookups, but each module type has a different default mount path (secret vs pki). Setting this variable globally works only when all tasks target the same engine mount. For playbooks that mix KV and PKI operations, set engine_mount_point (or secret_mount_path) on individual tasks instead of using a single global environment variable.

Parameter Precedence

When both environment variables and module/plugin parameters are provided, explicit parameters take precedence:

1. Explicit module/plugin parameters (highest priority)
2. Environment variables
3. Default values (lowest priority)

Example Usage

# Set environment variables once
environment:
  VAULT_ADDR: "https://vault.example.com:8200"
  VAULT_TOKEN: "{{ vault_token }}"
  VAULT_NAMESPACE: "admin"
  VAULT_AUTH_METHOD: "token"
  VAULT_ENGINE_MOUNT_POINT: "secret"

# Use lookup with minimal parameters
- name: Read secret
  ansible.builtin.debug:
    msg: "{{ lookup('hashicorp.vault.kv2_secret_get', secret='myapp/config') }}"

Testing

GitHub Actions workflows run tests for this collection. The CI uses a two-tier approach:

• Tier 1 (All PRs): Linters, sanity tests, and unit tests run automatically
• Tier 2 (Integration): Vault integration tests run automatically for internal PRs; external PRs require maintainer approval

Running Tests Locally

Linters:

pip install -r requirements-linters.txt
tox -e linters

Unit Tests:

pip install -r test-requirements.txt
pytest tests/unit/

Integration Tests:

Integration tests require a Vault instance.

Copy the integration config template and fill in your Vault details:

cp tests/integration/integration_config.yml.template tests/integration/integration_config.yml

Add your Vault details:

vault_url_from_int_config: "<VAULT_URL_HERE>"
vault_namespace_from_int_config: "<VAULT_NAMESPACE_HERE>" # example: admin/hashicorp-vault-integration-tests
vault_approle_role_id_from_int_config: "<VAULT_APPROLE_ROLE_ID_HERE>"
vault_approle_secret_id_from_int_config: "<VAULT_APPROLE_SECRET_ID_HERE>"

Run the tests:

ansible-test integration <target>

Using a Local Vault Instance:

You can test changes using a local instance of HashiCorp Vault.

Follow this guide to start a local development server: https://developer.hashicorp.com/vault/tutorials/get-started/setup

Prerequisites:

For running the integration tests locally, you need to:

1. Start a Vault dev server
2. Configure AppRole authentication
3. Retrieve the role_id and secret_id
4. Update defaults/main.yml in your integration tests with the required values:

# Example values only — replace with real credentials
vault_url: "http://localhost:8200"
vault_namespace: "admin"
vault_approle_role_id: "xxxxxxxx-60da-6224-d270-xxxxxxxx"
vault_approle_secret_id: "xxxxxxxx-2458-14b9-b643-xxxxxxxx"
vault_resource_suffix: ansible-test

Support

As Red Hat Ansible Certified Content, this collection is entitled to support through the Ansible Automation Platform (AAP) using the Create issue button on the top right corner. If a support case cannot be opened with Red Hat and the collection has been obtained either from Galaxy or GitHub, there may be community help available on the Ansible Forum.

Release Notes and Roadmap

See the changelog.

Related Information

• Ansible collection development forum
• Ansible User guide
• Ansible Developer guide
• Ansible Collections Checklist
• Ansible Community code of conduct
• The Bullhorn (the Ansible Contributor newsletter)
• News for Maintainers

License Information

GNU General Public License v3.0 or later.

See LICENSE to see the full text.