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, comprendre l'ordre de précédence des surcharges, et éviter les pièges de --set. En 20 minutes, vous saurez configurer n'importe quel chart de façon 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, kind pour cette formation
• Avoir compris helm install (voir module H1-03)

Comprendre le système de values

Les values sont le seul moyen d'adapter un chart sans le modifier, et c'est ce qui rend un chart réutilisable d'une équipe à l'autre. Le mécanisme tient en trois temps : des défauts portés par le chart, vos surcharges, et une fusion dont l'ordre décide de qui gagne. Ce chapitre traite les trois.

Comment fonctionne la personnalisation ?

Chaque chart Helm contient un values.yaml porteur de valeurs par défaut. À l'installation, Helm fusionne vos surcharges avec ces défauts, puis injecte le résultat dans les templates pour générer les manifestes 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é absente du 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 de votre poste : vous pouvez donc les relire depuis une autre machine, à condition d'avoir accès au namespace. Par défaut, helm get values ne montre que 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. Une valeur qui contient l'un des deux doit être échappée par un antislash, sans quoi Helm la découpe. Les index entre crochets 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, listes vides et objets imbriqués compris, 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.

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 rend helm get values au contenu de votre 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, le plus souvent parce que le chemin passé à -f était erroné et que Helm a déployé les seuls défauts, sans rien 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

Le même chart doit servir la préproduction et la production, sans être dupliqué. C'est là que se joue la maintenabilité d'un déploiement : dès qu'on copie un chart pour changer deux valeurs, les deux copies divergent et plus personne ne sait laquelle fait foi. Les stratégies qui suivent gardent un seul chart et font varier les fichiers de values.

Stratégie de fichiers par environnement

La stratégie la plus courante isole le commun du variable. Un fichier values-base.yaml porte les réglages identiques partout, image, ports et 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 préproduction manque en production, faute d'avoir édité les deux fichiers ensemble.

• 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 : le fichier de base en premier, l'environnement ensuite, garantit que l'environnement gagne.

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

Un upgrade ne repart pas de ce que vous aviez fourni la fois précédente, et c'est la cause d'incident la plus fréquente sur les values. Deux drapeaux permettent de choisir explicitement ce qui sert de point de départ ; les comprendre évite de perdre une configuration entière sur une simple mise à jour d'image.

--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 vos --set que 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

Le piège de la surcharge partielle

Sans --reuse-values ni -f, un helm upgrade qui ne passe qu'un --set perd toutes les anciennes values. C'est l'une des causes les plus fréquentes de régression en production, et la plus difficile à relier à sa cause.

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

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

Le plus traître n'est pas la perte, c'est qu'elle ne produit aucune erreur. Une release lancée avec replicaCount: 2, puis mise à jour par un simple --set ui.color=blue, voit ses USER-SUPPLIED VALUES réduites à cette seule couleur : replicaCount retombe à la valeur par défaut du chart, et le Deployment passe de deux répliques à une. Personne n'est prévenu, la commande rend deployed, et la capacité a été divisée par deux.

Le réflexe qui protège tient en une commande, jouée avant et après chaque upgrade :

helm get values demo

Comparer les deux sorties prend cinq secondes et rend visible exactement ce que l'upgrade a emporté.

Visualiser sans déployer : helm template

helm template effectue le rendu complet des templates avec vos values et affiche les manifestes obtenus, 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. Notez qu'il ne joue aucune vérification côté serveur, schémas d'admission et ressources existantes compris : il ne remplace pas un --dry-run=server.

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, vérifier le nombre de pods, puis démontrer les deux règles de précédence vues plus haut, la conservation par --reuse-values et la priorité de --set sur un fichier. Exécutez-le sur un cluster jetable, les manifestes ne créant 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

Ces conventions n'ont rien d'obligatoire, et c'est bien le problème : rien ne les impose, mais leur absence se paie six mois plus tard, quand personne ne sait plus quel fichier de values est appliqué en production. Les trois qui suivent sont celles dont l'absence coûte le plus cher.

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 exclut 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'œil ce qu'il surcharge et pourquoi. Deux axes suffisent : par environnement pour ce qui change entre dev, préproduction et production, par fonctionnalité pour ce qui active un bloc optionnel. La convention values.override.yaml désigne un fichier local jamais versionné : c'est là que va un réglage propre à votre poste.

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 nœud.

• 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 ? helm get values --all répond à la première en montrant la fusion réelle, helm template répond à la seconde en montrant le YAML généré. Le tableau 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é, et get manifest montre le YAML final envoyé au cluster. Les comparer 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.

Contrôle de connaissances

Six questions sur le piège le plus coûteux de Helm, la perte silencieuse de values lors d'un upgrade, plus l'ordre de précédence et le typage de --set.

Contrôle de connaissances

Validez vos connaissances avec ce quiz interactif

5 questions

5 min.

80% requis

Informations

• Le chronomètre démarre au clic sur Démarrer
• Questions à choix multiples, vrai/faux et réponses courtes
• Vous pouvez naviguer entre les questions
• Les résultats détaillés sont affichés à la fin

Démarrer le quiz

Lance le quiz et démarre le chronomètre

Pour aller plus loin

• Patterns de templates pour la production : Les tournures de template qui rendent des values réellement exploitables.
• Upgrade, rollback et cycle de vie : Ce que devient une value modifiée lors d'un upgrade.
• Qualité, schéma et documentation : Valider les values par un schéma JSON plutôt que par la relecture.

×

📖 Voir la documentation →