Migrate from Helm V2 to Helm V3 - Container Service for Kubernetes

Important

Helm v2 a atteint sa fin de vie en novembre 2020 et ne reçoit plus de correctifs de sécurité ni de corrections de bogues. Le plug-in de migration helm-2to3 est également archivé. Nous vous recommandons vivement de finaliser la migration vers Helm v3 dans les plus brefs délais. Pour les nouveaux clusters, installez directement Helm v3 au lieu de suivre cette procédure de migration.

Afin d'éliminer les risques de sécurité potentiels liés au serveur Tiller de Helm v2, nous vous recommandons de migrer de Helm v2 vers Helm v3. Dans le cas contraire, des attaquants pourraient exploiter Tiller pour installer des applications non autorisées dans votre cluster et utiliser davantage de fonctionnalités Helm sans autorisation. Cette rubrique décrit comment migrer de Helm v2 vers Helm v3.

Prérequis

Avant de commencer la migration, assurez-vous que les conditions suivantes sont remplies :

Le client Helm v2 est installé et gère actuellement les versions (releases) sur votre cluster.
Vous disposez d'un accès kubectl au cluster et pouvez vous connecter au serveur API Kubernetes.
Vous possédez les permissions RBAC nécessaires pour accéder au namespace Tiller et gérer les ConfigMaps ou Secrets qui stockent les données de version.
Si votre cluster exécute Kubernetes 1,22 ou une version ultérieure, mettez à jour les versions API de vos ressources gérées par Helm vers des versions prises en charge avant la migration. Pour plus d'informations, consultez Mettre à jour la version API d'une ressource Kubernetes à l'aide de helm-mapkubeapis pour effectuer une mise à niveau sur place.

Sauvegarder les données Helm v2

Avant de lancer la migration, sauvegardez vos données Helm v2 afin de pouvoir les restaurer en cas d'échec de la migration.

Exécutez la commande suivante pour sauvegarder le répertoire home de Helm v2 :
```
cp -r ~/.helm ~/.helm.backup
```
Exécutez la commande suivante pour sauvegarder les données de version stockées dans le namespace Tiller. Par défaut, Helm v2 stocke les données de version sous forme de ConfigMaps dans le namespace kube-system.
```
kubectl get configmaps -n kube-system -l "OWNER=TILLER" -o yaml > helm2-releases-backup.yaml
```

Étapes de migration

Cette section utilise Helm v3.3.0 comme exemple pour illustrer la migration de Helm v2 vers Helm v3. Pour plus d'informations sur les versions de Helm, consultez Helm.

Remarque

Si vous pouvez réinstaller l'application, supprimez-la puis réinstallez-la. Pour plus d'informations, consultez Annonce de la mise à niveau de Tiller Helm v2.

Étape 1 : Installer Helm v3

Exécutez les commandes suivantes pour installer Helm v3 :

wget https://get.helm.sh/helm-v3.3.0-linux-amd64.tar.gz
tar -xzvf helm-v3.3.0-linux-amd64.tar.gz
mv linux-amd64/helm /usr/local/bin/helm
helm version

Sortie attendue :

version.BuildInfo{Version:"v3.3.0", GitCommit:"e29ce2a54e96cd02ccfce88bee4f58bb6e2a****", GitTreeState:"clean", GoVersion:"go1.13.4"}

Étape 2 : Installer le plug-in Helm 2to3

Exécutez les commandes suivantes pour installer le plug-in Helm 2to3. Les exemples de cette rubrique utilisent le chart ack-node-local-dns pour illustrer le processus de migration.

git clone https://github.com/helm/helm-2to3.git
helm plugin install ./helm-2to3

Étape 3 : Migrer la configuration Helm v2

Exécutez les commandes suivantes pour migrer votre configuration Helm v2, y compris les dépôts, les plug-ins et les modèles de chart, vers Helm v3. Nous vous recommandons d'effectuer d'abord un test à blanc (dry run) pour prévisualiser les modifications.

Effectuez un test à blanc pour prévisualiser la migration de la configuration :
```
helm 2to3 move config --dry-run
```
Si la sortie du test à blanc semble correcte, lancez la migration réelle :
```
helm 2to3 move config
```
Vérifiez que la configuration a été migrée avec succès :
```
helm repo list
```

Étape 4 : Convertir les versions (releases) vers Helm v3

Avant de convertir une version, effectuez un test à blanc pour vérifier que la conversion réussira sans apporter de modifications :

helm 2to3 convert ack-node-local-dns --dry-run

Si la sortie du test à blanc n'affiche aucune erreur, exécutez la commande suivante pour convertir le chart ack-node-local-dns vers Helm v3 :

helm 2to3 convert ack-node-local-dns --delete-v2-releases

Sortie attendue :

2022/12/27 17:12:50 Release "ack-node-local-dns" will be converted from Helm v2 to Helm v3.
2022/12/27 17:12:50 [Helm 3] Release "ack-node-local-dns" will be created.
2022/12/27 17:12:50 [Helm 3] ReleaseVersion "ack-node-local-dns.v1" will be created.
2022/12/27 17:12:50 [Helm 3] ReleaseVersion "ack-node-local-dns.v1" created.
2022/12/27 17:12:50 [Helm 3] Release "ack-node-local-dns" created.
2022/12/27 17:12:50 [Helm 2] Release "ack-node-local-dns" will be deleted.
2022/12/27 17:12:50 [Helm 2] ReleaseVersion "ack-node-local-dns.v1" will be deleted.
2022/12/27 17:12:50 [Helm 2] ReleaseVersion "ack-node-local-dns.v1" deleted.
2022/12/27 17:12:50 [Helm 2] Release "ack-node-local-dns" deleted.
2022/12/27 17:12:50 Release "ack-node-local-dns" was converted successfully from Helm v2 to Helm v3.

Une fois la conversion terminée, vérifiez que la version est désormais gérée par Helm v3 :

helm list -n kube-system

Répétez cette étape pour chaque version Helm v2 que vous souhaitez migrer. Notez qu'après la migration, les versions Helm v3 sont limitées à un namespace. Pour lister les versions dans tous les namespaces, exécutez helm list --all-namespaces.

Étape 5 : Nettoyer les données Helm v2

Après avoir vérifié que toutes les versions ont été migrées avec succès, nettoyez la configuration Helm v2 restante ainsi que les ressources Tiller. Cette étape supprime Tiller de votre cluster, éliminant ainsi le risque de sécurité associé à Helm v2.

Effectuez un test à blanc pour prévisualiser le nettoyage :
```
helm 2to3 cleanup --dry-run
```
Si la sortie du test à blanc semble correcte, lancez le nettoyage réel :
```
helm 2to3 cleanup
```

Avertissement

Après le nettoyage, Helm v2 ne sera plus utilisable sur ce cluster. Assurez-vous que toutes les versions ont été migrées et vérifiées avant de procéder.

FAQ

Erreur « Resource already exists » due à une apiVersion incohérente

Problème

Après la mise à niveau de votre cluster, le système affiche le message rendered manifests contain a new resource that already exists. Unable to continue with update: existing resource conflict: kind: MutatingWebhookConfiguration, namespace: , name: mse-pilot-ack-mse-pilot lors de la migration depuis Helm v2.

Cause

Les clusters dont la version Kubernetes est 1,22 ou ultérieure ne prennent plus en charge v1beta1. La version v1beta1 reste prise en charge dans les versions antérieures de Kubernetes. Le système peut renvoyer l'erreur précédente après la mise à niveau de votre cluster.

Solution

Mettez à jour la version API de la ressource. Pour plus d'informations, consultez Mettre à jour la version API d'une ressource Kubernetes à l'aide de helm-mapkubeapis pour effectuer une mise à niveau sur place.

Remarque

Pour éviter cette erreur, nous vous recommandons de mettre à jour les versions API de vos ressources avant de migrer de Helm v2 vers Helm v3. Consultez la section Prérequis.

Erreur lors de la mise à niveau d'un chart après la migration de Helm v2 vers Helm v3

Problème

Après la migration de Helm v2 vers v3, une erreur se produit lors de la mise à niveau de la version d'un chart, par exemple de v1.3.5 vers v1.5.3 : err: rendered manifests contain a resource that already exists. Unable to continue with update: MutatingWebhookConfiguration "ack-node-local-dns-admission-controller" in namespace "" exists and cannot be imported into the current release: invalid ownership metadata; label validation error: missing key "app.kubernetes.io/managed-by": must be set to "Helm"; annotation validation error: missing key "meta.helm.sh/release-name": must be set to "ack-node-local-dns".

Cause

Le chart ne possède pas les métadonnées de propriété Helm.

Solutions

Utilisez l'une des méthodes suivantes pour résoudre ce problème :

Méthode 1 : Attribuez la ressource à la version Helm correspondante.

Exécutez la commande suivante pour modifier le fichier de configuration.

kubectl edit MutatingWebhookConfiguration ack-node-local-dns-admission-controller

Ajoutez les annotations et labels suivantes à la version.

annotations:
  meta.helm.sh/release-name: ack-node-local-dns
  meta.helm.sh/release-namespace: kube-system
labels:
  app.kubernetes.io/managed-by: Helm

Méthode 2 : Exécutez la commande suivante pour supprimer la ressource.

kubectl delete MutatingWebhookConfiguration ack-node-local-dns-admission-controller