ansible-role-hc-vault

Ansible role for retrieving secrets from HashiCorp Vault using AppRole authentication and exposing them as Ansible variables for use in subsequent tasks.

Overview

This role handles the full Vault secret retrieval workflow:

1. Reads Vault connection parameters from environment variables
2. Authenticates to Vault via the AppRole auth method
3. Fetches a secret from the KV v2 secrets engine
4. Assigns each requested key from the secret as an Ansible fact

All sensitive operations are protected with no_log: true to prevent credentials and secrets from appearing in logs or output.

Requirements

• Ansible >= 2.9
• Python collection: community.hashi_vault

Install the collection before using the role:

ansible-galaxy collection install community.hashi_vault

Or via a collections/requirements.yml in your playbook directory:

---
collections:
  - name: community.hashi_vault
    version: ">=6.0.0"

ansible-galaxy collection install -r collections/requirements.yml

The hvac Python library is also required on the controller node:

pip install hvac

Environment Variables

The role reads the following environment variables on the Ansible controller at runtime:

Variable	Default	Required	Description
VAULT_ADDR	https://vault.example.com	No	Vault server URL
VAULT_ROLE_ID	—	Yes	AppRole Role ID
VAULT_SECRET_ID	—	Yes	AppRole Secret ID
VAULT_MOUNT	kv	No	KV v2 engine mount point

Role Variables

The following variables must be provided by the calling playbook or inventory:

Variable	Type	Description
vault_secret_path	string	Path to the secret inside the KV v2 engine (e.g. network/device/creds)
vault_secret_keys	list(string)	List of keys to extract from the secret and expose as Ansible facts

Usage

1. Define vault variables in a dedicated vars file

Create a vars/hc-vault.yml file in your playbook directory:

---
vault_secret_path: myapp/credentials
vault_secret_keys:
  - USERNAME
  - PASSWORD
  - API_KEY

2. Add the role to your roles/requirements.yml

Declare the role so it can be installed via ansible-galaxy:

---
- name: ansible-role-hc-vault
  src: git+ssh://git@gitlab.com/mycompany/ansible-role-hc-vault.git
  version: main

ansible-galaxy role install -r roles/requirements.yml

3. Load the vars file and place the role before any role that needs the secrets

List ansible-role-hc-vault first in the roles: section. Ansible runs roles in order, so all keys from vault_secret_keys will be available as host facts by the time subsequent roles execute:

---
- name: Install and provision My Application
  hosts: all
  become: true
  vars_files:
    - vars/hc-vault.yml

  roles:
    - role: ansible-role-hc-vault
    - role: ansible-role-myapp

After ansible-role-hc-vault runs, all keys listed in vault_secret_keys are available as Ansible facts (e.g. {{ USERNAME }}, {{ PASSWORD }}).

4. Environment setup

Export the required AppRole credentials before running your playbook:

export VAULT_ADDR="https://vault.example.com"
export VAULT_ROLE_ID="<your-role-id>"
export VAULT_SECRET_ID="<your-secret-id>"
export VAULT_MOUNT="kv"   # optional, defaults to 'kv'

ansible-playbook site.yml

Real-world example: ansible-playbook-frrds

vars/hc-vault.yml

---
vault_secret_path: frrds/credentials
vault_secret_keys:
  - AD_JOIN_USER
  - CERT_CA
  - CERT_COMBINED
  - CERT_CRT
  - CERT_KEY
  - KRB5_DOMAIN_REALM_KEY_1
  - KRB5_DOMAIN_REALM_KEY_2
  - KRB5_REALM
  - KRB5_REALM_SERVER
  - LDAP_BASE_DN
  - LDAP_BIND_PASS
  - LDAP_BIND_USER
  - LDAP_SERVER
  - LDAP_SERVER_PORT

freeradius.yml

---
- name: Install and provisioning FreeRADIUS Server
  hosts: all
  become: true
  vars_files:
    - vars/hc-vault.yml

  roles:
    - role: ansible-role-hc-vault
    - role: ansible-role-frrds-server

The secrets fetched from Vault (e.g. {{ CERT_CRT }}, {{ LDAP_BIND_PASS }}, {{ AD_JOIN_USER }}) are consumed directly by ansible-role-frrds-server to configure certificates, LDAP, and AD domain join.

How It Works

Environment Variables
       │
       ▼
┌─────────────────────┐
│  Set Vault facts    │  VAULT_ADDR, VAULT_ROLE_ID, VAULT_SECRET_ID, VAULT_MOUNT
└────────┬────────────┘
         │
         ▼
┌─────────────────────┐
│  AppRole login      │  community.hashi_vault.vault_login
│  (delegate: localhost│  Returns client_token
│   run_once: true)   │
└────────┬────────────┘
         │
         ▼
┌─────────────────────┐
│  Read KV v2 secret  │  community.hashi_vault.vault_kv2_get
│  (delegate: localhost│  path = vault_secret_path
│   run_once: true)   │
└────────┬────────────┘
         │
         ▼
┌─────────────────────┐
│  Assign secret keys │  set_fact for each item in vault_secret_keys
│  as Ansible facts   │  → available as {{ USERNAME }}, {{ PASSWORD }}, …
│  (all hosts)        │  reads from hostvars of first host
└─────────────────────┘

Multi-host note: Vault authentication and secret retrieval run once on localhost. The resulting data is propagated to all hosts in the play via hostvars, so every host gets the facts regardless of inventory size.

Security Considerations

• All tasks that handle credentials or tokens use no_log: true
• Authentication and secret retrieval are delegated to localhost and executed once (run_once: true), reducing exposure across the inventory
• AppRole credentials should be short-lived or scoped tightly to the required Vault policies
• Avoid printing or templating retrieved secrets into files unnecessarily

Platform Support

OS	Versions
Ubuntu	focal, jammy

Metadata

Field	Value
Author	Luis Coutinho
Company	N/A
License	MIT
Min Ansible Version	2.9
Galaxy Tags	networking
Dependencies	none