Envoyer (push) et tirer (pull) des graphiques Helm vers un registre de conteneurs Azure

  • Article

Pour gérer et déployer rapidement des applications pour Kubernetes, vous pouvez utiliser le Gestionnaire de package Helm open source. Avec Helm, les packages d’applications sont définis en tant que graphiques, lesquels sont collectés et stockés dans un référentiel de graphiques Helm.

Cet article vous montre la procédure à suivre pour stocker des référentiels de graphiques Helm hébergés dans le registre de conteneurs Azure, en utilisant les 3 commandes Helm et les graphiques de stockage en tant qu’artefacts OCI. Dans beaucoup de scénarios, vous devez générer et charger vos propres graphiques pour les applications que vous développez. Pour plus d’informations sur la génération de vos propres graphiques Helm, consultez le Guide pour les développeurs de graphiques Helm. Vous pouvez également stocker un graphique Helm existant à partir d’un autre dépôt Helm.

Remarque

Cet article a été mis à jour avec les commandes Helm 3. Helm 3.7 comprend des modifications apportées aux commandes CLI Helm et à la prise en charge OCI introduite dans les versions antérieures de Helm 3. Par conception, helm avance avec les mises à jour de version. Nous vous recommandons d’utiliser la version 3.7.2 ou ultérieure.

Important

  • En novembre 2020, Helm 2 a atteint la fin de sa vie. À compter du 30 mars 2025, Azure Container Registry ne prendra plus en charge Helm 2. Par conséquent, la fonctionnalité héritée « Référentiels Helm » sera également mise hors service. Nous vous recommandons de passer immédiatement à Helm 3.
  • À compter du 21 janvier 2025, la commande CLI az acr helm push sera mise hors service pour empêcher l’envoi (push) de nouveaux charts Helm à des référentiels Helm hérités.
  • À compter du 30 mars 2025, le groupe de commandes CLI az acr helm sera mis hors service, mettant fin à toutes les fonctionnalités des référentiels Helm hérités dans Azure Container Registry.
  • Tous les charts Helm non stockés en tant qu’artefact OCI seront supprimés d’Azure Container Registry le 30 mars 2025.
  • Découvrez comment trouver tous les charts Helm stockés dans un référentiel Helm ici : az acr helm list. Si le chart Helm que vous utilisez est listé, c’est qu’il est stocké dans un référentiel Helm hérité et risque d’être supprimé.

Helm 3 ou Helm 2 ?

Pour stocker, gérer et installer des graphiques Helm, vous utilisez des commandes dans l’interface CLI Helm. Les principales versions Helm incluent Helm 3 et Helm 2. Pour plus d’informations sur les différences entre les versions, consultez la FAQ sur les versions.

Helm 3 doit être utilisé pour le stockage des graphiques Helm dans Azure Container Registry. Avec Helm 3, vous pouvez :

  • stocker et gérer des graphiques Helm dans des référentiels dans le registre de conteneurs Azure
  • stocker les graphiques Helm dans un registre en tant qu’artefacts OCI. Azure Container Registry assure la prise en charge de la disponibilité générale pour les artefacts OCI, y compris les graphiques Helm.
  • Authentifiez-vous auprès du registre à l’aide de la commande helm registry login ou az acr login.
  • Utilisez les commandes helm pour envoyer (push), tirer (pull) et gérer des graphiques Helm dans un registre
  • Utiliser helm install pour installer des graphiques sur un cluster Kubernetes à partir du registre.

Prise en charge des fonctionnalités

Azure Container Registry prend en charge des fonctionnalités de gestion de graphiques Helm spécifiques selon que vous utilisez Helm 3 (actuel) ou Helm 2 (déconseillé).

Fonctionnalité Helm 2 Helm 3
Gérer des graphiques à l’aide des commandes az acr helm ✔️
Stocker des graphiques en tant qu’artefacts OCI ✔️
Gérer des graphiques à l’aide des commandes az acr repository et du panneau Référentiels dans le Portail Azure ✔️

Compatibilité des versions de graphiques

Les versions de graphiques Helm suivantes peuvent être stockées dans Azure Container Registry et peuvent être installées par les clients Helm 2 et Helm 3.

Version Helm 2 Helm 3
apiVersion v1 ✔️ ✔️
apiVersion v2 ✔️

Migrer de Helm 2 à Helm 3

Si vous avez déjà stocké et déployé des graphiques à l’aide de Helm 2 et Azure Container Registry, nous vous recommandons de migrer vers Helm 3. Consultez l'article :

Prérequis

Les ressources suivantes sont nécessaires pour le scénario décrit dans cet article :

Configurer un client Helm

Utiliser la commande helm version pour vérifier que vous avez installé Helm 3 :

helm version

Notes

La version indiquée doit être au moins la version 3.8.0, car la prise en charge de l’OCI dans les versions antérieures était expérimentale.

Définissez les variables d’environnement suivantes pour le registre cible. ACR_NAME est le nom de la ressource du registre. Si l’URL du registre ACR est myregistry.azurecr.io, définissez ACR_NAME sur myregistry

ACR_NAME=<container-registry-name>

Créer un exemple de graphique

Créez un graphique de test à l’aide des commandes suivantes :

mkdir helmtest

cd helmtest
helm create hello-world

En guise d’exemple de base, accédez au dossier templates et supprimez son contenu :

cd hello-world/templates
rm -rf *

Dans le dossier templates, créez un fichier nommé configmap.yaml en exécutant la commande suivante :

cat <<EOF > configmap.yaml
apiVersion: v1
kind: ConfigMap
metadata:
  name: hello-world-configmap
data:
  myvalue: "Hello World"
EOF

Pour plus d’informations sur la création et l’exécution de cet exemple, consultez Getting Started dans la documentation Helm.

Enregistrer le graphique dans l’archive locale

Accédez au sous-répertoire hello-world. Exécutez ensuite helm package pour enregistrer le graphique dans une archive locale.

Dans l’exemple suivant, le graphique est enregistré avec le nom et la version dans Chart.yaml.

cd ..
helm package .

Le résultat se présente ainsi :

Successfully packaged chart and saved it to: /my/path/hello-world-0.1.0.tgz

S’authentifier auprès du registre

Exécuter helm registry login pour s’authentifier auprès du registre. Vous pouvez transmettre les informations d’identification de Registre appropriées pour votre scénario, telles que les informations d’identification du principal de service, l’identité de l’utilisateur ou un jeton d’étendue de référentiel.

  • Authentifiez-vous avec un principal de service Microsoft Entra doté d’autorisations d’extraction (pull) et d’envoi (push) (rôle AcrPush) sur le registre. 
    SERVICE_PRINCIPAL_NAME=<acr-helm-sp>
ACR_REGISTRY_ID=$(az acr show --name $ACR_NAME --query id --output tsv)
PASSWORD=$(az ad sp create-for-rbac --name $SERVICE_PRINCIPAL_NAME \
          --scopes $(az acr show --name $ACR_NAME --query id --output tsv) \
           --role acrpush \
          --query "password" --output tsv)
USER_NAME=$(az identity show -n $SERVICE_PRINCIPAL_NAME -g $RESOURCE_GROUP_NAME --subscription $SUBSCRIPTION_ID --query "clientId" -o tsv)
  • Authentifiez-vous auprès de votre identité Microsoft Entra individuelle pour envoyer et extraire des graphiques Helm à l’aide d’un jeton AD. 
    USER_NAME="00000000-0000-0000-0000-000000000000"
PASSWORD=$(az acr login --name $ACR_NAME --expose-token --output tsv --query accessToken)
  • Authentifiez-vous avec un jeton limité à un référentiel (préversion). 
    USER_NAME="helmtoken"
PASSWORD=$(az acr token create -n $USER_NAME \
                  -r $ACR_NAME \
                  --scope-map _repositories_admin \
                  --only-show-errors \
                  --query "credentials.passwords[0].value" -o tsv)
  • Fournissez ensuite les informations d’identification à helm registry login. 
    helm registry login $ACR_NAME.azurecr.io \
  --username $USER_NAME \
  --password $PASSWORD

Envoyer le graphique vers le registre en tant qu’artefact OCI

Exécutez la commande helm push dans l’interface CLI Helm 3 pour envoyer (push) l’archive de graphique vers le référentiel cible (spécifié avec son nom complet). Séparez les mots des noms de graphique et utilisez uniquement des lettres minuscules et des chiffres. Dans l’exemple suivant, l’espace de noms du référentiel cible est helm/hello-world, et le graphique est étiqueté 0.1.0 :

helm push hello-world-0.1.0.tgz oci://$ACR_NAME.azurecr.io/helm

Après une opération push réussie, la sortie ressemble à ceci :

Pushed: <registry>.azurecr.io/helm/hello-world:0.1.0
digest: sha256:5899db028dcf96aeaabdadfa5899db02589b2899b025899b059db02

Répertorier les graphiques dans le référentiel

Comme avec les images stockées dans un registre de conteneurs Azure, vous pouvez utiliser les commandes az acr repository pour lister les référentiels hébergeant vos graphiques ainsi que les étiquettes et les manifestes des graphiques.

Par exemple, exécutez az acr repository show pour voir les propriétés du référentiel que vous avez créé à l’étape précédente :

az acr repository show \
  --name $ACR_NAME \
  --repository helm/hello-world

Le résultat se présente ainsi :

{
  "changeableAttributes": {
    "deleteEnabled": true,
    "listEnabled": true,
    "readEnabled": true,
    "writeEnabled": true
  },
  "createdTime": "2021-10-05T12:11:37.6701689Z",
  "imageName": "helm/hello-world",
  "lastUpdateTime": "2021-10-05T12:11:37.7637082Z",
  "manifestCount": 1,
  "registry": "mycontainerregistry.azurecr.io",
  "tagCount": 1
}

Exécutez la commande az acr manifest list-metadata pour voir les détails du graphique stocké dans le référentiel. Par exemple :

az acr manifest list-metadata \
  --registry $ACR_NAME \
  --name helm/hello-world

La sortie, abrégée dans cet exemple, montre le paramètre configMediaType défini à application/vnd.cncf.helm.config.v1+json :

[
  {
    [...]
    "configMediaType": "application/vnd.cncf.helm.config.v1+json",
    "createdTime": "2021-10-05T12:11:37.7167893Z",
    "digest": "sha256:0c03b71c225c3ddff53660258ea16ca7412b53b1f6811bf769d8c85a1f0663ee",
    "imageSize": 3301,
    "lastUpdateTime": "2021-10-05T12:11:37.7167893Z",
    "mediaType": "application/vnd.oci.image.manifest.v1+json",
    "tags": [
      "0.1.0"
    ]

Installer le graphique Helm

Exécutez helm install pour installer le graphique Helm que vous avez envoyé au registre. L’étiquette de graphique est passée à l’aide du paramètre --version. Spécifiez un nom de version, par exemple myhelmtest, ou passez le paramètre --generate-name. Par exemple :

helm install myhelmtest oci://$ACR_NAME.azurecr.io/helm/hello-world --version 0.1.0

La sortie après l’installation réussie du graphique est semblable à celle-ci :

NAME: myhelmtest
LAST DEPLOYED: Tue Oct  4 16:59:51 2021
NAMESPACE: default
STATUS: deployed
REVISION: 1
TEST SUITE: None

Pour vérifier l’installation, exécutez la commande helm get manifest.

helm get manifest myhelmtest

La commande retourne les données YAML dans votre fichier de modèle configmap.yaml.

Exécutez helm uninstall pour désinstaller la version du graphique sur votre cluster :

helm uninstall myhelmtest

Extraire le graphique vers une archive locale

Vous pouvez éventuellement extraire un graphique du registre de conteneurs vers une archive locale à l’aide de helm pull. L’étiquette de graphique est passée à l’aide du paramètre --version. S’il existe une archive locale dans le chemin actuel, cette commande la remplace.

helm pull oci://$ACR_NAME.azurecr.io/helm/hello-world --version 0.1.0

Supprimer le graphique du registre

Pour supprimer un graphique du registre de conteneurs, utilisez la commande az acr repository delete. Exécutez la commande suivante, puis confirmez l’opération lorsque vous y êtes invité :

az acr repository delete --name $ACR_NAME --image helm/hello-world:0.1.0

Migrer votre registre pour stocker les artefacts Helm OCI

Si vous configurez préalablement votre registre de conteneurs Azure en tant que référentiel de graphiques à l’aide de Helm 2 et des commandes az acr helm, nous vous recommandons de mettre à niveau vers le client Helm 3. Ensuite, procédez comme suit pour stocker les graphiques en tant qu’artefacts OCI dans votre registre.

Important

  • Une fois que vous avez terminé la migration à partir d’un référentiel de graphiques de style Helm 2 (basé sur index.yaml) vers des référentiels d’artefacts OCI, utilisez l’interface de ligne de commande Helm et les commandes az acr repository pour gérer les graphiques. Consultez les sections précédentes de cet article.
  • Les référentiels d’artefacts OCI Helm ne sont pas détectables à l’aide des commandes Helm telles que helm search et helm repo list. Pour plus d’informations sur les commandes Helm utilisées pour stocker des graphiques en tant qu’artefacts OCI, consultez la documentation Helm.

Activer la prise en charge OCI (activée par défaut dans Helm v3.8.0)

Vérifiez que vous utilisez le client Helm 3 :

helm version

Si vous utilisez Helm v3.8.0 ou version ultérieure, cette option est activée par défaut. Si vous utilisez une version antérieure, vous pouvez activer la prise en charge OCI en définissant la variable d’environnement :

export HELM_EXPERIMENTAL_OCI=1

Répertorier les graphiques actuels

Répertoriez les graphiques actuellement stockés dans le registre, ici nommémyregistry :

helm search repo myregistry

La sortie affiche les graphiques et les versions de graphiques :

NAME                            CHART VERSION   APP VERSION     DESCRIPTION                                       
myregistry/ingress-nginx        3.20.1          0.43.0          Ingress controller for Kubernetes...
myregistry/wordpress            9.0.3           5.3.2           Web publishing platform for building...
[...]

Extraire des archives de graphiques localement

Pour chaque graphique du référentiel, extrayez l’archive de graphique localement et prenez note du nom de fichier :

helm pull myregisry/ingress-nginx
ls *.tgz

Une archive de graphique locale telle que ingress-nginx-3.20.1.tgz est créée.

Envoyer des graphiques en tant qu’artefacts OCI au registre

Se connecter au registre :

az acr login --name $ACR_NAME

Envoyez (push) chaque archive de graphique vers le registre. Exemple :

helm push ingress-nginx-3.20.1.tgz oci://$ACR_NAME.azurecr.io/helm

Après avoir envoyé un graphique, confirmez qu’il est stocké dans le registre :

az acr repository list --name $ACR_NAME

Après avoir envoyé tous les graphiques, supprimez éventuellement le référentiel de graphiques de type Helm 2 du registre. Cela réduit le stockage dans votre registre :

helm repo remove $ACR_NAME

Étapes suivantes