Values Helm : personnaliser proprement avec -f et --set

Ce guide vous apprend à personnaliser vos déploiements Helm sans modifier les charts. Vous allez maîtriser les fichiers values.yaml pour gérer plusieurs environnements (dev, staging, prod), comprendre l'ordre de précédence des surcharges, et éviter les pièges courants de --set. En 20 minutes, vous saurez configurer n'importe quel chart de manière reproductible.

Ce que vous allez apprendre

• Lire les valeurs par défaut d'un chart avec helm show values
• Surcharger une valeur en ligne de commande avec --set, --set-string et --set-json
• Structurer des fichiers values-<env>.yaml pour dev, staging et production
• Appliquer l'ordre de précédence entre défauts, fichiers -f et --set
• Conserver les values existantes lors d'un helm upgrade
• Vérifier le résultat avec helm get values et helm template

Prérequis

• Helm installé et un repo configuré (voir module H1-02)
• Un cluster Kubernetes fonctionnel (minikube, kind, k3d)
• Avoir compris helm install (voir module H1-03)

Comprendre le système de values

Comment fonctionne la personnalisation ?

Chaque chart Helm contient un fichier values.yaml avec des valeurs par défaut. Quand vous installez un chart, Helm fusionne vos surcharges avec ces valeurs par défaut, puis injecte le résultat dans les templates pour générer les manifests Kubernetes.

Voir les values par défaut d'un chart

Un chart n'expose que les paramètres que son auteur a décidé de rendre configurables. Surcharger une clé qui n'existe pas dans values.yaml ne produit aucune erreur : Helm l'ajoute silencieusement à l'arbre de values, et le template l'ignore. C'est la première cause de « ma surcharge ne fait rien ». Commencez donc toujours par lire les valeurs disponibles :

helm show values podinfo/podinfo

Résultat (extrait) :

# Default values for podinfo.

replicaCount: 1
logLevel: info

image:
  repository: ghcr.io/stefanprodan/podinfo
  tag: 6.14.1
  pullPolicy: IfNotPresent

ui:
  color: "#34577c"
  message: ""

service:
  enabled: true
  type: ClusterIP
  httpPort: 9898

resources:
  limits:
  requests:
    cpu: 1m
    memory: 16Mi

Ce que vous devez repérer :

Élément	Signification
Structure hiérarchique	ui.color signifie ui: → color:
Valeurs vides ("", {}, [])	À compléter si besoin
Valeurs commentées	Options disponibles mais désactivées
Types de données	Nombres (1), strings ("info"), booléens (true), objets, listes

Glissez pour voir

Surcharger avec --set (rapide mais limité)

L'option --set modifie une valeur directement en ligne de commande, sans créer de fichier. C'est pratique en exploration, mais la surcharge n'existe alors que dans votre historique de shell : elle n'est ni versionnée, ni relisible par un collègue, et elle disparaît au prochain helm upgrade qui ne la répète pas. Réservez-la aux essais, et basculez vers -f dès que la valeur doit survivre.

helm install demo podinfo/podinfo \
  --namespace helm-demo \
  --create-namespace \
  --set replicaCount=2 \
  --set ui.message="Hello DevOps"

Résultat :

NAME: demo
LAST DEPLOYED: Sun Feb  1 18:10:59 2026
NAMESPACE: helm-demo
STATUS: deployed
REVISION: 1

Vérifier les values utilisées

Helm stocke les values dans le secret de la release, pas dans un fichier sur votre poste : vous pouvez donc les relire même depuis une autre machine, à condition d'avoir accès au namespace. La commande helm get values montre par défaut uniquement les surcharges, ce qui répond à la question « qu'est-ce que quelqu'un a changé ici ? » :

helm get values demo -n helm-demo

Résultat :

USER-SUPPLIED VALUES:
replicaCount: 2
ui:
  message: Hello DevOps

Pour voir toutes les values (défaut + surcharges fusionnées) :

helm get values demo -n helm-demo --all

Résultat (extrait) :

COMPUTED VALUES:
image:
  pullPolicy: IfNotPresent
  repository: ghcr.io/stefanprodan/podinfo
  tag: 6.14.1
logLevel: info
replicaCount: 2          # ← Votre surcharge
ui:
  color: '#34577c'       # ← Valeur par défaut conservée
  message: Hello DevOps  # ← Votre surcharge

Lecture du résultat :

Section	Contenu
USER-SUPPLIED VALUES	Uniquement vos surcharges
COMPUTED VALUES	Fusion complète (défaut + surcharges)

Glissez pour voir

Syntaxe --set pour différents types

La syntaxe de --set a sa propre grammaire, qui n'est ni du YAML ni du JSON. Deux caractères y sont significatifs et vous piégeront tôt ou tard : la virgule sépare deux affectations, le point descend d'un niveau dans l'arbre. Une valeur qui contient l'un des deux doit donc être échappée avec un antislash, sans quoi Helm la découpe. Les index entre crochets, eux, servent à écrire dans une liste.

Type	Syntaxe	Exemple
Valeur simple	--set key=value	--set replicaCount=3
Valeur imbriquée	--set parent.child=value	--set ui.color="#ff0000"
Liste	--set key[0]=val1,key[1]=val2	--set backends[0]=http://a:80
Objet dans liste	--set list[0].key=value	--set tolerations[0].key=node

Glissez pour voir

Exemple avec une liste (tolerations) :

helm template test podinfo/podinfo \
  --set "tolerations[0].key=node-role.kubernetes.io/master" \
  --set "tolerations[0].effect=NoSchedule"

Génère :

tolerations:
  - effect: NoSchedule
    key: node-role.kubernetes.io/master

--set-string : forcer le type string

Par défaut, --set interprète les valeurs :

• 123 → nombre
• true → booléen
• null → null

Si vous avez besoin d'une string littérale, utilisez --set-string :

# A EVITER : --set interprète "123" comme un nombre
helm template test podinfo/podinfo --set image.tag=123

# CORRECT : --set-string force la string "123"
helm template test podinfo/podinfo --set-string image.tag="123"

Piège classique

Les tags d'image comme 1.0 ou 2 peuvent être interprétés comme des nombres. Utilisez toujours --set-string pour les tags d'image :

--set-string image.tag="1.0"

--set-json : structures complexes

Écrire un bloc resources complet avec --set demande six affectations et autant d'occasions de se tromper de niveau. L'option --set-json accepte une valeur JSON entière, ce qui préserve la structure et les types d'origine, y compris les listes vides et les objets imbriqués que la syntaxe pointée gère mal :

helm template test podinfo/podinfo \
  --set-json 'resources={"limits":{"cpu":"500m","memory":"256Mi"},"requests":{"cpu":"100m","memory":"128Mi"}}'

Génère :

resources:
  limits:
    cpu: 500m
    memory: 256Mi
  requests:
    cpu: 100m
    memory: 128Mi

Surcharger avec -f (fichier values)

Un fichier de values est un YAML ordinaire dont l'arborescence reproduit celle du values.yaml du chart. Il n'a pas besoin d'être complet : Helm le fusionne avec les défauts, clé par clé, et ne remplace que ce que vous déclarez. C'est cette fusion qui permet de garder des fichiers courts, limités aux écarts par rapport au chart :

values-dev.yaml

# Configuration pour environnement de développement
replicaCount: 1

ui:
  color: "#17a2b8"  # Bleu cyan pour identifier dev
  message: "Environnement DEV"

resources:
  limits:
    cpu: 100m
    memory: 64Mi
  requests:
    cpu: 10m
    memory: 32Mi

logLevel: debug

Utilisez-le avec -f (ou --values) :

helm install demo-dev podinfo/podinfo \
  --namespace helm-demo \
  --create-namespace \
  -f values-dev.yaml

Vérifier les values appliquées

Comparez ce que renvoie helm get values au contenu de votre fichier values-dev.yaml : les deux doivent coïncider clé pour clé. Une différence signale que le fichier n'a pas été pris en compte, souvent parce que le chemin passé à -f était erroné et que Helm a déployé les seuls défauts sans le signaler.

helm get values demo-dev -n helm-demo

Résultat :

USER-SUPPLIED VALUES:
logLevel: debug
replicaCount: 1
resources:
  limits:
    cpu: 100m
    memory: 64Mi
  requests:
    cpu: 10m
    memory: 32Mi
ui:
  color: '#17a2b8'
  message: "Environnement DEV"

Gérer plusieurs environnements

Stratégie de fichiers par environnement

La stratégie la plus courante isole ce qui est commun de ce qui varie. Un fichier values-base.yaml porte les réglages identiques partout (image, ports, sondes), et chaque environnement n'écrit que ses différences. On évite ainsi la dérive silencieuse où un réglage de sécurité présent en staging manque en production parce que les deux fichiers ont été édités séparément.

• Répertoirehelm-config/

  • values-base.yaml Configuration commune
  • values-dev.yaml Surcharges développement
  • values-staging.yaml
  • values-prod.yaml Surcharges production

values-base.yaml (configuration commune) :

image:
  repository: ghcr.io/stefanprodan/podinfo
  pullPolicy: IfNotPresent

service:
  type: ClusterIP
  httpPort: 9898

probes:
  readiness:
    initialDelaySeconds: 1
  liveness:
    initialDelaySeconds: 1

values-prod.yaml (surcharges production) :

replicaCount: 3

ui:
  color: "#28a745"  # Vert pour identifier prod
  message: "Production"

resources:
  limits:
    cpu: 500m
    memory: 256Mi
  requests:
    cpu: 100m
    memory: 128Mi

logLevel: warn

Combiner plusieurs fichiers -f

Vous pouvez passer plusieurs fichiers -f sur la même commande. Helm les fusionne de gauche à droite, et pour une clé présente dans deux fichiers, c'est la valeur du dernier fichier de la ligne qui l'emporte. L'ordre des -f est donc porteur de sens : mettre le fichier de base en premier et l'environnement ensuite garantit que l'environnement gagne, jamais l'inverse.

helm install myapp-prod podinfo/podinfo \
  -n production \
  -f values-base.yaml \
  -f values-prod.yaml

Règle de fusion : les valeurs du dernier fichier gagnent.

# Démonstration de l'ordre de précédence
# values-a.yaml contient replicaCount: 2
# values-b.yaml contient replicaCount: 5

# Fichier A puis B → replicaCount = 5
helm template test podinfo/podinfo -f values-a.yaml -f values-b.yaml

# Fichier B puis A → replicaCount = 2
helm template test podinfo/podinfo -f values-b.yaml -f values-a.yaml

Ordre de précédence complet

Helm applique les values dans cet ordre (du moins au plus prioritaire) :

1. values.yaml du chart (défaut)
      ↓
2. Fichiers -f dans l'ordre (le dernier gagne)
      ↓
3. --set / --set-string / --set-json (plus prioritaire)

Exemple concret :

# Le chart a replicaCount: 1 par défaut
# values-dev.yaml a replicaCount: 2
# --set définit replicaCount=5

helm install demo podinfo/podinfo \
  -f values-dev.yaml \
  --set replicaCount=5

# Résultat : replicaCount = 5 (--set gagne)

Règle d'or

Fichiers pour la configuration stable (ressources, replicas, images) --set pour les overrides ponctuels (debug, tests)

En CI/CD, privilégiez les fichiers -f : ils sont versionnés, auditables et reproductibles.

Comportement lors des upgrades

--reuse-values : conserver les values existantes

Le comportement par défaut de helm upgrade surprend beaucoup de débutants : sans option ni fichier, un upgrade qui ne passe qu'un seul --set repart des valeurs par défaut du chart et perd toutes les surcharges de l'installation précédente. Le drapeau --reuse-values rétablit l'intuition attendue : il repart des values de la dernière release et n'applique que vos nouveaux --set par-dessus.

# Installation initiale avec plusieurs values
helm install demo podinfo/podinfo -n helm-demo \
  -f values-dev.yaml

# Upgrade en conservant les anciennes values + ajout d'une nouvelle
helm upgrade demo podinfo/podinfo -n helm-demo \
  --reuse-values \
  --set replicaCount=3

Avant upgrade :

logLevel: debug
replicaCount: 1
ui:
  color: '#17a2b8'

Après upgrade avec --reuse-values :

logLevel: debug      # ← Conservé
replicaCount: 3      # ← Modifié par --set
ui:
  color: '#17a2b8'   # ← Conservé

--reset-values : repartir de zéro

Pour ignorer les anciennes values et repartir des valeurs par défaut :

helm upgrade demo podinfo/podinfo -n helm-demo \
  --reset-values \
  --set ui.message="Fresh start"

Après upgrade avec --reset-values :

ui:
  message: Fresh start  # ← Seule surcharge, tout le reste = défaut

Piège courant

Sans --reuse-values ni -f, un helm upgrade avec juste --set perd toutes les anciennes values. C'est souvent la cause de régressions en production.

# DANGEREUX : perd les anciennes values
helm upgrade demo podinfo/podinfo --set newValue=xyz

# SECURISE : conserve les anciennes values
helm upgrade demo podinfo/podinfo --reuse-values --set newValue=xyz

Visualiser sans déployer : helm template

helm template effectue le rendu complet des templates avec vos values et affiche les manifests Kubernetes résultants, sans contacter le cluster. C'est l'outil de référence pour vérifier une surcharge avant de la déployer : vous voyez exactement le YAML que Kubernetes recevra, valeur appliquée comprise. Notez qu'il ne joue pas les vérifications côté serveur (schémas d'admission, ressources existantes), il ne remplace donc pas un helm install --dry-run.

helm template demo podinfo/podinfo \
  --set replicaCount=3 \
  --set "ui.message=Test Template"

Résultat (extrait) :

podinfo/templates/deployment.yaml

---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: demo-podinfo
spec:
  replicas: 3   # ← Votre value appliquée

C'est idéal pour :

• Debugger une configuration avant déploiement
• Vérifier ce qui sera créé
• Générer des manifests pour GitOps (ArgoCD, Flux)

Lab A4 : Configuration multi-environnements

Objectif : Créer et tester une configuration multi-environnements avec fichiers values.

Ce lab enchaîne les six commandes que vous rejouerez sur un vrai projet : créer les fichiers par environnement, déployer dev, vérifier le nombre de pods, puis démontrer les deux règles de précédence vues plus haut (conservation avec --reuse-values, priorité de --set sur un fichier). Exécutez-le sur un cluster jetable (k3d, kind), les manifests ne créent que des objets éphémères dans un namespace dédié.

1. Créer le namespace et les fichiers values

   kubectl create namespace helm-lab

   Créez values-base.yaml :

   image:
     repository: ghcr.io/stefanprodan/podinfo
     pullPolicy: IfNotPresent
   
   service:
     type: ClusterIP
     httpPort: 9898

   Créez values-dev.yaml :

   replicaCount: 1
   ui:
     color: "#17a2b8"
     message: "DEV"
   logLevel: debug
   resources:
     limits:
       cpu: 100m
       memory: 64Mi

   Créez values-prod.yaml :

   replicaCount: 3
   ui:
     color: "#28a745"
     message: "PROD"
   logLevel: warn
   resources:
     limits:
       cpu: 500m
       memory: 256Mi

2. Déployer l'environnement dev

   helm install app-dev podinfo/podinfo -n helm-lab \
     -f values-base.yaml \
     -f values-dev.yaml

3. Vérifier les values et les pods

   helm get values app-dev -n helm-lab
   kubectl get pods -n helm-lab

   Attendu : 1 pod (replicaCount: 1)

4. Tester un upgrade avec --reuse-values

   helm upgrade app-dev podinfo/podinfo -n helm-lab \
     --reuse-values \
     --set ui.message="DEV - Updated"
   
   helm get values app-dev -n helm-lab

   Vérifiez que logLevel: debug est toujours présent.

5. Tester la précédence fichier vs --set

   helm upgrade app-dev podinfo/podinfo -n helm-lab \
     -f values-base.yaml \
     -f values-dev.yaml \
     --set replicaCount=5
   
   kubectl get pods -n helm-lab

   Attendu : 5 pods (--set surcharge le fichier)

6. Nettoyer

   helm uninstall app-dev -n helm-lab
   kubectl delete namespace helm-lab

Résultat attendu : Vous maîtrisez la gestion des values multi-environnements et l'ordre de précédence.

Bonnes pratiques

Structure de fichiers recommandée

Rangez les surcharges d'environnement dans un sous-dossier values/ à côté du chart, plutôt qu'en vrac à la racine. Cette convention rend explicite quels fichiers sont des variantes de déploiement, et elle simplifie le .gitignore : un seul motif values.override.yaml suffit à exclure les surcharges locales sans risquer d'oublier un fichier d'environnement légitime.

• Répertoirecharts/

  • Répertoiremyapp/

    • Chart.yaml
    • values.yaml Défauts sensés
    • Répertoirevalues/ Surcharges par environnement

      • dev.yaml
      • staging.yaml
      • prod.yaml

Conventions de nommage

Un nom de fichier de values doit dire d'un coup d'oeil ce qu'il surcharge et pourquoi. Deux axes suffisent : par environnement pour ce qui change entre dev, staging et prod, par fonctionnalité pour ce qui active un bloc optionnel (supervision, ingress). La troisième ligne, values.override.yaml, est une convention de fichier local jamais versionné : c'est là que vous mettez un réglage propre à votre poste sans polluer le dépôt.

Convention	Exemple	Usage
values-<env>.yaml	values-prod.yaml	Fichier par environnement
values-<feature>.yaml	values-monitoring.yaml	Fichier par fonctionnalité
values.override.yaml		Surcharges locales (gitignored)

Glissez pour voir

Checklist values production

Passez cette liste avant tout déploiement en production. Les deux premiers points relèvent de la traçabilité (retrouver qui a changé quoi), les trois derniers de la sûreté d'exécution : un secret laissé en clair dans un fichier de values finit dans l'historique Git, et un déploiement sans limits ni requests expose le cluster à un pod qui monopolise un noeud.

• Fichiers versionnés : toutes les values sont dans Git
• Pas de --set en CI/CD : uniquement des fichiers -f
• Valeurs sensibles : externalisées (Secrets, Vault)
• Resources définies : limits et requests explicites
• Replicas adaptés : >= 2 en prod pour la haute disponibilité

Dépannage

La majorité des problèmes de values se ramènent à deux questions : la valeur est-elle bien arrivée jusqu'au template, et a-t-elle le bon type ? La commande helm get values --all répond à la première (elle montre la fusion réelle), et un helm template répond à la seconde (il montre le YAML généré). Le tableau ci-dessous associe chaque symptôme au bon réflexe.

Symptôme	Cause probable	Solution
Value non appliquée	Typo dans le chemin (ui.Color vs ui.color)	Vérifier avec helm show values
Nombre interprété comme string	Mauvais type attendu par le template	Utiliser --set sans quotes ou --set-json
Values perdues après upgrade	Pas de --reuse-values ni -f	Toujours utiliser -f ou --reuse-values
Erreur de parsing YAML	Indentation incorrecte	Valider avec yamllint
Error: values don't meet the spec	Schema validation du chart	Vérifier le schéma dans values.schema.json

Glissez pour voir

Investiguer les values d'une release

Face à une release qui se comporte mal, ces trois commandes se lisent dans l'ordre : get values sans option montre ce que quelqu'un a surchargé, --all montre le résultat fusionné réellement injecté dans les templates, et get manifest montre le YAML final envoyé au cluster. Comparer ces trois vues localise précisément l'endroit où votre intention s'est perdue.

# Values fournies par l'utilisateur
helm get values myrelease -n mynamespace

# Toutes les values (fusionnées)
helm get values myrelease -n mynamespace --all

# Manifests générés
helm get manifest myrelease -n mynamespace

À retenir

• values.yaml = valeurs par défaut du chart. Consultez-le avec helm show values.
• -f fichier.yaml = surcharges via fichier. Versionnez-les dans Git.
• --set = surcharges CLI ponctuelles. Le plus prioritaire, mais moins traçable.
• Ordre de précédence : défaut < fichiers -f (dans l'ordre) < --set.
• --reuse-values conserve les anciennes values lors d'un upgrade. Sans lui, elles sont perdues.
• --set-string force une valeur en string (utile pour les tags d'image numériques).
• helm template génère les manifests sans déployer, idéal pour le debug.

Prochaines étapes

Cycle de vie : upgrade et rollback Mettre à jour une release et revenir en arrière en cas de problème

Anatomie d'un chart Comprendre la structure interne pour mieux personnaliser

Debug et validation Diagnostiquer les problèmes avec lint, template et --debug

×

📖 Voir la documentation →