Qualité des charts Helm : schema, documentation et linting

Un chart Helm mal configuré peut générer des manifestes Kubernetes invalides, des déploiements qui échouent silencieusement, ou des failles de sécurité. Ce guide vous montre comment détecter ces problèmes avant qu'ils n'atteignent la production, en mettant en place une chaîne de validation automatisée.

Concrètement, vous allez apprendre à :

Valider les values fournies par les utilisateurs (types, limites, valeurs autorisées)
Générer automatiquement la documentation de votre chart
Vérifier que les manifestes générés sont conformes aux standards Kubernetes
Détecter les mauvaises pratiques de sécurité (containers root, absence de limits...)

Pré-requis

Avant de commencer, assurez-vous d'avoir :

Un chart Helm existant (ou helm create mon-chart)
Helm v3.8+ installé
Les outils de qualité installés :

# Avec mise (recommandé)
mise use helm-docs kubeconform kube-linter helm-ct
pipx install yamale  # Requis par ct

# Vérification
helm-docs --version   # v1.14.2
kubeconform -v        # v0.7.0
kube-linter version   # 0.8.1
ct version            # v3.14.0

Ce que vous allez apprendre

Section	Concept	Durée
values.schema.json	Validation JSON Schema native	10 min
helm-docs	Génération automatique du README	8 min
helm lint	Validation syntaxique de base	5 min
kubeconform	Validation des manifestes K8s	8 min
kube-linter	Bonnes pratiques sécurité	8 min
ct lint	Validation complète CI/CD	10 min
Conventions	Labels, nommage, versioning	6 min

Valider les values avec values.schema.json

Helm supporte nativement la validation des values via un fichier JSON Schema. Quand ce fichier existe, Helm refuse tout install, upgrade ou template si les values ne respectent pas le schema.

Créer le schema

Le fichier se place à la racine du chart, à côté de values.yaml, et Helm le détecte automatiquement : aucune option de ligne de commande n'est nécessaire. La clé required liste les values sans lesquelles le chart refuse de s'installer, tandis que default documente la valeur retenue en l'absence de saisie sans pour autant la fournir à la place de values.yaml.

{
  "\$schema": "https://json-schema.org/draft-07/schema#",
  "type": "object",
  "required": ["replicaCount", "image"],
  "properties": {
    "replicaCount": {
      "type": "integer",
      "minimum": 1,
      "maximum": 10,
      "description": "Nombre de réplicas (1-10)"
    },
    "image": {
      "type": "object",
      "required": ["repository"],
      "properties": {
        "repository": {
          "type": "string",
          "description": "Image Docker à déployer"
        },
        "tag": {
          "type": "string",
          "default": "latest",
          "description": "Tag de l'image"
        },
        "pullPolicy": {
          "type": "string",
          "enum": ["Always", "IfNotPresent", "Never"],
          "default": "IfNotPresent"
        }
      }
    },
    "service": {
      "type": "object",
      "properties": {
        "type": {
          "type": "string",
          "enum": ["ClusterIP", "NodePort", "LoadBalancer"],
          "default": "ClusterIP"
        },
        "port": {
          "type": "integer",
          "minimum": 1,
          "maximum": 65535,
          "default": 80
        }
      }
    }
  }
}

Tester la validation

helm template suffit à éprouver le schema, sans toucher au cluster. Les messages d'erreur indiquent le chemin JSON exact de la value fautive, ce qui les rend directement exploitables par l'utilisateur du chart.

# Values valides → succès
helm template test mon-chart/

# replicaCount hors limites → erreur
helm template test mon-chart/ --set replicaCount=15

Error: values don't meet the specifications of the schema(s) in the following chart(s):
mon-chart:
- at '/replicaCount': maximum: got 15, want 10

# Valeur enum invalide → erreur
helm template test mon-chart/ --set service.type=Invalid

Error: values don't meet the specifications of the schema(s) in the following chart(s):
mon-chart:
- at '/service/type': value must be one of 'ClusterIP', 'NodePort', 'LoadBalancer'

Types JSON Schema utiles

JSON Schema propose six types de base, largement suffisants pour des values Helm. Attention à la distinction entre integer et number : déclarer integer sur un champ qui recevra une valeur comme 0.5 fera échouer l'installation.

Type	Usage	Exemple
`string`	Texte	`"nginx"`
`integer`	Nombre entier	`3`
`number`	Nombre décimal	`0.5`
`boolean`	Vrai/faux	`true`
`array`	Liste	`["a", "b"]`
`object`	Objet imbriqué	`{"key": "value"}`

Contraintes utiles

Le type seul laisse passer beaucoup d'erreurs : rien n'empêche un integer de valoir 10 000. Ces quatre contraintes restreignent l'espace des valeurs acceptées. La dernière, additionalProperties: false, est la plus stricte puisqu'elle rejette toute clé non déclarée, ce qui attrape les fautes de frappe dans les noms de values, mais casse aussi les extensions non prévues.

{
  "replicaCount": {
    "type": "integer",
    "minimum": 1,           // Valeur minimale
    "maximum": 100          // Valeur maximale
  },
  "environment": {
    "type": "string",
    "enum": ["dev", "staging", "prod"]  // Liste de valeurs autorisées
  },
  "image": {
    "type": "string",
    "pattern": "^[a-z0-9.-]+/[a-z0-9.-]+:[a-z0-9.-]+$"  // Regex
  },
  "resources": {
    "type": "object",
    "additionalProperties": false  // Interdit les clés non déclarées
  }
}

Documenter un chart avec helm-docs

helm-docs génère automatiquement un README.md à partir des commentaires dans values.yaml et du Chart.yaml. L'intérêt n'est pas de gagner du temps de rédaction mais de supprimer la dérive entre le code et sa documentation : ajouter une value sans la documenter devient visible au prochain passage de l'outil. C'est le format attendu par les dépôts de charts publics, et l'un des points vérifiés lors d'une revue.

Ajouter des commentaires helm-docs

Les commentaires commençant par # -- sont extraits pour la documentation :

# -- Nombre de réplicas du deployment
replicaCount: 1

image:
  # -- Repository de l'image Docker
  repository: nginx
  # -- Tag de l'image (défaut: appVersion du Chart)
  tag: ""
  # -- Politique de téléchargement de l'image
  # @default -- IfNotPresent
  pullPolicy: IfNotPresent

service:
  # -- Type de service Kubernetes
  type: ClusterIP
  # -- Port exposé par le service
  port: 80

# -- Configuration des resources (requests/limits)
# @default -- Voir values.yaml
resources: {}

# -- Activation de l'autoscaling HPA
autoscaling:
  # -- Activer/désactiver l'autoscaling
  enabled: false
  # -- Nombre minimum de réplicas
  minReplicas: 1
  # -- Nombre maximum de réplicas
  maxReplicas: 100

Générer le README

Lancé sans argument, helm-docs parcourt le répertoire courant, y cherche les charts et écrase le README.md existant. N'y écrivez donc jamais de contenu à la main : tout ce qui doit y figurer passe par les commentaires de values.yaml ou par un modèle personnalisé.

cd mon-chart/
helm-docs

INFO[2026-02-01T19:27:33+01:00] Found Chart directories [.]
INFO[2026-02-01T19:27:33+01:00] Generating README Documentation for chart .

Résultat généré

Le fichier produit reprend le nom et la description du Chart.yaml, ajoute des badges de version et surtout le tableau des values, dont la colonne Default est lue directement dans values.yaml. C'est ce couplage qui garantit que la documentation ne dérive pas du code.

# mon-chart

![Version: 0.1.0](https://img.shields.io/badge/Version-0.1.0-informational)
![Type: application](https://img.shields.io/badge/Type-application-informational)
![AppVersion: 1.16.0](https://img.shields.io/badge/AppVersion-1.16.0-informational)

A Helm chart for Kubernetes

## Values

| Key | Type | Default | Description |
|-----|------|---------|-------------|
| replicaCount | int | `1` | Nombre de réplicas du deployment |
| image.repository | string | `"nginx"` | Repository de l'image Docker |
| image.tag | string | `""` | Tag de l'image (défaut: appVersion du Chart) |
| image.pullPolicy | string | `"IfNotPresent"` | Politique de téléchargement de l'image |
| service.type | string | `"ClusterIP"` | Type de service Kubernetes |
| service.port | int | `80` | Port exposé par le service |
| resources | object | Voir values.yaml | Configuration des resources (requests/limits) |
| autoscaling.enabled | bool | `false` | Activer/désactiver l'autoscaling |

Template personnalisé

Créez un fichier README.md.gotmpl pour personnaliser le format :

# {{ .Name }}

{{ .Description }}

## Installation

\\`\\`\\`bash
helm install {{ .Name }} ./{{ .Name }}
\\`\\`\\`

## Configuration

{{ template "chart.valuesTable" . }}

## Maintainers

{{ template "chart.maintainersTable" . }}

helm lint : validation de base

helm lint est le contrôle le plus rapide et le seul qui ne demande aucun outil supplémentaire : il vérifie la syntaxe YAML, le rendu des templates Go et la validité du Chart.yaml. Lancez-le en premier, car un chart qui ne passe pas ce stade ne peut pas produire de manifeste à donner aux outils suivants.

helm lint mon-chart/

==> Linting mon-chart/
[INFO] Chart.yaml: icon is recommended

1 chart(s) linted, 0 chart(s) failed

Mode strict

Le flag --strict fait échouer le lint sur les warnings :

helm lint mon-chart/ --strict

Lint avec values spécifiques

Un chart peut passer le lint avec ses values par défaut et échouer avec celles de production, par exemple si un bloc conditionnel n'est activé que là. Rejouez donc le lint avec chaque fichier de values que vous livrez.

helm lint mon-chart/ -f production-values.yaml

kubeconform : validation des manifestes

kubeconform valide que les manifestes générés sont conformes aux schemas Kubernetes. C'est le premier outil de la chaîne qui regarde le résultat du rendu plutôt que le chart : il attrape les champs mal orthographiés, les types incorrects et les apiVersion inexistantes, que helm lint laisse passer sans broncher. Il travaille hors ligne à partir de schémas embarqués, aucun accès au cluster n'est nécessaire.

helm template test mon-chart/ | kubeconform -strict -summary

Summary: 4 resources found parsing stdin - Valid: 4, Invalid: 0, Errors: 0, Skipped: 0

Détecter les erreurs de schema

Si un champ est mal nommé ou a le mauvais type :

# Manifest avec erreur
helm template test mon-chart/ --set service.ports=80 | kubeconform -strict

stdin - Service test-mon-chart is invalid: problem validating schema:
  port in body is required

Valider pour une version K8s spécifique

Sans précision, kubeconform valide contre la version de schémas la plus récente qu'il connaît. Si vos clusters sont plus anciens, imposez la version cible : c'est ainsi que l'on détecte une apiVersion retirée avant la mise à jour, et non pendant.

helm template test mon-chart/ | kubeconform -kubernetes-version 1.29.0 -strict -summary

Options utiles

Deux options changent le comportement plutôt que l'affichage. -strict fait échouer la validation sur toute propriété inconnue, ce qui attrape les fautes de frappe dans les noms de champs ; -skip sert aux ressources personnalisées dont kubeconform n'a pas le schéma, et qu'il rejetterait faute de savoir les lire.

Option	Description
`-strict`	Échoue sur les propriétés inconnues
`-summary`	Affiche un résumé à la fin
`-output json`	Sortie JSON pour la CI
`-kubernetes-version X.Y.Z`	Valide pour une version K8s spécifique
`-skip Kind1,Kind2`	Ignore certains types de ressources

kube-linter : bonnes pratiques sécurité

kube-linter analyse les mêmes manifestes que kubeconform, mais pose une question différente : non plus « est-ce valide ? » mais « est-ce raisonnable ? ». Il signale les conteneurs qui tournent en root, les systèmes de fichiers accessibles en écriture, les images en tag latest et l'absence de requests et limits. Ses messages contiennent systématiquement une remédiation, ce qui en fait un bon support pour un chart repris par une autre équipe.

helm template test mon-chart/ | kube-linter lint -

KubeLinter 0.8.1

<stdin>: (object: <no namespace>/test-mon-chart apps/v1, Kind=Deployment)
  container "mon-chart" does not have a read-only root file system
  (check: no-read-only-root-fs, remediation: Set readOnlyRootFilesystem
   to true in the container securityContext.)

<stdin>: (object: <no namespace>/test-mon-chart apps/v1, Kind=Deployment)
  container "mon-chart" is not set to runAsNonRoot
  (check: run-as-non-root, remediation: Set runAsUser to a non-zero number
   and runAsNonRoot to true in your pod or container securityContext.)

<stdin>: (object: <no namespace>/test-mon-chart apps/v1, Kind=Deployment)
  container "mon-chart" has cpu request 0
  (check: unset-cpu-requirements, remediation: Set CPU requests for your
   container based on its requirements.)

Error: found 9 lint errors

Checks courants

Voici les règles qui remontent le plus souvent sur un chart issu de helm create, car le squelette généré par Helm ne définit ni contexte de sécurité ni ressources. Chacune se corrige dans les templates du chart, pas dans la configuration de kube-linter : désactiver la règle ne supprime que le message.

Check	Description	Remediation
`no-read-only-root-fs`	Filesystem root accessible en écriture	Ajouter `readOnlyRootFilesystem: true`
`run-as-non-root`	Container s'exécute en root	Ajouter `runAsNonRoot: true`
`unset-cpu-requirements`	Pas de requests/limits CPU	Définir `resources.requests.cpu`
`unset-memory-requirements`	Pas de requests/limits memory	Définir `resources.limits.memory`
`latest-tag`	Image utilise le tag `latest`	Utiliser un tag spécifique
`privilege-escalation-container`	`allowPrivilegeEscalation` non défini	Ajouter `allowPrivilegeEscalation: false`

Configuration personnalisée

Créez un fichier .kube-linter.yaml pour ajuster les règles :

checks:
  # Désactiver certaines règles
  exclude:
    - "unset-cpu-requirements"
    - "no-read-only-root-fs"

  # Ou activer uniquement certaines règles
  # include:
  #   - "run-as-non-root"
  #   - "latest-tag"

helm template test mon-chart/ | kube-linter lint --config .kube-linter.yaml -

ct lint : validation complète

chart-testing (ct) est l'outil officiel pour valider les charts avant merge. Il combine helm lint, yamale (validation YAML), et vérifie les conventions.

Configuration

Créez un fichier ct.yaml à la racine du repo :

# Désactive la vérification des maintainers
validate-maintainers: false
# Désactive la vérification d'incrément de version
check-version-increment: false
# Chemin vers les charts
chart-dirs:
  - charts

Téléchargez les schemas officiels :

curl -sSL https://raw.githubusercontent.com/helm/chart-testing/main/etc/chart_schema.yaml -o chart_schema.yaml
curl -sSL https://raw.githubusercontent.com/helm/chart-testing/main/etc/lintconf.yaml -o lintconf.yaml

Lancer ct lint

La commande enchaîne la validation du Chart.yaml contre son schéma, le lint YAML et l'appel à helm lint. Sa sortie est verbeuse par construction : ce qui compte se trouve à la fin, avec la liste des charts traités et le verdict global.

ct lint --config ct.yaml --chart-yaml-schema chart_schema.yaml --lint-conf lintconf.yaml --charts mon-chart/

Linting charts...

------------------------------------------------------------------------------------------------------------------------
 Charts to be processed:
------------------------------------------------------------------------------------------------------------------------
 mon-chart => (version: "0.1.0", path: "mon-chart")
------------------------------------------------------------------------------------------------------------------------

Linting chart "mon-chart => (version: \"0.1.0\", path: \"mon-chart\")"
Validating mon-chart/Chart.yaml...
Validation success! 👍
==> Linting mon-chart
[INFO] Chart.yaml: icon is recommended

1 chart(s) linted, 0 chart(s) failed

------------------------------------------------------------------------------------------------------------------------
 ✔︎ mon-chart => (version: "0.1.0", path: "mon-chart")
------------------------------------------------------------------------------------------------------------------------
All charts linted successfully

ct lint dans un dépôt Git

ct lint peut détecter automatiquement les charts modifiés :

# Lint uniquement les charts modifiés par rapport à main
ct lint --target-branch main --config ct.yaml

Conventions de nommage et labels

Les outils précédents détectent ce qui est invalide ou risqué ; les conventions, elles, relèvent de la cohérence, et aucun linter ne les imposera à votre place. Trois sujets méritent d'être tranchés une fois pour toutes dans une équipe : les labels posés sur chaque ressource, la façon de nommer les objets créés, et la distinction entre la version du chart et celle de l'application.

Labels Kubernetes recommandés

Utilisez les labels standards définis par Kubernetes :

{{- define "mychart.labels" -}}
helm.sh/chart: {{ include "mychart.chart" . }}
app.kubernetes.io/name: {{ include "mychart.name" . }}
app.kubernetes.io/instance: {{ .Release.Name }}
app.kubernetes.io/version: {{ .Chart.AppVersion | quote }}
app.kubernetes.io/managed-by: {{ .Release.Service }}
{{- end }}

{{- define "mychart.selectorLabels" -}}
app.kubernetes.io/name: {{ include "mychart.name" . }}
app.kubernetes.io/instance: {{ .Release.Name }}
{{- end }}

Label	Description	Exemple
`app.kubernetes.io/name`	Nom de l'application	`nginx`
`app.kubernetes.io/instance`	Instance unique	`nginx-prod`
`app.kubernetes.io/version`	Version de l'application	`1.25.0`
`app.kubernetes.io/component`	Composant dans l'application	`frontend`
`app.kubernetes.io/part-of`	Application parente	`wordpress`
`app.kubernetes.io/managed-by`	Outil de gestion	`Helm`
`helm.sh/chart`	Nom et version du chart	`nginx-1.0.0`

Nommage des ressources

Préfixer le nom des objets par celui de la release permet d'installer plusieurs fois le même chart dans un namespace sans collision. Le helper ci-dessous applique le motif {{ .Release.Name }}-{{ .Chart.Name }}, avec deux garde-fous importants : fullnameOverride laisse à l'utilisateur le dernier mot, et le trunc 63 respecte la longueur maximale d'un nom de ressource Kubernetes.

{{- define "mychart.fullname" -}}
{{- if .Values.fullnameOverride }}
{{- .Values.fullnameOverride | trunc 63 | trimSuffix "-" }}
{{- else }}
{{- \$name := default .Chart.Name .Values.nameOverride }}
{{- printf "%s-%s" .Release.Name \$name | trunc 63 | trimSuffix "-" }}
{{- end }}
{{- end }}

Versioning : chart vs appVersion

Chart.yaml porte deux versions que l'on confond régulièrement, alors qu'elles évoluent indépendamment : corriger un template n'a rien à voir avec livrer une nouvelle image applicative. Seule version est utilisée par Helm pour comparer les releases et décider d'une mise à jour ; appVersion est purement informative.

Champ	Ce qu'il représente	Quand l'incrémenter
`version`	Version du chart Helm	Modification des templates, values, schema
`appVersion`	Version de l'application	Mise à jour de l'image Docker

apiVersion: v2
name: mon-app
version: 1.2.0        # Chart modifié → +1 minor ou patch
appVersion: "3.5.1"   # Nouvelle version de l'app → mettre à jour

Labs

L'exercice ci-dessous reprend la chaîne complète sur un chart neuf. Comptez une trentaine de minutes ; les critères de réussite en fin de section vous permettent de vérifier votre travail sans corrigé.

Lab B4, Chaîne qualité complète

Partez d'un chart généré par helm create : il produit volontairement des manifestes non conformes, ce qui donne de la matière à corriger dès la quatrième étape.

Créer un chart avec schema :
Fenêtre de terminal
```
helm create quality-demo
```
Ajouter un values.schema.json avec au moins :
- replicaCount : integer, min 1, max 10
- service.type : enum ClusterIP/NodePort/LoadBalancer
- image.repository : required
Documenter avec helm-docs :
- Ajouter les commentaires # -- dans values.yaml
- Générer le README

Valider avec kubeconform et kube-linter :

helm template test quality-demo/ | kubeconform -strict -summary
helm template test quality-demo/ | kube-linter lint -

Corriger les erreurs kube-linter dans les templates

Critères de réussite :

Schema valide rejette replicaCount=15
README.md généré automatiquement avec tableau des values
kubeconform : 0 invalid
kube-linter : < 3 erreurs (après corrections)

À retenir

Outil	Valide	Quand l'utiliser
`values.schema.json`	Values utilisateur	Toujours (natif Helm)
`helm lint`	Syntaxe chart	Développement
`helm-docs`	Documentation	Avant commit
`kubeconform`	Manifestes K8s	CI/CD
`kube-linter`	Sécurité, bonnes pratiques	CI/CD
`ct lint`	Chart complet	CI/CD, avant merge

Prochaines étapes

Distribution OCI Publier vos charts sur des registries OCI

Provenance et signature Signer vos charts avec Sigstore