Intégrer HashiCorp Vault ou OpenBao avec Ansible : lookup, AppRole, KV v2

Quand Ansible Vault ne suffit plus, on délègue le stockage à HashiCorp Vault — ou son fork open-source OpenBao, API-compatible. Bénéfices : secrets dynamiques (credentials DB éphémères), rotation centralisée, audit logs détaillés, TTL automatique, intégration Cloud IAM. Cette page montre comment lookup un secret depuis un playbook avec la collection community.hashi_vault, avec l’authentification token (dev) puis AppRole (production).

À la fin, vous saurez démarrer un Vault local en mode dev, stocker un secret KV v2, le récupérer depuis Ansible, et migrer vers AppRole pour un usage CI/CD réaliste.

# 0. Installer la collection
# ansible-galaxy collection install community.hashi_vault

# Pattern 1 : lookup token (dev/test)
- name: Récupérer un secret KV v2
  ansible.builtin.set_fact:
    db_password: "{{ lookup('community.hashi_vault.vault_kv2_get',
                     'kv/myapp/db',
                     url='https://vault.example.com:8200',
                     token=lookup('env', 'VAULT_TOKEN')).data.password }}"
  no_log: true

# Pattern 2 : AppRole (production CI/CD)
- name: Récupérer un secret avec AppRole auth
  ansible.builtin.set_fact:
    api_token: "{{ lookup('community.hashi_vault.vault_kv2_get',
                   'kv/myapp/api',
                   url='https://vault.example.com:8200',
                   auth_method='approle',
                   role_id=lookup('env', 'VAULT_ROLE_ID'),
                   secret_id=lookup('env', 'VAULT_SECRET_ID')).data.token }}"
  no_log: true

# Pattern 3 : credentials dynamiques (TTL court, rotés automatiquement)
- name: Demander un compte BDD éphémère (valable 1h)
  ansible.builtin.set_fact:
    db_creds: "{{ lookup('community.hashi_vault.vault_read',
                  'database/creds/readonly',
                  url='https://vault.example.com:8200',
                  token=lookup('env', 'VAULT_TOKEN')) }}"
  no_log: true
# db_creds.data.username + db_creds.data.password — valides 1h, auto-révoqués après

Sécurité non négociable :

no_log: true mandatory sur TOUT lookup Vault — sinon le secret apparaît en -v ou en cas d’échec, et atterrit dans Splunk/ELK.
Token court-vécu en dev (-dev mode), AppRole en prod — un token dev n’a pas sa place en prod, jamais.
role_id + secret_id via variables d’env CI/CD secrétées — JAMAIS hardcodés dans le playbook.
TLS strict (validate_certs: true côté lookup, défaut) — un Vault accédé en HTTP ou avec cert non validé = MITM accepté = secrets volés.
Préférer secrets dynamiques (TTL court) aux secrets statiques pour les BDD, AWS STS, etc. — réduit massivement la surface en cas de fuite.
OpenBao = drop-in replacement open-source de HashiCorp Vault — même API, même collection Ansible. Préférer si vous voulez éviter les BSL changes de licence HashiCorp.

Ce que vous allez apprendre

Différence Ansible Vault vs HashiCorp Vault : ce que chaque outil résout.
HashiCorp Vault vs OpenBao : licence, gouvernance, compatibilité API.
Démarrer Vault dev local avec Podman.
vault_kv2_get : lookup dans le moteur KV v2 (versionné).
AppRole : pattern d’authentification recommandé en CI/CD.
Sécurité : pas de token root, TLS, audit log.

Prérequis

Lu Introduction Ansible Vault pour la mise en perspective.
Podman (ou Docker) installé.
Collection community.hashi_vault : ansible-galaxy collection install community.hashi_vault.
Module Python hvac : pipx inject ansible hvac (ou pip install hvac).

HashiCorp Vault vs Ansible Vault — limites des `*.vault.yml`

Ansible Vault chiffre statiquement un fichier YAML. Il atteint ses limites dès que :

La rotation devient régulière : changer un mot de passe DB demande de rechiffrer N rôles.
L’audit fin est exigé : qui a accédé au secret ? Aucune trace dans Ansible Vault.
Les secrets sont dynamiques : credentials DB à TTL court, certificats à émission auto, tokens AWS STS.
Plusieurs équipes se partagent les mêmes secrets : qui peut éditer ? Aucun contrôle granulaire dans Ansible Vault.
Compliance SOC 2 / PCI-DSS exige un coffre dédié certifié.

HashiCorp Vault résout ces 5 points : centralisation, audit, rotation, dynamic secrets, RBAC fin, compliance.

HashiCorp Vault vs OpenBao — quel choisir

En août 2023, HashiCorp est passé d’une licence MPL-2.0 à BSL (Business Source License) : commerciale au-delà d’un seuil de revenus. La Linux Foundation a forké le projet sous le nom OpenBao en MPL-2.0, sous gouvernance neutre.

Critère	HashiCorp Vault	OpenBao
Licence	BSL (commerciale > seuil)	MPL-2.0 (open-source pur)
Gouvernance	HashiCorp (IBM depuis 2024)	Linux Foundation
Enterprise features	DR, MFA SAML, namespaces, Sentinel	Disponibles dans la version Edge
Compatibilité API	Référence	Compatible 95+ %
Communauté	Plus large (historique)	Croissance rapide depuis 2024

Décision pratique : un même playbook Ansible fonctionne avec les deux sans modification. Choisir selon le licensing et la gouvernance souhaitée, pas selon les fonctionnalités.

# Démarrer HashiCorp Vault
podman run -d --name=vault-dev -p 8200:8200 \
  -e VAULT_DEV_ROOT_TOKEN_ID=lab82-root \
  hashicorp/vault:latest

# Ou OpenBao (commande IDENTIQUE, image différente)
podman run -d --name=vault-dev -p 8200:8200 \
  -e VAULT_DEV_ROOT_TOKEN_ID=lab82-root \
  openbao/openbao:latest

Étape 1 — Démarrer Vault local

Le repo de lab fournit un script qui supporte les deux images :

cd labs/vault/integration-hashicorp/

# HashiCorp Vault par défaut
./setup-vault.sh

# Ou OpenBao
IMAGE=openbao/openbao:latest ./setup-vault.sh

Sortie :

[setup-vault] OK — Vault disponible sur http://localhost:8200
  Token : lab82-root
  Path  : secret/lab82

Étape 2 — Stocker un secret KV v2

Le moteur KV v2 (Key-Value version 2) est le moteur de secrets statiques recommandé. Il versionne automatiquement chaque modification (history + rollback).

podman exec -e VAULT_TOKEN=lab82-root vault-lab82 \
  vault kv put secret/lab82 \
    db_password=VaultPassLab82 \
    api_key=vault_api_xyz_lab82

Vérifier :

podman exec -e VAULT_TOKEN=lab82-root vault-lab82 \
  vault kv get secret/lab82

KV v1 vs KV v2 :

KV v1 : pas de versioning, écrase à chaque put. Mode legacy.
KV v2 : versionné, peut rollback à -version=N. Recommandé.

Étape 3 — Récupérer le secret depuis Ansible

Avec la collection community.hashi_vault :

- name: Démo lookup HashiCorp Vault / OpenBao
  hosts: localhost
  connection: local
  gather_facts: false

  vars:
    db_password: "{{ lookup('community.hashi_vault.vault_kv2_get',
                            'lab82',
                            engine_mount_point='secret',
                            url=hashi_vault_url,
                            token=hashi_vault_token).secret.db_password }}"

  tasks:
    - name: Vérifier la lookup
      ansible.builtin.debug:
        msg: "DB password length: {{ db_password | length }}"

Lancer :

ansible-playbook playbook.yml \
  -e "hashi_vault_url=http://localhost:8200" \
  -e "hashi_vault_token=lab82-root"

Sortie :

TASK [Vérifier la lookup] ***
ok: [localhost] =>
  msg: "DB password length: 14"

Bénéfice clé : le playbook ne contient aucun secret en clair. La lookup va chercher la valeur au runtime depuis Vault. Si on rote le mot de passe dans Vault, le prochain run récupère la nouvelle valeur automatiquement.

Étape 4 — Authentification AppRole en production

En production, on n’utilise pas le token root. Le pattern recommandé est AppRole : Vault génère un role_id (public, peut être commité) et un secret_id (TTL court, renouvelé par job CI).

Configurer AppRole

# Activer le backend AppRole
podman exec -e VAULT_TOKEN=lab82-root vault-lab82 \
  vault auth enable approle

# Créer une policy ansible-readonly
podman exec -e VAULT_TOKEN=lab82-root vault-lab82 sh -c '
cat << EOF | vault policy write ansible-readonly -
path "secret/data/lab82" {
  capabilities = ["read"]
}
EOF
'

# Créer un AppRole "ansible-app"
podman exec -e VAULT_TOKEN=lab82-root vault-lab82 \
  vault write auth/approle/role/ansible-app \
    token_policies="ansible-readonly" \
    token_ttl=1h \
    token_max_ttl=4h

# Récupérer role_id (public) et secret_id (sensible, TTL court)
ROLE_ID=$(podman exec -e VAULT_TOKEN=lab82-root vault-lab82 \
  vault read -field=role_id auth/approle/role/ansible-app/role-id)
SECRET_ID=$(podman exec -e VAULT_TOKEN=lab82-root vault-lab82 \
  vault write -field=secret_id -f auth/approle/role/ansible-app/secret-id)

Utiliser AppRole dans le playbook

- name: Lookup avec AppRole
  vars:
    db_password: "{{ lookup('community.hashi_vault.vault_kv2_get',
                            'lab82',
                            engine_mount_point='secret',
                            url=vault_url,
                            auth_method='approle',
                            role_id=role_id,
                            secret_id=secret_id).secret.db_password }}"

Lancer en CI/CD :

ansible-playbook playbook.yml \
  -e "vault_url=https://vault.prod.example.com" \
  -e "role_id=$VAULT_ROLE_ID" \
  -e "secret_id=$VAULT_SECRET_ID"

Pattern de sécurité :

role_id est public, peut être commité dans Git (équivalent d’un username).
secret_id est sensible, généré à la volée, TTL 15 minutes. Le pipeline CI le récupère via une étape sécurisée (un autre lookup Vault, un secret manager du CI), l’injecte au job, le révoque après.

Sécurité — bonnes pratiques 2026

Pas de token en clair dans playbook.yml — toujours via env var (VAULT_TOKEN) ou --extra-vars.
AppRole en CI/CD avec secret_id éphémère renouvelé par job.
TLS mandatory en production : https://, certificat pinné via ca_cert=.
Audit log activé : vault audit enable file file_path=/var/log/vault/audit.log.
Policy restrictives : least-privilege, un AppRole par projet/environnement.
Rotation périodique des secret_id AppRole (toutes les heures, voire à chaque pipeline).

Lab pratique

Le lab vault/integration-hashicorp du repo ansible-training reproduit ce parcours avec 6 tests pytest qui valident :

Le script setup-vault.sh est présent et exécutable.
Il supporte HashiCorp Vault et OpenBao via la variable IMAGE.
Le playbook utilise bien la lookup community.hashi_vault.vault_kv2_get.
Aucun secret en clair n’est commité dans le playbook.

Suivre : labs/vault/integration-hashicorp/README.md.

Pour aller plus loin

Auth Kubernetes : Vault s’intègre avec les service accounts K8s pour rotation automatique.
Auth AWS IAM / Azure AD / GCP : pas de credentials statiques à stocker.
Dynamic secrets : Vault génère des credentials DB éphémères (PostgreSQL, MySQL, MongoDB).
Vault PKI : émission automatique de certificats X.509 internes.
Vault + Ansible Tower / AAP : Vault Credential Type intégré nativement.
Combinaison Passbolt + Vault : voir page suivante.

À retenir

HashiCorp Vault / OpenBao complètent Ansible Vault dès qu’on a besoin de rotation centralisée, dynamic secrets, ou audit fin.
API compatible entre les deux — choisir selon licence et gouvernance, pas selon fonctionnalités.
community.hashi_vault.vault_kv2_get : lookup standard, pas de secret en clair dans le playbook.
AppRole est le pattern d’authentification recommandé en CI/CD (role_id public, secret_id éphémère).
TLS mandatory + audit log + policies least-privilege en production.
Combinaison hybride : Ansible Vault pour les configs versionnées, HashiCorp Vault pour les secrets dynamiques.

Prochaines étapes

Intégration Passbolt (humains) Gestionnaire de mots de passe d'équipe OpenPGP, complément à Vault pour les workflows humains.

Vault dans les rôles Pattern defaults/main.yml + vars/main.yml chiffré, surchargeable par lookup HashiCorp Vault.

Multi-environnements vault-id Combinaison vault-id local + AppRole différent par environnement.

Lab 82 sur GitHub Suivre le lab pas à pas, support HashiCorp Vault ET OpenBao.