Helm vs Kustomize : values, overlays et rollback

Helm remplit un chart à partir de values.yaml. Kustomize patche le YAML que vous pouvez déjà lire. Les deux émettent des manifests, et les deux peuvent définir le même nombre de replicas et tag d’image. Cette page montre que changer fonctionne des deux côtés, puis quand un chart, un overlay ou les deux est le propriétaire approprié.

Réponse courte

Choisissez Helm quand l’unité de livraison est une version : une tarball ou un artifact OCI, un historique de révision, et une commande qui installe ou annule chaque objet. Choisissez Kustomize quand l’unité est un répertoire et chaque environnement est un patch sur une base. kubectl 1.30 inclut déjà Kustomize, donc kubectl apply -k, kubectl diff -k et kubectl kustomize n’ont besoin d’aucune installation extra.

Les templates Helm sont des templates Go. Ils peuvent sauter un document avec if ou échouer le render quand une value manque. Kustomize n’a pas de langage de template. Un objet optionnel est un fichier listé seulement dans l’overlay qui en a besoin.

Côte à côte

kubectl diff -k sort 1 quand les objets en direct diffèrent du build. C’est un diff, pas un binaire cassé. Tenez-en compte en CI avant de traiter le code de sortie comme un échec.

Le même changement, les deux façons

L’objectif est trois replicas d’API et le tag 1.4.2.

Values Helm :

replicaCount: 3
image:
  repository: example/api
  tag: "1.4.2"

Le template remplace seulement ce qui varie. required arrête un render qui imprimerait autrement un nombre de replicas vide :

spec:
  replicas: {{ required "replicaCount is required" .Values.replicaCount }}
  template:
    spec:
      containers:
        - name: api
          image: "{{ .Values.image.repository }}:{{ .Values.image.tag }}"

helm lint ./chart
helm upgrade --install api ./chart -n demo --create-namespace -f values/prod.yaml --wait --timeout 3m
helm history api -n demo

--wait bloque jusqu’à ce que le Déploiement soit disponible ou --timeout soit atteint. --atomic annule une mise à jour échouée et désinstalle un premier install échoué.

La base Kustomize répertorie les manifests ordinaires. L’overlay production ne les copie pas :

apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
resources:
  - ../../base
namespace: prod
replicas:
  - name: api
    count: 3
images:
  - name: example/api
    newTag: "1.4.2"
patches:
  - path: memory.yaml
    target:
      kind: Deployment
      name: api

newTag édite le YAML. Il ne construit pas une image. images.name est le dépôt sans le tag. Dans le patch ci-dessous, le name du conteneur est la clé de fusion :

apiVersion: apps/v1
kind: Deployment
metadata:
  name: api
spec:
  template:
    spec:
      containers:
        - name: api
          resources:
            requests:
              memory: 256Mi
            limits:
              memory: 512Mi

kubectl kustomize overlays/prod
kubectl diff -k overlays/prod
kubectl apply -k overlays/prod

-k est le flag intégré sur apply, diff et delete. kubectl kustomize imprime seulement le build.

Préférez labels quand vous ne voulez pas que les selectors soient réécrite. commonLabels écrit toujours sur les selectors, ce qui est douloureux à changer plus tard.

labels:
  - pairs:
      app.kubernetes.io/part-of: shop
    includeSelectors: false

Quand choisir Helm

Choisissez Helm pour ingress-nginx, cert-manager, ou tout chart que vous ne voulez pas forker. Épinglez une version. Les dépôts HTTP fonctionnent toujours :

helm repo add ingress-nginx https://kubernetes.github.io/ingress-nginx
helm repo update
helm search repo ingress-nginx/ingress-nginx --versions
helm show values ingress-nginx/ingress-nginx

helm show values imprime les clés que le chart honore. Si un paramètre manque, patchez le render plus tard. Ne forkez pas un chart pour une limite mémoire d’une ligne.

Publiez votre propre application en tant qu’artifact OCI. L’URL push n’a pas de nom chart ni de version. Helm lit les deux de la tarball. L’URL install inclut le nom chart.

helm package ./chart
helm registry login ghcr.io -u myuser
helm push shop-0.1.0.tgz oci://ghcr.io/example/charts
helm upgrade --install shop oci://ghcr.io/example/charts/shop --version 0.1.0 -n demo --create-namespace

helm package nomme le fichier à partir de Chart.yaml (name plus version). apiVersion: v2 est l’API chart Helm 3. helm registry login prend un hôte (ghcr.io), pas une URL avec un schéma ou un chemin.

Utilisez un template if quand un document existe seulement dans certains environnements. Gardez le template mince pour que les examinateurs puissent toujours voir le YAML.

Quand choisir Kustomize

Choisissez Kustomize quand chaque environnement est le même Déploiement avec un tag, namespace ou nombre de replicas différent. La base reste un YAML valide. Les overlays ne bouclent pas. Le diff git est le diff cluster.

configMapGenerator et secretGenerator hachent le nom d’objet et réécrivent les références dans cette kustomization, donc un changement de données déploie les Pods. Définissez generatorOptions.disableNameSuffixHash: true seulement quand un appelant en dehors de l’overlay a besoin d’un nom fixe. Vous possédez alors le déploiement.

Essayez l’overlay sur un cluster portable à partir de kind vs minikube vs k3d avant de le pointer vers une API partagée. Le déplacement Compose-vers-manifest en forme d’app est couvert dans Docker Compose vs Kubernetes.

Quand utiliser les deux

Un propriétaire. Un plus tard helm upgrade écrase un champ que vous aviez patché avec kubectl. Si vous appliquez un YAML rendu et ne installez jamais une release, helm rollback n’a rien à restaurer.

Rendez, puis patchez. C’est la forme praticable de « helm template, puis kustomize ». kubectl apply -k lit un répertoire, pas un pipe, donc écrivez le render dans un fichier que l’overlay répertorie :

helm template shop ./chart -n prod -f values/prod.yaml > overlays/prod/all.yaml
kubectl apply -k overlays/prod

Annulez en appliquant un plus ancien all.yaml, ou kubectl rollout undo deployment/api -n prod pour ce Déploiement seulement. Plus de patterns kubectl se trouvent dans la feuille de référence kubectl.

Gonflez un chart à l’intérieur de Kustomize. helmCharts exécute helm template en tant que sous-processus. Helm doit être sur PATH (--helm-command si le binaire est nommé autrement). --enable-helm existe sur kubectl kustomize et n’existe pas sur kubectl apply, donc -k échoue quand helmCharts est présent.

helmCharts:
  - name: ingress-nginx
    repo: https://kubernetes.github.io/ingress-nginx
    version: X.Y.Z
    releaseName: ingress-nginx
    namespace: ingress-nginx
    valuesFile: values.yaml

Remplacez X.Y.Z par une version de helm search repo ingress-nginx/ingress-nginx --versions. Puis :

kubectl kustomize --enable-helm overlays/prod | kubectl apply -f -

Il n’y a toujours pas de release Helm. Le chart n’est qu’une source de YAML.

Secrets

Helm stocke chaque révision dans un Secret nommé sh.helm.release.v1.<release>.v<revision> (type helm.sh/release.v1) dans le namespace de release. La charge utile inclut les values. Quiconque peut obtenir des Secrets là-bas peut les récupérer. Le chiffrement au repos est un paramètre etcd, pas un flag Helm.

Pointez le chart vers un Secret qui existe déjà (existingSecret est une clé values commune, pas un champ universel). Créez-le en dehors de git :

kubectl create secret generic app-secret -n demo --from-literal=POSTGRES_PASSWORD="$POSTGRES_PASSWORD"

Un littéral secretGenerator est du texte brut en git. kubectl apply -k crée le Secret et ne déchiffre rien. Déchiffrez avant d’appliquer si vous avez besoin de cela. Les générateurs exec ne font pas partie d’une course -k ordinaire.

helm.sh/resource-policy: keep dit à helm uninstall de laisser cet objet. Il ne le cache ni ne le chiffre.

Chemin de migration

Release Helm vers Kustomize. Capturez le render, marquez les objets pour que la désinstallation les laisse, puis appliquez le répertoire.

helm get manifest api -n demo > base/all.yaml
helm get values api -n demo > values-used.yaml
kubectl -n demo annotate deploy,svc,cm,secret,pvc -l app.kubernetes.io/instance=api helm.sh/resource-policy=keep --overwrite
helm uninstall api -n demo
kubectl apply -k overlays/prod

Helm 3 définit app.kubernetes.io/instance au nom de release sauf si le chart a remplacé les labels. Si un type n’a pas de correspondances, abandonnez-le et annotez de nouveau. La désinstallation supprime quoi que ce soit sans helm.sh/resource-policy: keep. Supprimez l’annotation plus tard avec un tiret de fin : kubectl annotate ... helm.sh/resource-policy-.

Répertoire Kustomize vers une release Helm. Diffez d’abord. Helm 3.2 et plus tard refusent les objets existants jusqu’à ce qu’ils portent ses métadonnées de propriété.

kubectl kustomize overlays/prod > /tmp/before.yaml
helm template api ./chart -n demo -f values/prod.yaml > /tmp/after.yaml
diff -u /tmp/before.yaml /tmp/after.yaml

Quand le diff restant ne concerne que les labels que vous acceptez, marquez les objets et installez :

kubectl -n demo annotate deployment/api svc/api cm/app-config secret/app-secret \
  meta.helm.sh/release-name=api meta.helm.sh/release-namespace=demo --overwrite
kubectl -n demo label deployment/api svc/api cm/app-config secret/app-secret \
  app.kubernetes.io/managed-by=Helm --overwrite
helm upgrade --install api ./chart -n demo -f values/prod.yaml

Répétez cela pour chaque objet que le chart rend.

helm rollback api 2 -n demo --wait

Omettez la révision pour revenir à la précédente. kubectl rollout undo deployment/api -n demo remobine seulement le modèle Pod de ce Déploiement. Utilisez helm rollback quand le mauvais changement a enjambé l’Ingress, la ConfigMap et le Déploiement ensemble.

FAQ

Devrais-je utiliser Helm ou Kustomize ?

Utilisez Helm quand vous publiez un package versionné ou installez un chart de quelqu’un d’autre. Utilisez Kustomize quand vous possédez le YAML et les environnements diffèrent par tag d’image, nombre de replicas, namespace ou un petit patch. kubectl exécute déjà Kustomize. Helm est un binaire séparé.

Puis-je utiliser Helm et Kustomize ensemble ?

Oui, si seulement l’un d’eux possède l’apply. Rendez avec helm template, patchez avec Kustomize et kubectl apply -k le résultat. Ou rendez un chart avec kubectl kustomize --enable-helm et appliquez cette sortie. Ne faites pas helm upgrade sur les objets que Kustomize patche aussi. La prochaine mise à jour remet la copie du chart.

Comment fais-je un rollback d’une release Helm par rapport à un apply Kustomize ?

helm rollback <release> <revision> restaure chaque objet de cette révision. Kustomize n’a pas d’objet release. Appliquez un overlay plus ancien à partir de git, ou exécutez kubectl rollout undo deployment/<name> pour un Déploiement. L’undo n’annule pas les Services, ConfigMaps ou quoi que ce soit d’autre dans l’overlay.

Où les mots de passe de base de données devraient-ils vivre ?

Dans un Secret créé en dehors du dépôt git, référencé par nom. Helm copie les values dans un Secret de release dans le même namespace, donc un mot de passe dans values.yaml est lisible par quiconque peut obtenir les Secrets. Kustomize secretGenerator les littéraux sont du texte brut en git. Aucun outil n’est un secret store.