Vault KV : stocker et versionner vos secrets statiques

Le secrets engine KV (Key-Value) est le plus utilisé dans Vault. Il stocke des paires clé/valeur comme des mots de passe, clés API ou tokens. La version KV v2 ajoute le versioning : chaque modification crée une nouvelle version, permettant de récupérer ou restaurer des valeurs précédentes.

Ce guide couvre toutes les opérations sur les secrets KV v2, du stockage basique au contrôle de concurrence avec Check-and-Set.

KV v2 ne remplace pas les secrets dynamiques

KV v2 est le bon choix pour les secrets statiques (imposés par des systèmes externes, ou partagés avec des tiers). Mais dès que Vault peut générer un secret dynamique (database, AWS, PKI, SSH), privilégiez cette approche : rotation automatique, révocation native, et exposition limitée dans le temps.

Prérequis

Installer Vault Installation et premier démarrage

• Vault installé et démarré (mode dev ou production)
• Variables d’environnement configurées (VAULT_ADDR, VAULT_TOKEN)

Comprendre KV v1 vs KV v2

Vault propose deux versions du secrets engine KV :

Aspect	KV v1	KV v2
Versioning	Non	Oui (conserve les versions)
Soft delete	Non	Oui (récupérable)
Check-and-Set	Non	Oui (évite les écrasements)
Métadonnées	Basiques	Complètes (timestamps, custom)
Cas d’usage	Legacy, très haute performance	Standard, recommandé

Glissez pour voir

Mode dev uniquement

En mode dev (vault server -dev), KV v2 est automatiquement activé sur le path secret/. En environnement auto-hébergé ou production, vous devez activer explicitement le moteur.

Activer KV v2 (production)

# Activer KV v2 sur le path "secret/"
vault secrets enable -path=secret kv-v2

# Vérifier l'activation
vault secrets list | grep secret

Stocker un secret

La commande vault kv put crée ou met à jour un secret.

Syntaxe de base

# Forme classique : path complet
vault kv put secret/chemin/du/secret clé1="valeur1" clé2="valeur2"

# Forme avec -mount (plus explicite)
vault kv put -mount=secret chemin/du/secret clé1="valeur1" clé2="valeur2"

L'option -mount=

La syntaxe -mount=secret chemin/relatif rend plus visible la séparation entre le mount point (où le moteur est monté) et le chemin relatif (votre organisation). C’est particulièrement utile pour les policies et l’API HTTP.

Exemple concret

Imaginons une application web qui a besoin de se connecter à une base de données PostgreSQL :

vault kv put -mount=secret apps/webapp/database \
    host="db.example.com" \
    port="5432" \
    username="webapp_user" \
    password="SuperSecret123!"

Sortie :

===== Secret Path =====
secret/data/apps/webapp/database

======= Metadata =======
Key                Value
---                -----
created_time       2026-03-16T13:32:40.176016777Z
custom_metadata    <nil>
deletion_time      n/a
destroyed          false
version            1

Comprendre les chemins API (path réel vs logique)

Vous écrivez sur secret/apps/webapp/database, mais Vault stocke sur secret/data/apps/webapp/database. Pourquoi ?

KV v2 utilise des sous-chemins API pour séparer les opérations :

Opération	Chemin API	Exemple
Données (CRUD)	secret/data/...	secret/data/apps/webapp/database
Métadonnées	secret/metadata/...	secret/metadata/apps/webapp/database
Suppression (versions)	secret/delete/...	secret/delete/apps/webapp/database
Restauration	secret/undelete/...	secret/undelete/apps/webapp/database
Destruction	secret/destroy/...	secret/destroy/apps/webapp/database

Glissez pour voir

La CLI masque cette complexité, mais vous la verrez dans :

• les policies Vault (capabilities sur secret/data/*)
• l’API HTTP directe
• les intégrations tierces (Terraform, Kubernetes operator…)

Impact sur les policies

Une policy qui donne read sur secret/apps/* ne fonctionnera pas pour KV v2. Il faut écrire secret/data/apps/* pour les données et secret/metadata/apps/* pour les métadonnées.

Écrire des valeurs depuis un fichier

Vault accepte plusieurs formats d’entrée. Pour des secrets complexes, vous pouvez lire depuis un fichier.

Option 1 : Paires clé=valeur depuis stdin

# stdin avec le préfixe @- (tiret = stdin)
echo '{"api_key":"sk-abc123","api_secret":"secret-xyz789"}' | \
    vault kv put -mount=secret apps/webapp/api-config -

Le contenu JSON est interprété comme plusieurs paires clé=valeur. Vault stockera deux champs : api_key et api_secret.

Option 2 : Stocker un blob entier

Si vous voulez stocker un fichier entier (certificat, clé privée) comme une seule valeur :

vault kv put -mount=secret apps/webapp/tls-cert \
    cert="$(cat server.crt)" \
    key="$(cat server.key)"

Option 3 : Fichier JSON avec @

# Le fichier doit contenir un objet JSON avec les paires clé-valeur
cat > creds.json << 'EOF'
{
  "username": "admin",
  "password": "secret123"
}
EOF

vault kv put -mount=secret apps/webapp/creds @creds.json

# Nettoyer
rm creds.json

Cette commande crée un secret avec deux champs : username et password.

Lire un secret

Lecture simple

vault kv get -mount=secret apps/webapp/database

Sortie :

===== Secret Path =====
secret/data/apps/webapp/database

======= Metadata =======
Key                Value
---                -----
created_time       2026-03-16T13:32:40.176016777Z
custom_metadata    <nil>
deletion_time      n/a
destroyed          false
version            1

====== Data ======
Key         Value
---         -----
host        db.example.com
password    SuperSecret123!
port        5432
username    webapp_user

Extraire une valeur spécifique

Pour l’intégration dans des scripts, extrayez une seule valeur :

# Extraire le mot de passe
vault kv get -mount=secret -field=password apps/webapp/database
# SuperSecret123!

Format JSON

Pour le parsing automatisé, utilisez le format JSON :

vault kv get -mount=secret -format=json apps/webapp/database | \
    jq -r '.data.data.password'
# SuperSecret123!

Double .data

La structure JSON de réponse KV v2 a deux niveaux data : .data contient les métadonnées, .data.data contient les valeurs.

Éviter les écrasements avec Check-and-Set

Quand plusieurs processus écrivent sur le même secret, il y a un risque d’écrasement silencieux. Check-and-Set (CAS) résout ce problème.

Le problème

Sans CAS, si deux processus modifient le même secret en parallèle :

1. Processus A lit la version 5
2. Processus B lit la version 5
3. Processus A écrit → version 6
4. Processus B écrit → version 7, écrasant les changements de A

La solution : -cas

L’option -cas=<version> impose que l’écriture ne réussisse que si la version courante correspond :

# Écrire seulement si la version actuelle est 2
vault kv put -mount=secret -cas=2 apps/webapp/database \
    password="NewSecurePassword!"

Si un autre processus a modifié le secret entre-temps :

Error writing data to secret/data/apps/webapp/database: Error making API request.

Code: 400. Errors:
* check-and-set parameter did not match the current version

Créer seulement si n’existe pas

-cas=0 crée le secret uniquement s’il n’existe pas :

# Échoue si le secret existe déjà
vault kv put -mount=secret -cas=0 apps/webapp/new-secret \
    api_key="sk-newkey123"

Forcer CAS au niveau métadonnées

Vous pouvez imposer l’usage de CAS pour tous les écrivains :

# Toute écriture sans -cas échouera
vault kv metadata put -mount=secret -cas-required=true apps/webapp/database

Tentative d’écriture sans CAS :

Error writing data to secret/data/apps/webapp/database: Error making API request.

Code: 400. Errors:
* check-and-set parameter required for this call

Quand activer cas-required

Activez cas-required sur les secrets critiques (credentials partagés, configurations sensibles) où une écriture concurrente pourrait causer des problèmes.

Versioning

Chaque modification d’un secret crée une nouvelle version. C’est l’un des avantages majeurs de KV v2.

Mettre à jour un secret

Quand vous modifiez un secret, la version incrémente automatiquement :

# Mise à jour du mot de passe (crée version 2)
vault kv put -mount=secret apps/webapp/database \
    host="db.example.com" \
    port="5432" \
    username="webapp_user" \
    password="NewPassword456!"

Sortie :

...
version            2

Lire une version spécifique

Vous pouvez récupérer n’importe quelle version antérieure :

# Lire la version 1 (ancien mot de passe)
vault kv get -mount=secret -version=1 apps/webapp/database

Voir l’historique des versions

vault kv metadata get -mount=secret apps/webapp/database

Sortie (extrait) :

======= Metadata =======
Key                     Value
---                     -----
cas_required            false
created_time            2026-03-16T13:32:40.176016777Z
current_version         2
delete_version_after    0s
max_versions            0
oldest_version          0
updated_time            2026-03-16T13:45:12.234567890Z

====== Version 1 ======
Key              Value
---              -----
created_time     2026-03-16T13:32:40.176016777Z
deletion_time    n/a
destroyed        false

====== Version 2 ======
Key              Value
---              -----
created_time     2026-03-16T13:45:12.234567890Z
deletion_time    n/a
destroyed        false

Revenir à une version antérieure

Si une mise à jour pose problème, vous pouvez “rollback” :

# Restaurer la version 1 comme nouvelle version (crée version 3)
vault kv rollback -mount=secret -version=1 apps/webapp/database

Rollback = nouvelle version

Le rollback ne supprime pas l’historique. Il crée une nouvelle version avec le contenu de l’ancienne. L’historique reste intact pour l’audit.

Supprimer des secrets

KV v2 distingue plusieurs niveaux de suppression. Le modèle mental :

Action	Effet	Réversible ?
delete	Masque la version (soft delete)	✅ Oui (undelete)
undelete	Rend la version visible à nouveau	—
destroy	Supprime les données de la version	❌ Non
metadata delete	Supprime tout : versions + métadonnées	❌ Non

Glissez pour voir

Delete (soft delete)

Marque la version comme supprimée mais conserve les données :

vault kv delete -mount=secret apps/webapp/database

Les données ne sont plus accessibles par un get normal :

vault kv get -mount=secret apps/webapp/database
# Affiche uniquement les métadonnées, pas les données

Undelete (restauration)

Annule un soft delete :

# Restaurer la version 2
vault kv undelete -mount=secret -versions=2 apps/webapp/database

Les données sont à nouveau accessibles.

Destroy (suppression définitive des données)

Supprime définitivement les données d’une ou plusieurs versions :

# Supprimer définitivement les versions 1 et 2
vault kv destroy -mount=secret -versions=1,2 apps/webapp/database

Destroy est irréversible

Contrairement à delete, destroy supprime définitivement les données. Les métadonnées de la version existent encore (avec destroyed: true), mais les valeurs sont perdues. Aucune restauration possible.

Supprimer l’objet secret entier

Pour supprimer complètement un secret (toutes versions + métadonnées) :

vault kv metadata delete -mount=secret apps/webapp/database

Cette commande supprime tout : le secret n’existe plus dans Vault.

Organiser vos secrets pour les policies

Une bonne organisation facilite la gestion des policies et la maintenance. La structure de vos chemins détermine directement vos policies de sécurité.

Structure recommandée

secret/
├── apps/                    # Secrets applicatifs
│   ├── webapp/
│   │   ├── database         # Credentials DB
│   │   ├── api-keys         # Clés API tierces
│   │   └── config           # Config sensible
│   └── mobile-app/
│       └── firebase
├── infra/                   # Secrets infrastructure
│   ├── aws/
│   │   └── credentials
│   └── docker-registry/
│       └── credentials
└── teams/                   # Secrets par équipe
    ├── dev/
    └── ops/

Pourquoi cette structure ?

Cette hiérarchie permet d’écrire des policies précises sans wildcards trop larges :

# Policy pour l'application webapp (lecture seule)
path "secret/data/apps/webapp/*" {
  capabilities = ["read"]
}

# Policy pour l'équipe ops (lecture/écriture sur infra)
path "secret/data/infra/*" {
  capabilities = ["create", "update", "read", "delete"]
}

path "secret/metadata/infra/*" {
  capabilities = ["list", "read"]
}

N'oubliez pas secret/data/ et secret/metadata/

Comme vu plus haut, les policies KV v2 doivent cibler les chemins API (secret/data/* pour les données, secret/metadata/* pour les métadonnées).

Critères d’organisation

Critère	Exemple de chemin	Avantage
Par application	secret/apps/webapp/...	Isolation par service
Par environnement	secret/prod/..., secret/dev/...	Séparation prod/dev
Par équipe	secret/teams/backend/...	Ownership clair
Par type	secret/databases/..., secret/api-keys/...	Gestion transverse

Glissez pour voir

Combinez ces critères selon votre contexte : secret/prod/apps/webapp/database ou secret/apps/webapp/prod/database.

Lister les secrets

# Lister les secrets sous un chemin
vault kv list -mount=secret apps/

Sortie :

Keys
----
webapp/
mobile-app/

Métadonnées personnalisées

Ajoutez des métadonnées pour documenter vos secrets :

vault kv metadata put -mount=secret \
    -custom-metadata="owner=team-backend" \
    -custom-metadata="environment=production" \
    -custom-metadata="rotation=90days" \
    apps/webapp/database

Les métadonnées ne déclenchent rien

custom_metadata sert à documenter et pister vos secrets, mais ce n’est pas un moteur de rotation automatique. Écrire rotation=90days ne déclenche aucune action — c’est un marqueur pour vos processus externes (scripts de rotation, alertes…).

Limiter les versions conservées

Par défaut, Vault conserve toutes les versions. Cela peut poser problème :

• Croissance du stockage
• Conservation d’anciennes valeurs sensibles plus longtemps que nécessaire

Limitez avec -max-versions :

# Conserver uniquement les 10 dernières versions
vault kv metadata put -mount=secret -max-versions=10 apps/webapp/database

Définir une valeur par défaut

Vous pouvez configurer -max-versions au niveau du moteur KV entier via vault secrets tune. Toutes les nouvelles clés hériteront de cette limite.

Suppression automatique après soft delete

Configurez un délai avant suppression définitive des versions soft-deleted :

# Supprimer définitivement 24h après un delete
vault kv metadata put -mount=secret -delete-version-after=24h apps/webapp/database

Consommation par les applications

Ce guide montre la gestion via CLI. En production, vos applications consomment les secrets via d’autres méthodes :

Méthode	Usage typique
API HTTP	Intégration directe dans le code
Agent + templates	Injection dans fichiers de config
CSI driver	Montage comme volume Kubernetes
Vault Secrets Operator	Synchronisation vers Secrets K8s

Glissez pour voir

Guides à venir

Les guides sur l’agent Vault et l’intégration Kubernetes détailleront ces méthodes de consommation.

Ce que KV v2 ne fait pas

KV v2 améliore énormément la gestion des secrets statiques, mais il a des limites structurelles :

Capacité	KV v2	Alternative Vault
Générer des secrets dynamiques	❌	Database, AWS, Azure…
Rotation automatique côté cible	❌	Database secrets engine
Chiffrement de données applicatives	❌	Transit
Certificats X.509	❌	PKI
Clés SSH signées	❌	SSH secrets engine

Glissez pour voir

Règle simple : si vous pouvez éviter un secret statique, faites-le.

• Base de données → Database secrets engine (credentials éphémères)
• Cloud provider → AWS/Azure/GCP secrets engine
• Certificats → PKI secrets engine
• SSH → SSH secrets engine avec certificats

KV v2 reste indispensable pour :

• Clés API tierces (imposées par le fournisseur)
• Secrets legacy (systèmes non intégrables)
• Tokens partagés (Slack webhooks, API tokens…)
• Bootstrap secrets (premiers credentials pour accéder au reste)

Dépannage

Symptôme	Cause probable	Solution
no value found at secret/data/...	Secret inexistant ou supprimé	Vérifier le path, utiliser undelete
permission denied	Policy insuffisante	Vérifier les capabilities read, list sur secret/data/...
check-and-set parameter did not match	Écriture concurrente	Relire la version actuelle, utiliser -cas=<version>
check-and-set parameter required	cas-required=true sur la clé	Ajouter -cas=<version> à la commande
Version non trouvée	Version détruite	Vérifier avec metadata get
Versions anciennes inaccessibles	max-versions atteint	Augmenter la limite ou accepter la perte

Glissez pour voir

À retenir

1. KV v2 est le standard pour les secrets statiques — préférez les secrets dynamiques quand c’est possible
2. Check-and-Set (-cas) évite les écrasements concurrents — activez -cas-required sur les secrets critiques
3. La CLI masque les chemins API — vos policies doivent cibler secret/data/* et secret/metadata/*
4. delete = soft delete récupérable, destroy = définitif, metadata delete = suppression totale
5. Organisez vos secrets pour faciliter les policies : par application/environnement/équipe
6. Les métadonnées personnalisées documentent mais ne déclenchent rien
7. Limitez les versions avec -max-versions pour éviter la croissance infinie et la rétention excessive

Prochaines étapes

Transit : chiffrement as a service Chiffrer vos données sans gérer les clés

Policies Contrôler qui accède à quels secrets

Authentification Configurer l'accès pour vos applications

×

📖 Voir la documentation →