Dépendances Helm : subcharts, umbrella charts et composition

Réponse directe : helm dependency update télécharge les sous-charts déclarés dans Chart.yaml vers charts/ et génère un Chart.lock pour verrouiller les versions exactes. Le chart parent passe des values aux subcharts via des clés nommées (ex: backend.replicaCount), et global.* est automatiquement propagé à tous les sous-charts.

Ce guide vous montre comment composer des applications complexes en assemblant plusieurs charts Helm — subcharts locaux, dépendances externes, et umbrella charts — tout en maintenant une configuration cohérente et reproductible.

Objectif du module

Maîtriser la composition multi-charts : dépendances externes, subcharts locaux, passage de values, conditions/tags, et bonnes pratiques de maintenance.

Pré-requis

Avant de commencer, assurez-vous d’avoir :

• Un cluster Kubernetes fonctionnel (kind, k3d, minikube ou distant)
• kubectl configuré et un namespace de test
• Helm v3.8+ installé
• Connaissance des modules précédents : templates, values, fonctions

Ce que vous allez apprendre

Section	Concept	Durée
Déclarer des dépendances	Chart.yaml dependencies, repositories	10 min
Télécharger et verrouiller	helm dependency update/build, Chart.lock	8 min
Subcharts et values	Clés nommées, global.*, import-values	12 min
Conditions et tags	Activer/désactiver des sous-charts	8 min
Umbrella chart	Architecture multi-tiers complète	10 min
Pièges et maintenance	Conflits de noms, mises à jour	7 min

Glissez pour voir

---

Déclarer des dépendances

Un chart Helm peut dépendre d’autres charts — locaux ou distants. Ces dépendances sont déclarées dans le fichier Chart.yaml sous la clé dependencies.

Syntaxe de base

Créez un chart umbrella avec des dépendances mixtes :

Chart.yaml

apiVersion: v2
name: mon-stack
description: Chart umbrella pour démo composition
type: application
version: 1.0.0
appVersion: "1.0.0"

dependencies:
  # Dépendance locale (sous-chart dans charts/)
  - name: backend
    version: "0.1.0"
    repository: "file://charts/backend"

  # Dépendance externe (repository Helm)
  - name: kube-state-metrics
    version: "5.27.0"
    repository: "https://prometheus-community.github.io/helm-charts"
    condition: monitoring.enabled   # Activation conditionnelle
    alias: metrics                  # Renommer dans les templates

Types de repositories

Type	Syntaxe repository	Usage
Local	file://charts/nom	Sous-chart développé avec le parent
HTTPS	https://example.com/charts	Repository Helm classique
OCI	oci://ghcr.io/org/charts	Registry OCI (Helm 3.8+)
Alias	@monrepo	Référence un repo ajouté via helm repo add

Glissez pour voir

Ajouter le repository d'abord

Pour les dépendances externes HTTPS, ajoutez d’abord le repository :

helm repo add prometheus-community https://prometheus-community.github.io/helm-charts
helm repo update

Champs de dépendance

Champ	Obligatoire	Description
name	✅	Nom du chart à inclure
version	✅	Version ou range SemVer (^1.2.0, ~1.2.0, >=1.0.0)
repository	✅	URL ou chemin du chart
condition	❌	Chemin values pour activer/désactiver (ex: db.enabled)
tags	❌	Liste de tags pour activation groupée
alias	❌	Renommer le chart (utile si même chart plusieurs fois)
import-values	❌	Importer des values du sous-chart vers le parent

Glissez pour voir

---

Télécharger et verrouiller les versions

Helm propose deux commandes pour gérer les dépendances : update et build.

helm dependency update

Cette commande résout les dépendances depuis Chart.yaml, télécharge les charts dans charts/, et génère un fichier Chart.lock :

helm dependency update mon-stack/

Sortie typique :

Hang tight while we grab the latest from your chart repositories...
...Successfully got an update from the "prometheus-community" chart repository
Update Complete. ⎈Happy Helming!⎈
Saving 2 charts
Downloading kube-state-metrics from repo https://prometheus-community.github.io/helm-charts
Deleting outdated charts

Ce qui se passe :

1. Helm met à jour les indexes des repositories
2. Résout les versions selon les contraintes (5.27.0, ^1.0.0, etc.)
3. Télécharge les .tgz dans charts/
4. Génère Chart.lock avec les versions exactes

Contenu de charts/ après update

ls -la mon-stack/charts/

total 32
drwxrwxr-x 3 bob bob  4096 févr.  1 19:09 .
drwxrwxr-x 4 bob bob  4096 févr.  1 19:09 ..
drwxrwxr-x 3 bob bob  4096 févr.  1 19:08 backend
-rw-rw-r-- 1 bob bob   751 févr.  1 19:09 backend-0.1.0.tgz
-rw-r--r-- 1 bob bob 14235 févr.  1 19:09 kube-state-metrics-5.27.0.tgz

Les sous-charts locaux (file://) restent en dossiers ET sont packagés en .tgz. Les dépendances externes arrivent uniquement en .tgz.

Chart.lock : le verrou de reproductibilité

Chart.lock (généré automatiquement)

dependencies:
- name: backend
  repository: file://charts/backend
  version: 0.1.0
- name: kube-state-metrics
  repository: https://prometheus-community.github.io/helm-charts
  version: 5.27.0
digest: sha256:c7be1e4c41ba5a5a166b995fbf57fd64ef0364100fb37c12a84553e64f4443c3
generated: "2026-02-01T19:09:58.573104083+01:00"

Ce fichier est essentiel : il garantit que toute l’équipe et la CI utilisent les mêmes versions exactes.

helm dependency build

Contrairement à update, la commande build utilise Chart.lock au lieu de Chart.yaml pour télécharger les dépendances :

# Supprimer les archives téléchargées
rm mon-stack/charts/*.tgz

# Reconstruire depuis le lock
helm dependency build mon-stack/

Sortie :

Saving 2 charts
Downloading kube-state-metrics from repo https://prometheus-community.github.io/helm-charts
Deleting outdated charts

update vs build : quand utiliser quoi ?

Commande	Utilise	Quand l’utiliser
helm dependency update	Chart.yaml	Développement, mise à jour vers nouvelles versions
helm dependency build	Chart.lock	CI/CD, builds reproductibles

Glissez pour voir

Workflow recommandé

1. Développeur : helm dependency update pour mettre à jour les dépendances
2. Commit : Chart.yaml + Chart.lock (sans le dossier charts/)
3. CI/CD : helm dependency build pour reconstruire identiquement

Lister les dépendances

helm dependency list mon-stack/

NAME                    VERSION REPOSITORY                                              STATUS
backend                 0.1.0   file://charts/backend                                   ok
kube-state-metrics      5.27.0  https://prometheus-community.github.io/helm-charts      ok

Les statuts possibles :

• ok : Dépendance présente et à jour
• missing : Non téléchargée (lancer update ou build)
• unpacked : Dossier présent mais pas de .tgz

---

Subcharts : passer des values

La communication entre chart parent et subcharts se fait exclusivement via les values. Helm offre trois mécanismes.

Mécanisme 1 : Clés nommées

Chaque sous-chart reçoit ses values sous une clé correspondant à son nom (ou alias) :

values.yaml du parent

# Configuration du sous-chart "backend"
backend:
  replicaCount: 2
  image:
    tag: "6.7.1"

# Configuration du sous-chart avec alias "metrics" (kube-state-metrics)
metrics:
  prometheusScrape: true
  replicas: 1

Dans le sous-chart backend, ces values sont accessibles directement :

charts/backend/templates/deployment.yaml

spec:
  replicas: {{ .Values.replicaCount }}  # Reçoit 2
  containers:
    - image: "{{ .Values.image.repository }}:{{ .Values.image.tag }}"  # tag = 6.7.1

Résolution des values

Le sous-chart voit ses propres values fusionnées : ses values.yaml par défaut + les overrides du parent. Il n’a jamais accès aux values des autres sous-charts.

Mécanisme 2 : Global values

Les values sous global.* sont automatiquement propagées à tous les sous-charts :

values.yaml du parent

global:
  imageRegistry: "my-registry.io"
  additionalLabels:
    team: platform
    cost-center: infra

Dans n’importe quel sous-chart :

Template d'un sous-chart

metadata:
  labels:
    {{- with .Values.global.additionalLabels }}
    {{- toYaml . | nindent 4 }}
    {{- end }}
spec:
  containers:
    - image: "{{ .Values.global.imageRegistry }}/{{ .Values.image.repository }}:{{ .Values.image.tag }}"

Résultat du template :

metadata:
  labels:
    team: platform
    cost-center: infra
spec:
  containers:
    - image: "my-registry.io/ghcr.io/stefanprodan/podinfo:6.7.1"

Mécanisme 3 : import-values

Pour des cas avancés, vous pouvez importer des values d’un sous-chart vers le parent :

Chart.yaml

dependencies:
  - name: database
    version: "0.1.0"
    repository: "file://charts/database"
    import-values:
      - child: exports.connection    # Chemin dans le sous-chart
        parent: dbConnection         # Clé dans le parent

charts/database/values.yaml

exports:
  connection:
    host: postgres.default.svc
    port: 5432
    database: appdb

Dans un template du parent, vous accédez maintenant à :

data:
  DB_HOST: {{ .Values.dbConnection.host | quote }}   # "postgres.default.svc"
  DB_PORT: {{ .Values.dbConnection.port | quote }}   # "5432"

Usage limité

import-values est rarement utilisé. Préférez les clés nommées ou global.* qui sont plus explicites et plus faciles à debugger.

---

Conditions et tags

Vous pouvez activer ou désactiver des sous-charts dynamiquement sans les supprimer de Chart.yaml.

Conditions

Une condition est un chemin values qui doit valoir true ou false :

Chart.yaml

dependencies:
  - name: kube-state-metrics
    version: "5.27.0"
    repository: "https://prometheus-community.github.io/helm-charts"
    condition: monitoring.enabled
    alias: metrics

values.yaml

monitoring:
  enabled: true   # Le sous-chart est inclus

Tester la condition :

# Avec monitoring activé
helm template mon-stack . --set monitoring.enabled=true 2>&1 | grep -E "^# Source:" | sort -u

mon-stack/charts/backend/templates/deployment.yaml

# Source: mon-stack/charts/backend/templates/service.yaml
# Source: mon-stack/charts/metrics/templates/clusterrolebinding.yaml
# Source: mon-stack/charts/metrics/templates/deployment.yaml
# Source: mon-stack/charts/metrics/templates/role.yaml
# Source: mon-stack/charts/metrics/templates/serviceaccount.yaml
# Source: mon-stack/charts/metrics/templates/service.yaml

# Avec monitoring désactivé
helm template mon-stack . --set monitoring.enabled=false 2>&1 | grep -E "^# Source:" | sort -u

mon-stack/charts/backend/templates/deployment.yaml

# Source: mon-stack/charts/backend/templates/service.yaml

Le sous-chart metrics n’est plus rendu quand monitoring.enabled=false.

Tags

Les tags permettent de grouper plusieurs sous-charts et de les activer/désactiver ensemble :

Chart.yaml

dependencies:
  - name: backend
    version: "0.1.0"
    repository: "file://charts/backend"
    tags:
      - backend
      - api

  - name: frontend
    version: "0.1.0"
    repository: "file://charts/frontend"
    tags:
      - frontend
      - api

  - name: kube-state-metrics
    repository: "https://prometheus-community.github.io/helm-charts"
    tags:
      - monitoring
      - observability

values.yaml

tags:
  api: true          # Active backend ET frontend
  monitoring: false  # Désactive kube-state-metrics

Priorité : condition vs tag

Quand un sous-chart a à la fois une condition et des tags, la condition a priorité :

condition	tag	Résultat
true	true	✅ Inclus
true	false	✅ Inclus (condition prioritaire)
false	true	❌ Exclu (condition prioritaire)
false	false	❌ Exclu
non définie	true	✅ Inclus
non définie	false	❌ Exclu

Glissez pour voir

---

Umbrella chart : composer une stack

Un umbrella chart est un chart qui ne contient (presque) pas de templates propres — il orchestre uniquement des sous-charts pour déployer une stack complète.

Architecture typique

• Répertoiremon-stack/

  • Chart.yaml Dépendances déclarées ici
  • Chart.lock Versions verrouillées
  • values.yaml Configuration globale + overrides subcharts
  • Répertoiretemplates/

    • configmap.yaml Optionnel : config partagée
  • Répertoirecharts/

    • Répertoirebackend/ Sous-chart local

      • …
    • Répertoiredatabase/ Sous-chart local

      • …
    • kube-state-metrics-5.27.0.tgz Dépendance externe

Exemple complet

Voici un umbrella chart pour une application web avec monitoring :

Chart.yaml

apiVersion: v2
name: mon-stack
description: Stack web complète avec backend, database et monitoring
type: application
version: 1.0.0
appVersion: "1.0.0"

dependencies:
  - name: backend
    version: "0.1.0"
    repository: "file://charts/backend"
    tags:
      - backend

  - name: database
    version: "0.1.0"
    repository: "file://charts/database"
    import-values:
      - child: exports.connection
        parent: dbConnection

  - name: kube-state-metrics
    version: "5.27.0"
    repository: "https://prometheus-community.github.io/helm-charts"
    condition: monitoring.enabled
    alias: metrics

values.yaml

# Activation par tags
tags:
  backend: true

# Configuration globale (propagée à tous les subcharts)
global:
  imageRegistry: ""
  additionalLabels:
    app.kubernetes.io/part-of: mon-stack

# Override du sous-chart backend
backend:
  replicaCount: 2
  image:
    tag: "6.7.1"
  resources:
    requests:
      cpu: 100m
      memory: 128Mi
    limits:
      cpu: 500m
      memory: 512Mi

# Override du sous-chart database
database:
  persistence:
    size: 20Gi

# Activation du monitoring
monitoring:
  enabled: true

# Override du sous-chart metrics (alias de kube-state-metrics)
metrics:
  prometheusScrape: true

Rendu

helm template mon-stack . 2>&1 | grep -E "^# Source:" | sort -u

mon-stack/charts/backend/templates/deployment.yaml

# Source: mon-stack/charts/backend/templates/service.yaml
# Source: mon-stack/charts/metrics/templates/clusterrolebinding.yaml
# Source: mon-stack/charts/metrics/templates/deployment.yaml
# Source: mon-stack/charts/metrics/templates/role.yaml
# Source: mon-stack/charts/metrics/templates/service.yaml
# Source: mon-stack/charts/metrics/templates/serviceaccount.yaml
# Source: mon-stack/templates/configmap.yaml

Afficher les métadonnées

helm show chart mon-stack/

apiVersion: v2
appVersion: 1.0.0
dependencies:
- name: backend
  repository: file://charts/backend
  tags:
  - backend
  version: 0.1.0
- import-values:
  - child: exports.connection
    parent: dbConnection
  name: database
  repository: file://charts/database
  version: 0.1.0
- alias: metrics
  condition: monitoring.enabled
  name: kube-state-metrics
  repository: https://prometheus-community.github.io/helm-charts
  version: 5.27.0
description: Stack web complète avec backend, database et monitoring
name: mon-stack
type: application
version: 1.0.0

Packager l’umbrella

Quand vous packagez un umbrella chart, toutes les dépendances sont incluses dans l’archive :

helm package mon-stack/ -d ./dist/

Successfully packaged chart and saved it to: ./dist/mon-stack-1.0.0.tgz

tar tzf ./dist/mon-stack-1.0.0.tgz | head -20

mon-stack/Chart.yaml
mon-stack/Chart.lock
mon-stack/values.yaml
mon-stack/templates/configmap.yaml
mon-stack/charts/backend/Chart.yaml
mon-stack/charts/backend/values.yaml
mon-stack/charts/backend/templates/deployment.yaml
mon-stack/charts/backend/templates/service.yaml
mon-stack/charts/kube-state-metrics/Chart.yaml
mon-stack/charts/kube-state-metrics/values.yaml
mon-stack/charts/kube-state-metrics/templates/...

---

Pièges de composition et maintenance

Piège 1 : Conflits de noms

Deux sous-charts peuvent générer des ressources avec le même nom, causant des conflits :

# backend génère : mon-stack-backend-config
# frontend génère aussi : mon-stack-frontend-config
# ✅ OK, noms différents

# Si les deux utilisent {{ .Release.Name }}-config :
# ❌ Conflit : mon-stack-config existe deux fois

Solution : Utilisez le pattern {{ include "chart.fullname" . }} qui inclut le nom du chart :

{{- define "backend.fullname" -}}
{{- printf "%s-%s" .Release.Name .Chart.Name | trunc 63 | trimSuffix "-" }}
{{- end }}

Piège 2 : Mises à jour des dépendances

Après modification de Chart.yaml, vous devez re-run helm dependency update :

# ❌ Erreur si vous oubliez
helm template mon-stack .
# Error: found in Chart.yaml, but missing in charts/ directory: new-dependency

# ✅ Correct
helm dependency update mon-stack/
helm template mon-stack .

Piège 3 : Version ranges trop permissives

dependencies:
  # ❌ Dangereux : peut sauter une major
  - name: postgres
    version: "*"

  # ⚠️ Peut inclure des breaking changes mineurs
  - name: postgres
    version: ">=15.0.0"

  # ✅ Recommandé : patch updates seulement
  - name: postgres
    version: "~15.5.0"   # 15.5.x uniquement

  # ✅ Recommandé : minor updates
  - name: postgres
    version: "^15.0.0"   # 15.x.x uniquement

Piège 4 : Charts.lock non commité

Si Chart.lock n’est pas dans le repo Git, chaque développeur peut avoir des versions différentes :

# Fichiers à commiter
git add Chart.yaml Chart.lock values.yaml templates/

# Fichiers à ignorer (reconstruits via helm dependency build)
echo "charts/*.tgz" >> .gitignore

Piège 5 : Oublier les conditions

Sans condition, un sous-chart est toujours déployé même si non utilisé :

# ❌ Pas de condition : monitoring toujours déployé
- name: prometheus
  version: "25.0.0"
  repository: "https://prometheus-community.github.io/helm-charts"

# ✅ Avec condition : contrôle explicite
- name: prometheus
  version: "25.0.0"
  repository: "https://prometheus-community.github.io/helm-charts"
  condition: prometheus.enabled

---

Labs

Lab B3 — Créer un umbrella chart fonctionnel

1. Créer la structure :

   mkdir -p mon-umbrella/charts/api/templates

2. Déclarer le sous-chart API (charts/api/Chart.yaml) :

   apiVersion: v2
   name: api
   version: 0.1.0

3. Ajouter une dépendance externe (Chart.yaml du parent) :

   dependencies:
     - name: api
       version: "0.1.0"
       repository: "file://charts/api"
     - name: kube-state-metrics
       version: "5.27.0"
       repository: "https://prometheus-community.github.io/helm-charts"
       condition: monitoring.enabled
       alias: metrics

4. Configurer les values avec global.* et overrides :

   global:
     environment: staging
   api:
     replicaCount: 3
   monitoring:
     enabled: true

5. Télécharger et valider :

   helm dependency update mon-umbrella/
   helm template test mon-umbrella/ | kubectl apply --dry-run=client -f -

Critères de réussite :

• helm dependency list affiche toutes les dépendances en status ok
• Chart.lock est généré avec les versions exactes
• Les values global.* sont accessibles dans les sous-charts
• --set monitoring.enabled=false exclut kube-state-metrics du rendu
• Le chart se package avec toutes les dépendances incluses

---

À retenir

Concept	Commande / Syntaxe	Usage
Déclarer	dependencies: dans Chart.yaml	Lister les sous-charts
Télécharger	helm dependency update	Développement, nouvelles versions
Reconstruire	helm dependency build	CI/CD, reproductibilité
Lister	helm dependency list	Vérifier les statuts
Values nommées	backend.replicaCount: 2	Configurer un sous-chart
Global values	global.imageRegistry	Propager à tous les sous-charts
Condition	condition: db.enabled	Activer/désactiver un sous-chart
Alias	alias: metrics	Renommer un sous-chart

Glissez pour voir

Règle d'or

Commitez toujours Chart.yaml ET Chart.lock. Utilisez helm dependency build en CI pour garantir la reproductibilité.

---

Prochaines étapes

Qualité des charts Valider vos charts avec values.schema.json, documentation et conventions

Distribution OCI Publier vos charts sur des registries OCI

×

📖 Voir la documentation →