Partager via

Échec de l’extraction d’images d’Azure Container Registry vers un cluster Azure Kubernetes Service

  • Article

Note

Cet article vous a-t-il été utile ? Votre avis est important à nos yeux. Utilisez le bouton Commentaires sur cette page pour nous faire savoir dans quelle mesure cet article vous a été utile ou comment nous pouvons l’améliorer.

Lorsque vous utilisez Microsoft Azure Container Registry avec Azure Kubernetes Service (AKS), un mécanisme d’authentification doit être établi. Vous pouvez configurer l’intégration d’AKS à Container Registry à l’aide de quelques commandes Azure CLI ou Azure PowerShell simples. Cette intégration affecte le rôle AcrPull pour l’identité kubelet associée au cluster AKS pour extraire des images d’un registre de conteneurs.

Dans certains cas, la tentative d’extraction d’images d’un registre de conteneurs vers un cluster AKS échoue. Cet article fournit des conseils pour résoudre les erreurs les plus courantes que vous rencontrez lorsque vous extrayez des images d’un registre de conteneurs vers un cluster AKS.

Avant de commencer

Cet article suppose que vous disposez d’un cluster AKS existant et d’un registre de conteneurs existant. Consultez les démarrages rapides suivants :

Vous avez également besoin d’Azure CLI version 2.0.59 ou ultérieure pour être installé et configuré. Exécutez az version pour déterminer la version. Si vous devez installer ou mettre à niveau, consultez Installer Azure CLI.

Symptômes et résolution des problèmes initiaux

L’ÉTAT du pod Kubernetes est ImagePullBackOff ou ErrImagePull. Pour obtenir des informations détaillées sur les erreurs, exécutez la commande suivante et vérifiez les événements à partir de la sortie.

kubectl describe pod <podname> -n <namespace>

Nous vous recommandons de commencer à résoudre les problèmes en vérifiant l’intégrité du registre de conteneurs et en vérifiant si le registre de conteneurs est accessible à partir du cluster AKS.

Pour vérifier l’intégrité du registre de conteneurs, exécutez la commande suivante :

az acr check-health --name <myregistry> --ignore-errors --yes

Si un problème est détecté, il fournit un code d’erreur et une description. Pour plus d’informations sur les erreurs et les solutions possibles, consultez informations de référence sur les erreurs de vérification d’intégrité.

Note

Si vous recevez des erreurs liées à Helm ou un notarié, cela ne signifie pas que vous rencontrez un problème affectant Container Registry ou AKS. Il indique uniquement que Helm ou le notarié n’est pas installé, ou qu’Azure CLI n’est pas compatible avec la version installée actuelle de Helm ou d’un noteur, et ainsi de suite.

Pour vérifier si le registre de conteneurs est accessible à partir du cluster AKS, exécutez la commande az aks check-acr suivante :

az aks check-acr --resource-group <MyResourceGroup> --name <MyManagedCluster> --acr <myacr>.azurecr.io

Les sections suivantes vous aident à résoudre les erreurs les plus courantes affichées dans Les événements dans la sortie de la kubectl describe pod commande.

Cause 1 : Erreur non autorisée 401

Un cluster AKS nécessite une identité. Cette identité peut être une identité gérée ou un principal de service. Si le cluster AKS utilise une identité managée, l’identité kubelet est utilisée pour l’authentification auprès d’ACR. Si le cluster AKS utilise comme identité un principal de service, le principal de service lui-même est utilisé pour l’authentification auprès d’ACR. Quelle que soit l’identité, l’autorisation appropriée utilisée pour extraire une image d’un registre de conteneurs est nécessaire. Sinon, vous pouvez obtenir l’erreur « 401 Non autorisé » suivante :

Échec de l’extraction de l’image « acrname.azurecr.io/<< repository :tag> » : [rpc error : code = Unknown desc = failed to pull and unpack image « <acrname.azurecr.io/><> repository :tag> » : failed to resolve reference « <acrname.azurecr.io/>< repository :tag> » : failed to authorize : failed to fetch oauth token : unexpected status : 401 Non autorisé

Plusieurs solutions peuvent vous aider à résoudre cette erreur, sous réserve des contraintes suivantes :

Solution 1 : Vérifier que l’attribution de rôle AcrPull est créée pour l’identité

L’intégration entre AKS et Container Registry crée une attribution de rôle AcrPull au niveau du registre de conteneurs pour l’identité kubelet du cluster AKS. Vérifiez que l’attribution de rôle est créée.

Pour vérifier si l’attribution de rôle AcrPull est créée, utilisez l’une des méthodes suivantes :

  • Exécutez la commande suivante :

    az role assignment list --scope /subscriptions/<subscriptionID>/resourceGroups/<resourcegroupname>/providers/Microsoft.ContainerRegistry/registries/<acrname> -o table

  • Vérifiez les Portail Azure en sélectionnant Les attributions de rôles azure Container Registry>Access Control (IAM).>. Pour plus d’informations, consultez Répertorier les attributions de rôles Azure à l’aide du Portail Azure.

Outre le rôle AcrPull, certains rôles intégrés et rôles personnalisés peuvent également contenir l’action « Microsoft.ContainerRegistry/registrys/pull/read ». Vérifiez ces rôles si vous en avez un.

Si l’attribution de rôle AcrPull n’est pas créée, créez-la en configurant l’intégration de Container Registry pour le cluster AKS avec la commande suivante :

az aks update -n <myAKSCluster> -g <myResourceGroup> --attach-acr <acr-resource-id>

Solution 2 : Vérifier que le principal de service n’a pas expiré

Vérifiez que le secret du principal de service associé au cluster AKS n’a pas expiré. Pour vérifier la date d’expiration de votre principal de service, exécutez les commandes suivantes :

SP_ID=$(az aks show --resource-group <myResourceGroup> --name <myAKSCluster> \
    --query servicePrincipalProfile.clientId -o tsv)

az ad app credential list --id "SP_ID" --query "[].endDateTime" --output tsv

Pour plus d’informations, consultez Vérifier la date d’expiration de votre principal de service.

Si le secret a expiré, mettez à jour les informations d’identification du cluster AKS.

Solution 3 : Vérifiez que le rôle AcrPull est attribué à un principal de service correct

Dans certains cas, l’attribution de rôle de registre de conteneurs fait toujours référence à l’ancien principal de service. Par exemple, lorsque le principal de service du cluster AKS est remplacé par un nouveau. Pour vous assurer que l’attribution de rôle de registre de conteneurs fait référence au principal de service approprié, procédez comme suit :

  1. Pour vérifier le principal de service utilisé par le cluster AKS, exécutez la commande suivante :

    az aks show --resource-group <myResourceGroup> \
    --name <myAKSCluster> \
    --query servicePrincipalProfile.clientId \
    --output tsv

  2. Pour vérifier le principal de service référencé par l’attribution de rôle de registre de conteneurs, exécutez la commande suivante :

    az role assignment list --scope /subscriptions/<subscriptionID>/resourceGroups/<resourcegroupname>/providers/Microsoft.ContainerRegistry/registries/<acrname> -o table

  3. Comparez les deux principaux de service. S’ils ne correspondent pas, intégrez à nouveau le cluster AKS au registre de conteneurs.

Solution 4 : Vérifiez que l’identité kubelet est référencée dans akS VMSS

Lorsqu’une identité managée est utilisée pour l’authentification auprès de l’ACR, l’identité managée est appelée identité kubelet. Par défaut, l’identité kubelet est affectée au niveau de VMSS AKS. Si l’identité kubelet est supprimée des VMSS AKS, les nœuds AKS ne peuvent pas extraire les images de l’ACR.

Pour rechercher l’identité kubelet de votre cluster AKS, exécutez la commande suivante :

az aks show --resource-group <MyResourceGroup> --name <MyManagedCluster> --query identityProfile.kubeletidentity

Ensuite, vous pouvez répertorier les identités des VMSS AKS en ouvrant vmSS à partir du groupe de ressources de nœud et en sélectionnant Identity>User affecté dans le Portail Azure ou en exécutant la commande suivante :

az vmss identity show --resource-group <NodeResourceGroup> --name <AksVmssName>

Si l’identité kubelet de votre cluster AKS n’est pas affectée à AKS VMSS, affectez-la.

Note

La modification des VMSS AKS à l’aide des API IaaS ou de l’Portail Azure n’est pas prise en charge, et aucune opération AKS ne peut supprimer l’identité kubelet de l’instance VMSS AKS. Cela signifie que quelque chose d’inattendu l’a supprimé, par exemple une suppression manuelle effectuée par un membre de l’équipe. Pour empêcher cette suppression ou cette modification, vous pouvez envisager d’utiliser la fonctionnalité NRGLockdown.

Étant donné que les modifications apportées aux vmSS AKS ne sont pas prises en charge, elles ne se propagent pas au niveau AKS. Pour réaffecter l’identité kubelet à AKS VMSS, une opération de rapprochement est nécessaire. Pour ce faire, exécutez la commande suivante :

az aks update --resource-group <MyResourceGroup> --name <MyManagedCluster>

Solution 5 : Vérifiez que le principal de service est correct et que le secret est valide

Si vous extrayez une image à l’aide d’un secret d’extraction d’image et que le secret Kubernetes a été créé à l’aide des valeurs d’un principal de service, vérifiez que le principal de service associé est correct et que le secret est toujours valide. Effectuez les étapes suivantes :

  1. Exécutez la commande kubectl get et base64 suivante pour afficher les valeurs du secret Kubernetes :

    kubectl get secret <secret-name> --output="jsonpath={.data.\.dockerconfigjson}" | base64 --decode

  2. Vérifiez la date d’expiration en exécutant la commande az ad sp credential list suivante. Le nom d’utilisateur est la valeur du principal de service.

    az ad sp credential list --id "<username>" --query "[].endDate" --output tsv

  3. Si nécessaire, réinitialisez le secret de ce principal de service en exécutant la commande az ad sp credential reset suivante :

    az ad sp credential reset --name "$SP_ID" --query password --output tsv

  4. Mettez à jour ou recréez le secret Kubernetes en conséquence.

Solution 6 : Vérifiez que le secret Kubernetes a les valeurs correctes du compte d’administrateur du registre de conteneurs

Si vous extrayez une image à l’aide d’un secret d’extraction d’image et que le secret Kubernetes a été créé à l’aide de valeurs de compte d’administrateur de registre de conteneurs, assurez-vous que les valeurs du secret Kubernetes sont identiques aux valeurs du compte d’administrateur du registre de conteneurs. Effectuez les étapes suivantes :

  1. Exécutez la commande kubectl get et base64 suivante pour afficher les valeurs du secret Kubernetes :

    kubectl get secret <secret-name> --output="jsonpath={.data.\.dockerconfigjson}" | base64 --decode

  2. Dans le Portail Azure, recherchez et sélectionnez Registres de conteneurs.

  3. Dans la liste des registres de conteneurs, sélectionnez votre registre de conteneurs.

  4. Dans le volet de navigation du registre de conteneurs, sélectionnez Clés d’accès.

  5. Dans la page Clés d’accès du registre de conteneurs, comparez les valeurs du registre de conteneurs aux valeurs du secret Kubernetes.

  6. Si les valeurs ne correspondent pas, mettez à jour ou recréez le secret Kubernetes en conséquence.

Note

Si une opération régénérer un mot de passe s’est produite, une opération nommée « Régénérer les informations d’identification de connexion du registre de conteneurs » s’affiche dans la page journal d’activité du registre de conteneurs. Le journal d’activité a une période de rétention de 90 jours.

Cause 2 : Erreur d’image introuvable

Échec de l’extraction de l’image " acrname.azurecr.io/ repository :tag> » : [rpc error : code = NotFound desc = failed to pull and unpack image « <acrname.azurecr.io/<> repository :tag » : failed to resolve reference « <acrname.azurecr.io/< repository :tag> » : <acrname.azurecr.io/>>>< repository :tag>> : not found<<

Solution : vérifiez que le nom de l’image est correct

Si vous voyez cette erreur, assurez-vous que le nom de l’image est entièrement correct. Vous devez vérifier le nom du Registre, le serveur de connexion du Registre, le nom du référentiel et la balise. Une erreur courante est que le serveur de connexion est spécifié en tant que « azureacr.io » au lieu de « azurecr.io ».

Si le nom de l’image n’est pas entièrement correct, l’erreur 401 Non autorisée peut également se produire, car AKS tente toujours une extraction anonyme, que le registre de conteneurs ait activé des accès de tirage anonymes.

Cause 3 : Erreur 403 Interdit

Échec de l’extraction de l’image « acrname.azurecr.io/<< repository :tag> » : rpc error : code = Unknown desc = failed to pull and unpack image « <acrname.azurecr.io/><> repository :tag> » : failed to resolve reference « <acrname.azurecr.io/>< repository :tag> » : failed to allow : failed to fetch anonymous token : 403 Forbidden

Si l’interface réseau du point de terminaison privé du registre de conteneurs et le cluster AKS se trouvent dans différents réseaux virtuels, assurez-vous que la liaison de réseau virtuel du réseau virtuel du cluster AKS est définie dans la zone DNS privé du registre de conteneurs. (Ce lien est nommé « privatelink.azurecr.io » par défaut.) Si la liaison de réseau virtuel n’est pas dans la zone DNS privé du registre de conteneurs, ajoutez-la en utilisant l’une des méthodes suivantes :

Solution 2 : Ajouter l’adresse IP publique d’AKS Load Balancer à la plage d’adresses IP autorisée du registre de conteneurs

Si le cluster AKS se connecte publiquement au registre de conteneurs (pas par le biais d’une liaison privée ou d’un point de terminaison) et que l’accès au réseau public du registre de conteneurs est limité aux réseaux sélectionnés, ajoutez l’adresse IP publique d’AKS Load Balancer à la plage d’adresses IP autorisée du registre de conteneurs :

  1. Vérifiez que l’accès au réseau public est limité aux réseaux sélectionnés.

    Dans le Portail Azure, accédez au registre de conteneurs. Sous Paramètres, sélectionnez Mise en réseau. Sous l’onglet Accès public, l’accès au réseau public est défini sur Réseaux sélectionnés ou Désactivé.

  2. Obtenez l’adresse IP publique d’AKS Load Balancer en utilisant l’une des méthodes suivantes :

    • Dans le Portail Azure, accédez au cluster AKS. Sous Paramètres, sélectionnez Propriétés, sélectionnez l’un des groupes de machines virtuelles identiques dans le groupe de ressources d’infrastructure, puis vérifiez l’adresse IP publique de l’équilibreur de charge AKS.

    • Exécutez la commande suivante :

      az network public-ip show --resource-group <infrastructure-resource-group> --name <public-IP-name> --query ipAddress -o tsv

  3. Autorisez l’accès à partir de l’adresse IP publique d’AKS Load Balancer en utilisant l’une des méthodes suivantes :

    • Exécutez la az acr network-rule add commande comme suit :

      az acr network-rule add --name acrname --ip-address <AKS-load-balancer-public-IP-address>

      Pour plus d’informations, consultez Ajouter une règle réseau au Registre.

    • Dans le Portail Azure, accédez au registre de conteneurs. Sous Paramètres, sélectionnez Mise en réseau. Sous l’onglet Accès public, sous Pare-feu, ajoutez l’adresse IP publique d’AKS Load Balancer à la plage d’adresses, puis sélectionnez Enregistrer. Pour plus d’informations, consultez Access à partir du réseau public sélectionné - portail.

      Note

      Si l’accès au réseau public est défini sur Désactivé, basculez-le d’abord sur Réseaux sélectionnés .

      Capture d’écran montrant comment ajouter l’adresse IP publique d’AKS Load Balancer à la plage d’adresses

Cause 4 : « Erreur de délai d’expiration d’e/s »

Échec de l’extraction de l’image " acrname.azurecr.io/ repository :tag> » : rpc error : code = Unknown desc = failed to pull and unpack image « <acrname.azurecr.io/>>< repository :tag> » : failed to resolve reference « <acrname.azurecr.io/>< repository :tag> » : échec de la demande : Head « https://< acrname.azurecr.io/v2/<> repository>/manifests/v1 » : dial tcp <acrprivateipaddress> :443 : i/o timeout<<

Note

L’erreur « délai d’expiration des e/s » se produit uniquement lorsque vous vous connectez en privé à un registre de conteneurs à l’aide d’Azure Private Link.

Solution 1 : Vérifier que le peering de réseaux virtuels est utilisé

Si l’interface réseau du point de terminaison privé du registre de conteneurs et le cluster AKS se trouvent dans différents réseaux virtuels, vérifiez que le peering de réseaux virtuels est utilisé pour les deux réseaux virtuels. Vous pouvez vérifier le peering de réseaux virtuels en exécutant la commande az network vnet peering list --resource-group <MyResourceGroup> --vnet-name <MyVirtualNetwork> --output table Azure CLI ou dans le Portail Azure en sélectionnant les peerings> de réseaux virtuels sous le panneau Paramètres. Pour plus d’informations sur la liste de tous les peerings d’un réseau virtuel spécifié, consultez az network vnet peering list.

Si le peering de réseaux virtuels est utilisé pour les deux réseaux virtuels, vérifiez que l’état est « Connecté ». Si l’état est déconnecté, supprimez le peering des deux réseaux virtuels, puis recréez-le. Si l’état est « Connecté », consultez le guide de résolution des problèmes : l’état de peering est « Connecté ».

Pour plus de dépannage, connectez-vous à l’un des nœuds ou pods AKS, puis testez la connectivité avec le registre de conteneurs au niveau TCP à l’aide de l’utilitaire Telnet ou Netcat. Vérifiez l’adresse IP avec la nslookup <acrname>.azurecr.io commande, puis exécutez la telnet <ip-address-of-the-container-registry> 443 commande.

Pour plus d’informations sur la connexion à des nœuds AKS, consultez Se connecter avec SSH aux nœuds de cluster Azure Kubernetes Service (AKS) pour la maintenance ou la résolution des problèmes.

Solution 2 : Utiliser le service Pare-feu Azure

Si l’interface réseau du point de terminaison privé du registre de conteneurs et le cluster AKS se trouvent dans différents réseaux virtuels, en plus du peering de réseaux virtuels, vous pouvez utiliser Pare-feu Azure Service pour configurer une topologie de réseau hub-spoke dans Azure. Lorsque vous configurez la règle de pare-feu, vous devez utiliser des règles réseau pour autoriser explicitement la connexion sortante aux adresses IP du point de terminaison privé du registre de conteneurs.

Cause 5 : Aucune correspondance pour la plateforme dans le manifeste

Le système d’exploitation hôte (système d’exploitation de nœud) est incompatible avec l’image utilisée pour le pod ou le conteneur. Par exemple, si vous planifiez un pod pour exécuter un conteneur Linux sur un nœud Windows ou un conteneur Windows sur un nœud Linux, l’erreur suivante se produit :

Échec de l’extraction de l’image «< acrname.azurecr.io/>< repository :tag> » :
[
  erreur rpc :
  code = NotFound
  desc = échec de l’extraction et de la décompression de l’image « acrname.azurecr.io/<>< repository :tag> » : aucune correspondance pour la plateforme dans le manifeste : introuvable,
]

Cette erreur peut se produire pour une image extraite de n’importe quelle source, tant que l’image n’est pas compatible avec le système d’exploitation hôte. L’erreur n’est pas limitée aux images extraites du registre de conteneurs.

Solution : Configurer le champ nodeSelector correctement dans votre pod ou déploiement

Spécifiez le champ approprié nodeSelector dans les paramètres de configuration de votre pod ou déploiement. La valeur correcte du paramètre de kubernetes.io/os ce champ garantit que le pod sera planifié sur le type de nœud approprié. Le tableau suivant montre comment définir le kubernetes.io/os paramètre dans YAML :

Type de conteneur Paramètre YAML
Conteneur Linux "kubernetes.io/os": linux
Conteneur Windows "kubernetes.io/os": windows

Par exemple, le code YAML suivant décrit un pod qui doit être planifié sur un nœud Linux :

apiVersion: v1
kind: Pod
metadata:
  name: aspnetapp
  labels:
    app: aspnetapp
spec:
  containers:
  - image: "mcr.microsoft.com/dotnet/core/samples:aspnetapp"
    name: aspnetapp-image
    ports:
    - containerPort: 80
      protocol: TCP
  nodeSelector:
    "kubernetes.io/os": linux

Plus d’informations

Si les conseils de dépannage de cet article ne vous aident pas à résoudre le problème, voici d’autres éléments à prendre en compte :

  • Vérifiez les groupes de sécurité réseau et les tables de routage associées aux sous-réseaux, si vous avez l’un de ces éléments.

  • Si une appliance virtuelle comme un pare-feu contrôle le trafic entre les sous-réseaux, vérifiez les règles d’accès au pare-feu et au pare-feu.

Exclusion de responsabilité de tiers

Les produits tiers mentionnés dans le présent article sont fabriqués par des sociétés indépendantes de Microsoft. Microsoft exclut toute garantie, implicite ou autre, concernant les performances ou la fiabilité de ces produits.

Contactez-nous pour obtenir de l’aide

Pour toute demande ou assistance, créez une demande de support ou posez une question au support de la communauté Azure. Vous pouvez également soumettre des commentaires sur les produits à la communauté de commentaires Azure.