ADR-004 : Helm vs manifests Kubernetes bruts dans les templates scaffoldés¶

Statut¶

• Statut : Accepté
• Date : 2026-05-11

Contexte¶

Quand la plateforme CNP scaffold un projet, elle génère un repo Git contenant entre autres les ressources Kubernetes nécessaires au déploiement de l'application. Il faut décider sous quelle forme ces ressources sont générées.

Deux approches sont possibles : - des manifests Kubernetes bruts (fichiers YAML statiques) - un chart Helm (templates paramétrables avec un fichier de valeurs par environnement).

Ce choix impacte directement : - l'expérience développeur (comment le dev configure son déploiement) - la cohérence entre environnements (dev, prod) - l'intégration avec ArgoCD en phase 2 (GitOps) - la lisibilité de la plateforme en soutenance

Rappel : ce qu'est Helm dans ce contexte Helm est un gestionnaire de paquets pour Kubernetes. Un chart Helm est une structure de templates YAML avec des variables, et un fichier values.yaml par environnement. Le rendu final produit des manifests Kubernetes standards.

chart/
  Chart.yaml            # métadonnées (nom, version)
  values.yaml           # valeurs par défaut
  values-dev.yaml       # surcharges environnement dev
  values-prod.yaml      # surcharges environnement prod
  templates/
    deployment.yaml     # {{ .Values.image.tag }}, {{ .Values.replicas }}
    service.yaml
    ingress.yaml

Décision¶

Options évaluées :

Option A : manifests Kubernetes bruts¶

Le scaffold génère des fichiers YAML statiques pour chaque ressource Kubernetes. Les valeurs variables (image tag, replicas, ressources CPU/RAM) sont substituées par des scripts shell ou des outils (envsubst ? sed ?) dans le pipeline CI.

Option B : chart Helm généré par le scaffold¶

Le scaffold génère un chart Helm complet avec un values.yaml par environnement. Le pipeline CI déploie via helm upgrade --install. ArgoCD en phase 2 pointe directement sur le chart.

Option C : Kustomize¶

Alternative à Helm, incluse nativement dans kubectl. Approche par overlays (base + patches par environnement) sans moteur de templates.

CHOIX Option B : chart Helm généré par le scaffold.¶

Le template scaffoldé par CNP génère systématiquement un chart Helm avec ce genre de structure suivante :

chart/
  Chart.yaml
  values.yaml           # image.tag, replicas, resources par défaut
  values-dev.yaml       # surcharges dev (replicas réduits, ressources minimales)
  values-prod.yaml      # surcharges prod (replicas, ressources production)
  templates/
    deployment.yaml
    service.yaml
    ingress.yaml
    _helpers.tpl        # helpers de nommage standard CNP

yamldeploy:
  stage: deploy
  script:
    - helm upgrade --install $APP_NAME ./chart
        -f chart/values-$ENVIRONMENT.yaml
        --set image.tag=$CI_COMMIT_SHA
        --namespace $KUBE_NAMESPACE
        --create-namespace

Conséquences¶

• Le générateur de templates dans FastAPI produit des fichiers Helm valides (syntaxe {{ .Values.* }}). Un test de rendu (helm template)
  est ajouté dans la CI de la plateforme CNP elle-même pour valider les templates générés.
• La plateforme CNP est elle-même déployée via des charts Helm (cohérence de stack).
• Un membre de l'équipe prend ownership de la structure du chart template de référence avant le premier scaffold fonctionnel.
• Le values.yaml généré expose au minimum : image.tag, image.repository, replicas, resources.requests, resources.limits, ingress.host.
  D'autres valeurs peuvent être ajoutées par le dev sans modifier le template.