ansible-modules-hashivault

You can install these Ansible modules for HashiCorp Vault using either pip or ansible-galaxy.

Note: If you install via ansible-galaxy, the hashicorp lookup plugin will not work due to an Ansible limitation. In that case, fallback to the built-in hashi_vault lookup plugin.

Requirements: hvac>=2.1.0 is required for the ansible-galaxy installation method.

# Via pip
pip install ansible-modules-hashivault

# Via ansible-galaxy
ansible-galaxy install 'git+https://github.com/TerryHowe/ansible-modules-hashivault.git'

You can use the automated functional tests to spin up an initialized Vault instance running in Docker. The ./start.sh script in the functional directory initializes Vault and generates a vaultenv.sh file containing the necessary environment variables for communication.

cd ../functional
./start.sh
source ./vaultenv.sh

Before using the modules, you must install the package via pip.

pip install ansible-modules-hashivault

You can verify that the playbook successfully wrote the secret by SSHing into the sandbox container. Note that the container uses port 3022 and the identity file .ssh/id_rsa.

Note: If you run the sandbox multiple times, you may need to clear the entry in your ~/.ssh/known_hosts file to avoid SSH host key verification errors.

$ ssh -i .ssh/id_rsa -p 3022 root@127.0.0.1
root@sandbox:~# cat /giant.txt 
I smell the blood

Check the status of your sandbox container using docker ps to ensure the SSH service is active and ports are mapped.

$ docker ps
CONTAINER ID        IMAGE                     COMMAND                  CREATED             STATUS              PORTS
3b214f80daf0        sandbox:latest            "/usr/sbin/sshd -D"      6 minutes ago       Up 6 minutes        127.0.0.1:3022->22/tcp

The hashivault_secret module (which defaults to KV version 2) and hashivault_read can be used to manage secrets. By default, these assume the /secret mount point. To use a different mount point, specify the mount_point parameter.

To support KV version 2 explicitly, use the version: 2 parameter.

- hosts: localhost
  tasks:
    - hashivault_secret:
        secret: giant
        data:
            foo: foe
            fie: fum
    - hashivault_read:
        secret: giant
        key: fie
        version: 2
      register: vault_read

# Using a custom mount point
- hosts: localhost
  tasks:
    - hashivault_write:
        mount_point: /stories
        secret: stuart
        data:
            last: 'little'
    - hashivault_read:
        mount_point: /stories
        secret: stuart
        key: last
        version: 2

You can retrieve secrets directly within Ansible templates or facts using the hashivault lookup plugin. You can specify the mount_point and version (for KV v2) within the lookup call.

# Basic lookup
- set_fact:
    looky: "{{lookup('hashivault', 'giant', 'foo', version=2)}}"

# Lookup with custom mount point and version
- set_fact:
    book: "{{lookup('hashivault', 'stuart', 'last', mount_point='/stories', version=2)}}"

The modules provide administrative capabilities to manage the Vault lifecycle, including initialization, checking status, sealing, and unsealing.

- hosts: localhost
  vars:
    vault_keys: "{{ lookup('env','VAULT_KEYS') }}"
  tasks:
    - hashivault_init:
        register: vault_init

    - hashivault_status:
        register: vault_status

    - block:
        - hashivault_seal:
            register: vault_seal
      when: "{{vault_status.status.sealed}} == False"

    - hashivault_unseal:
        keys: '{{vault_keys}}'

Once the sandbox is running, you can execute the sample playbook test_remote_host.yml. This playbook writes a secret to Vault and then writes that secret to a file within the sandbox container.

ansible-playbook test_remote_host.yml