HashiVault Role¶

Overview¶

This Ansible role deploys HashiCorp Vault, a powerful secrets management tool, as a containerized service using rootless Podman. It provides secure storage for sensitive data such as API keys, passwords, and certificates, with features like systemd integration, multiple secret engines, a web UI, automatic unsealing, and audit logging.

Requirements¶

Podman 4.x or later
Systemd
A user with sudo access
SELinux if running on a RHEL/CentOS-based system.

Installation / Quick Start¶

Orchestrator¶

The deployment process is broken down into several steps:

Prepare: Creates the necessary directory structure and configuration.
```
./manage-svc.sh hashivault prepare
```
Deploy: Creates and starts the Vault container.
```
./manage-svc.sh hashivault deploy
```
Initialize: Initializes Vault and securely stores the unseal keys and root token.
```
./svc-exec.sh hashivault initialize
```
Configure: Sets up authentication methods and secret engines.
```
./svc-exec.sh hashivault configure
```
Set Up Secret Engines: Enables and populates additional secret engines.
```
./svc-exec.sh hashivault vault-secrets
```

Role Variables / Configuration¶

Installation State¶

Name	Description	Default
`hashivault_state`	`present` to install, `absent` to remove.	`present`
`vault_force_reload`	Force a reload of the service.	`false`
`vault_delete_data`	Delete data on removal.	`false`

Container Settings¶

Name	Description	Default
`vault_image`	The Vault container image.	`docker.io/hashicorp/vault:1.15`
`vault_data_dir`	The directory to store Vault data.	`{{ ansible_user_dir }}/vault-data`
`vault_api_port`	The port for the Vault API.	`8200`
`vault_cluster_port`	The port for cluster communication.	`8201`

Security Settings¶

Name	Description	Default
`vault_enable_ui`	Enable the built-in web UI.	`true`
`vault_enable_audit`	Enable audit logging.	`true`

TLS Configuration¶

Name	Description	Default
`vault_enable_tls`	Enable TLS for the Vault API.	`false`
`vault_tls_cert_file`	Path to your TLS certificate.	`""`
`vault_tls_key_file`	Path to your TLS private key.	`""`
`vault_tls_ca_file`	Path to your optional CA certificate.	`""`

Usage¶

After deployment, the Vault UI is available at http://localhost:8200/ui.

Storing and Reading Secrets¶

# Login with root token or admin credentials
export VAULT_ADDR='http://localhost:8200'
vault login

# Store a secret
vault kv put kv/myapp/config username=admin password=secret123

# Read the secret
vault kv get kv/myapp/config

Service Management¶

# Check status
systemctl --user status vault-pod

# View logs
podman logs vault-svc

# Restart
systemctl --user restart vault-pod

Troubleshooting¶

Cannot Unseal Vault¶

Check if Vault is running: systemctl --user status vault-pod
Verify the keys file is readable: cat ~/.secrets/vault-secrets/vault-keys.json
Check Vault status: podman exec vault-svc vault status

API Connection Issues¶

Verify Vault is running and unsealed.
Check API port accessibility: curl -v http://localhost:8200/v1/sys/health

Role-Specific Sections¶

Initial Secrets Configuration¶

Initial secrets can be configured in your inventory:

vault_initial_secrets:
  - path: "kv/ansible/vault"
    data:
      provision_vault_password: "{{ lookup('env', 'PROVISION_VAULT_PASSWORD') }}"

Unsealing and Backup¶

Unseal: ./svc-exec.sh hashivault unseal
Backup: ./svc-exec.sh hashivault backup

Reference¶

License¶

MIT

Author¶

Created by jackaltx and Claude.