Flux CD — Déploiements Helm avec HelmRelease

Flux CD gère les releases Helm de façon déclarative via le HelmRelease CRD. Plutôt que d’exécuter helm upgrade --install dans un pipeline CI, vous déclarez l’état voulu dans Git et le helm-controller de Flux s’occupe des installs, upgrades et rollbacks. Ce guide explique comment configurer un HelmRepository, un HelmRelease et définir une stratégie de remediation robuste.

Guide précédent recommandé

Ce guide suppose que vous avez déjà déployé une première application avec Kustomize et que vous connaissez les concepts de base Flux. Consultez Première application si besoin.

Ce que vous allez apprendre

• Déclarer un HelmRepository pour référencer un dépôt de charts Helm
• Créer un HelmRelease avec les values de votre choix
• Surcharger les values par environnement sans dupliquer les fichiers
• Configurer une stratégie de remediation (retry, rollback, uninstall)
• Pointer vers un chart stocké dans votre Git ou dans un registre OCI
• Diagnostiquer une release Helm en échec

Prérequis

• Flux bootstrappé et fonctionnel (flux check tout en vert)
• Connaissance des concepts de base Helm (chart, values, release)

Architecture : Sources Helm dans Flux

Flux utilise deux objets pour gérer les charts Helm :

HelmRepository → HelmChart → HelmRelease

1. HelmRepository : déclare un dépôt de charts (un index.yaml). Le source-controller le télécharge périodiquement.
2. HelmChart : résout un chart spécifique depuis un HelmRepository. Il est souvent créé automatiquement par le helm-controller à partir d’un HelmRelease — vous n’avez généralement pas besoin de le créer manuellement.
3. HelmRelease : déclare l’état voulu d’une release Helm (chart + version + values). C’est l’objet que vous créez et gérez.

Déclarer un HelmRepository

Voici comment déclarer le dépôt de charts Bitnami :

infrastructure/sources/bitnami.yaml

apiVersion: source.toolkit.fluxcd.io/v1
kind: HelmRepository
metadata:
  name: bitnami
  namespace: flux-system
spec:
  interval: 1h
  url: https://charts.bitnami.com/bitnami

Bonnes pratiques :

• Placez les HelmRepository dans infrastructure/sources/ pour les partager entre toutes les applications.
• Utilisez un intervalle long (1h) car les index Helm ne changent pas fréquemment.

Vérifiez que le dépôt est accessible :

flux get source helm
# NAME     REVISION          SUSPENDED  READY   MESSAGE
# bitnami  sha256:a1b2c3...   False      True    stored artifact: revision 'sha256:a1b2c3'

Créer un HelmRelease

Exemple minimal — nginx

apps/base/nginx/helmrelease.yaml

apiVersion: helm.toolkit.fluxcd.io/v2
kind: HelmRelease
metadata:
  name: nginx
  namespace: web
spec:
  interval: 5m
  chart:
    spec:
      chart: nginx
      version: ">=18.0.0 <19.0.0"
      sourceRef:
        kind: HelmRepository
        name: bitnami
        namespace: flux-system
  values:
    replicaCount: 2
    service:
      type: ClusterIP

Points clés :

• chart.spec.version accepte des contraintes SemVer : ">=18.0.0 <19.0.0", "18.x.x", "18.1.0" (version exacte recommandée en production).
• chart.spec.sourceRef pointe vers le HelmRepository déclaré plus tôt.
• values surcharge directement les valeurs du chart.

Exemple avec valeurs par environnement

Pour gérer des values différentes par environnement sans dupliquer le fichier, utilisez valuesFrom avec des ConfigMap ou des Secret :

apps/production/nginx/helmrelease.yaml

apiVersion: helm.toolkit.fluxcd.io/v2
kind: HelmRelease
metadata:
  name: nginx
  namespace: web
spec:
  interval: 5m
  chart:
    spec:
      chart: nginx
      version: "18.2.4"
      sourceRef:
        kind: HelmRepository
        name: bitnami
        namespace: flux-system
  values:
    replicaCount: 3
  valuesFrom:
    - kind: ConfigMap
      name: nginx-prod-values
      valuesKey: values.yaml
    - kind: Secret
      name: nginx-prod-secrets
      valuesKey: secrets.yaml
      optional: true

Le champ valuesFrom permet de séparer les values publiques (ConfigMap) des values sensibles (Secret), et de les versionner séparément.

Ordre de priorité des values

Les values sont fusionnées dans l’ordre suivant (priorité croissante) :

1. Values du chart (par défaut)
2. valuesFrom (dans l’ordre déclaré)
3. values inline dans le HelmRelease

Un champ déclaré dans values inline écrase tout.

Stratégies de remediation

Par défaut, si une release Helm échoue, Flux ne fait rien. C’est un comportement correct pour éviter des boucles d’upgrades, mais en production vous voulez définir une stratégie explicite.

Remédiation à l’installation

spec:
  install:
    remediation:
      retries: 3

Si l’installation échoue, Flux réessaie 3 fois avant de s’arrêter avec READY: False.

Remédiation à l’upgrade

spec:
  upgrade:
    remediation:
      retries: 3
      strategy: rollback  # ou "uninstall"
      remediateLastFailure: true

• strategy: rollback — revient à la version précédente si l’upgrade échoue.
• strategy: uninstall — désinstalle la release en cas d’échec.
• remediateLastFailure: true — applique la stratégie même si c’est le dernier retry qui a échoué (sans cette option, le dernier échec reste dans l’état failed).

Configuration recommandée en production

spec:
  interval: 5m
  install:
    remediation:
      retries: 3
  upgrade:
    remediation:
      retries: 3
      strategy: rollback
      remediateLastFailure: true
  rollback:
    timeout: 5m
    cleanupOnFail: false

Charts depuis un dépôt Git

Flux peut aussi déployer un chart Helm stocké directement dans votre dépôt Git (utile pour les charts maison) :

apiVersion: helm.toolkit.fluxcd.io/v2
kind: HelmRelease
metadata:
  name: my-chart
  namespace: my-app
spec:
  interval: 5m
  chart:
    spec:
      chart: ./charts/my-chart    # Chemin relatif dans la source Git
      sourceRef:
        kind: GitRepository
        name: fleet-infra
        namespace: flux-system
  values:
    replicaCount: 1

Charts depuis un registre OCI

Les charts Helm peuvent aussi être stockés dans un registre OCI (GitHub Container Registry, Docker Hub, Harbor…) :

infrastructure/sources/my-registry.yaml

apiVersion: source.toolkit.fluxcd.io/v1beta2
kind: OCIRepository
metadata:
  name: my-charts
  namespace: flux-system
spec:
  interval: 5m
  url: oci://ghcr.io/my-org/charts
  ref:
    tag: latest

apiVersion: helm.toolkit.fluxcd.io/v2
kind: HelmRelease
metadata:
  name: my-app
  namespace: my-app
spec:
  interval: 5m
  chartRef:
    kind: OCIRepository
    name: my-charts
    namespace: flux-system
  values:
    replicaCount: 2

Diagnostiquer une HelmRelease en échec

1. Inspecter l’état de la HelmRelease

flux get helmreleases -A
# NAMESPACE  NAME   REVISION  SUSPENDED  READY  MESSAGE
# web        nginx  18.2.4    False      False  Helm upgrade failed: ...

2. Voir le détail de l’erreur

kubectl describe helmrelease nginx -n web
# Cherchez la section "Events:" en bas de la sortie

3. Inspecter les logs du helm-controller

kubectl logs -n flux-system deploy/helm-controller | grep "nginx" | tail -20

4. Vérifier que la Source est prête

flux get source helm
# Si READY: False, le dépôt Helm est inaccessible

5. Forcer une nouvelle tentative

# Annuler l'état d'échec et relancer
flux reconcile helmrelease nginx -n web --reset

Commandes Helm utiles avec Flux

Commande	Description
flux get helmreleases -A	Lister toutes les releases Helm
flux reconcile helmrelease <nom> -n <ns>	Forcer une réconciliation
flux reconcile helmrelease <nom> -n <ns> --reset	Réinitialiser l’état d’échec et relancer
flux suspend helmrelease <nom> -n <ns>	Suspendre une release
flux resume helmrelease <nom> -n <ns>	Reprendre une release suspendue
helm history <nom> -n <ns>	Voir l’historique des upgrades Helm
helm rollback <nom> -n <ns>	Rollback manuel (contourne Flux)

Glissez pour voir

Évitez les rollbacks manuels avec helm

Un helm rollback manuel met la release dans un état que Flux ne contrôle plus jusqu’à la prochaine réconciliation. Préférez modifier les values dans Git et laisser Flux gérer l’upgrade, ou utilisez flux reconcile --reset pour laisser Flux réessayer sa stratégie de remediation.

À retenir

• HelmRepository déclare un dépôt de charts — à placer dans infrastructure/sources/.
• HelmRelease déclare l’état voulu d’une release Helm (chart + version + values).
• valuesFrom permet de séparer les values sensibles (Secret) des publiques (ConfigMap).
• Toujours définir une upgrade.remediation avec strategy: rollback en production.
• flux reconcile helmrelease --reset relance une release bloquée en état d’échec.
• Ne pas faire de helm rollback manuel — laissez Flux gérer la remediation.

Prochaines étapes

Automatisation d'images Flux met à jour automatiquement les tags d'images dans votre config-repo

Multi-tenancy Isoler les équipes avec des namespaces et du RBAC Flux

Monitoring et alertes Métriques Prometheus, dashboards Grafana et alertes Slack

×

📖 Voir la documentation →