Det gick inte att hämta avbildningar från Azure Container Registry till Azure Kubernetes Service-kluster

När du använder Microsoft Azure Container Registry tillsammans med Azure Kubernetes Service (AKS) måste en autentiseringsmekanism upprättas. Du kan konfigurera AKS till Container Registry-integrering med hjälp av några enkla Azure CLI- eller Azure PowerShell-kommandon. Den här integreringen tilldelar AcrPull-rollen för kubelet-identiteten som är associerad med AKS-klustret för att hämta avbildningar från ett containerregister.

I vissa fall misslyckas försök att hämta avbildningar från ett containerregister till ett AKS-kluster. Den här artikeln innehåller vägledning för att felsöka de vanligaste felen som uppstår när du hämtar avbildningar från ett containerregister till ett AKS-kluster.

Innan du börjar

Den här artikeln förutsätter att du har ett befintligt AKS-kluster och ett befintligt containerregister. Se följande snabbstarter:

• Om du behöver ett AKS-kluster distribuerar du ett med hjälp av Azure CLI eller Azure Portal.

• Om du behöver ett Azure Container Registry (ACR) skapar du ett med hjälp av Azure CLI eller Azure Portal.

Du behöver också att Azure CLI version 2.0.59 eller en senare version installeras och konfigureras. Kör az version för att fastställa versionen. Om du måste installera eller uppgradera kan du läsa Installera Azure CLI.

Symptom och inledande felsökning

Kubernetes-poddens STATUS är ImagePullBackOff eller ErrImagePull. Om du vill få detaljerad felinformation kör du följande kommando och kontrollerar Händelser från utdata.

kubectl describe pod <podname> -n <namespace>

Vi rekommenderar att du börjar felsöka genom att kontrollera containerregistrets hälsotillstånd och kontrollera om containerregistret är tillgängligt från AKS-klustret.

Kör följande kommando för att kontrollera containerregistrets hälsotillstånd:

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

Om ett problem identifieras innehåller det en felkod och en beskrivning. Mer information om fel och möjliga lösningar finns i Felreferens för hälsokontroll.

Kontrollera om containerregistret är tillgängligt från AKS-klustret genom att köra följande az aks check-acr-kommando :

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

Följande avsnitt hjälper dig att felsöka de vanligaste felen som visas i Händelser i kommandots kubectl describe pod utdata.

Orsak 1: 401 Obehörigt fel

Orsak 1a: 401 Obehörigt fel på grund av felaktig auktorisering

Ett AKS-kluster kräver en identitet. Den här identiteten kan vara antingen en hanterad identitet eller ett huvudnamn för tjänsten. Om AKS-klustret använder en hanterad identitet används kubelet-identiteten för autentisering med ACR. Om AKS-klustret använder som en identitet som huvudnamn för tjänsten används själva tjänstens huvudnamn för autentisering med ACR. Oavsett vad identiteten är krävs rätt auktorisering som används för att hämta en avbildning från ett containerregister. Annars kan du få följande "401 Unauthorized"-fel:

Det gick inte att hämta avbildningen "<acrname.azurecr.io/>< repository:tag>": [rpc error: code = Unknown desc = failed to pull and unpack image "<acrname.azurecr.io/>< repository:tag>": det gick inte att matcha referensen "<acrname.azurecr.io/>< repository:tag>": det gick inte att auktorisera: det gick inte att hämta oauth-token: oväntad status: 401 Obehörig obehörig

Flera lösningar kan hjälpa dig att lösa det här felet, med följande begränsningar:

• Lösningarna 2, 3 och 5 gäller endast för AKS-kluster som använder tjänstens huvudnamn.

• Lösningarna 1, 2, 3 och 4 gäller för Azure-metoden för att skapa rolltilldelningen på containerregisternivå för AKS identitet.

• Lösningarna 5 och 6 gäller för Kubernetes-metoden för att hämta en Kubernetes-hemlighet.

Lösning 1: Kontrollera att AcrPull-rolltilldelning har skapats för identitet

Integreringen mellan AKS och Container Registry skapar en AcrPull-rolltilldelning på containerregisternivå för AKS-klustrets kubelet-identitet. Kontrollera att rolltilldelningen har skapats.

Om du vill kontrollera om AcrPull-rolltilldelningen har skapats använder du någon av följande metoder:

• Kör följande kommando:

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

• Checka in Azure Portal genom att välja Rolltilldelningar för Azure Container Registry>Access Control (IAM).> Mer information finns i Lista Azure-rolltilldelningar med hjälp av Azure Portal.

Förutom AcrPull-rollen kan vissa inbyggda roller och anpassade roller också innehålla åtgärden "Microsoft.ContainerRegistry/registries/pull/read". Kontrollera dessa roller om du har någon av dem.

Om rolltilldelningen AcrPull inte skapas skapar du den genom att konfigurera Container Registry-integrering för AKS-klustret med följande kommando:

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

Lösning 2: Kontrollera att tjänstens huvudnamn inte har upphört att gälla

Kontrollera att hemligheten för tjänstens huvudnamn som är associerad med AKS-klustret inte har upphört att gälla. Kör följande kommandon för att kontrollera förfallodatumet för tjänstens huvudnamn:

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

Mer information finns i Kontrollera förfallodatumet för tjänstens huvudnamn.

Om hemligheten har upphört att gälla uppdaterar du autentiseringsuppgifterna för AKS-klustret.

Lösning 3: Kontrollera att AcrPull-rollen har tilldelats rätt tjänsthuvudnamn

I vissa fall refererar rolltilldelningen för containerregistret fortfarande till det gamla tjänstens huvudnamn. När till exempel tjänstens huvudnamn för AKS-klustret ersätts med ett nytt. Följ dessa steg för att se till att rolltilldelningen för containerregistret refererar till rätt tjänsthuvudnamn:

1. Kör följande kommando för att kontrollera tjänstens huvudnamn som används av AKS-klustret:

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

2. Kör följande kommando för att kontrollera tjänstens huvudnamn som refereras av rolltilldelningen för containerregistret:

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

3. Jämför de två huvudnamnen för tjänsten. Om de inte matchar integrerar du AKS-klustret med containerregistret igen.

Lösning 4: Kontrollera att kubelet-identiteten refereras i AKS VMSS

När en hanterad identitet används för autentisering med ACR kallas den hanterade identiteten kubelet-identiteten. Som standard tilldelas kubelet-identiteten på AKS VMSS-nivå. Om kubelet-identiteten tas bort från AKS VMSS kan AKS-noderna inte hämta avbildningar från ACR.

Kör följande kommando för att hitta kubelet-identiteten för ditt AKS-kluster:

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

Sedan kan du lista identiteterna för AKS VMSS genom att öppna VMSS från nodresursgruppen och välja Identitetsanvändare>som tilldelats i Azure Portal eller genom att köra följande kommando:

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

Om kubelet-identiteten för ditt AKS-kluster inte har tilldelats till AKS VMSS tilldelar du tillbaka den.

Eftersom ändringar av AKS VMSS inte stöds sprids de inte på AKS-nivå. För att tilldela om kubelet-identiteten till AKS VMSS krävs en avstämningsåtgärd. Gör detta genom att köra följande kommando:

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

Lösning 5: Kontrollera att tjänstens huvudnamn är korrekt och att hemligheten är giltig

Om du hämtar en avbildning med hjälp av en avbildningshämtningshemlighet och kubernetes-hemligheten skapades med hjälp av värdena för tjänstens huvudnamn kontrollerar du att det associerade tjänstens huvudnamn är korrekt och att hemligheten fortfarande är giltig. Följ de här stegen:

1. Kör följande kubectl get - och base64-kommando för att se värdena för Kubernetes-hemligheten:

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

2. Kontrollera förfallodatumet genom att köra följande az ad sp-listkommando för autentiseringsuppgifter. Användarnamnet är tjänstens huvudnamn.

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

3. Om det behövs återställer du hemligheten för tjänstens huvudnamn genom att köra följande az ad sp-återställningskommando för autentiseringsuppgifter:

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

4. Uppdatera eller återskapa Kubernetes-hemligheten i enlighet med detta.

Lösning 6: Kontrollera att Kubernetes-hemligheten har rätt värden för administratörskontot för containerregistret

Om du hämtar en avbildning med hjälp av en avbildningshämtningshemlighet och kubernetes-hemligheten skapades med hjälp av värden för administratörskontot för containerregistret kontrollerar du att värdena i Kubernetes-hemligheten är samma som värdena för administratörskontot för containerregistret. Följ de här stegen:

1. Kör följande kubectl get - och base64-kommando för att se värdena för Kubernetes-hemligheten:

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

2. I Azure Portal söker du efter och väljer Containerregister.

3. I listan över containerregister väljer du ditt containerregister.

4. I navigeringsfönstret för containerregistret väljer du Åtkomstnycklar.

5. På sidan Åtkomstnycklar för containerregistret jämför du containerregistervärdena med värdena i Kubernetes-hemligheten.

6. Om värdena inte matchar uppdaterar eller återskapar du Kubernetes-hemligheten i enlighet med detta.

Orsak 1b: 401 Obehörigt fel på grund av inkompatibel arkitektur

Du kan stöta på felet "401 Obehörig" även när AKS-klusteridentiteten har auktoriserats (enligt beskrivningen i avsnittet Orsak 1a: 401 Obehörig på grund av felaktig auktorisering ). Det här problemet kan inträffa om containeravbildningen i ACR inte matchar arkitekturen (till exempel arm64 jämfört med amd64) för noden som kör containern. Om du till exempel distribuerar en arm64-avbildning på en amd64-nod eller vice versa kan det här felet uppstå.

Felmeddelandet visas på följande sätt:

Det gick inte att hämta avbildningen "<acrname.azurecr.io/><repository:tag>": [rpc error: code = NotFound desc = misslyckades med att hämta och packa upp avbildning "<acrname.azurecr.io/><repository:tag>": ingen motsvarande plattform hittades i manifestet: hittades inte, kunde inte hämta och packa upp avbildningen "<acrname.azurecr.io/><repository:tag>": det gick inte att lösa referensen "<acrname.azurecr.io/><repository:tag>": misslyckades med att auktorisera: det gick inte att hämta anonym token: oväntad status från GET-begäran till https://<acrname.azurecr.io/oauth2/token?scope=repository%3A<repository>%3Apull&service=<acrname.azurecr.io>: 401 Unauthorized]

När du diagnostiserar det här problemet med hjälp av Azure CLI kan det uppstå ett oväntat "exec format error" om system-nodpoolen kör en annan arkitektur än avbilden i ACR.

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

exec /canipull: exec format error

Lösning: Överföra bilder med rätt arkitektur eller överföra bilder för flera arkitekturer

Använd någon av följande metoder för att lösa problemet:

• Se till att containeravbildningarna som skickas till ACR matchar arkitekturen för dina AKS-noder (till exempel arm64 eller amd64).
• Skapa och ladda upp flerarkitektursavbildningar som stöder både arm64 och amd64.

Orsak 2: Det gick inte att hitta avbildningen

Det gick inte att hämta avbildningen "<acrname.azurecr.io/>< repository:tag>": [rpc error: code = NotFound desc = failed to pull and unpack image "<acrname.azurecr.io/>< repository:tag>": det gick inte att matcha referensen "<acrname.azurecr.io/>< repository:tag>": <acrname.azurecr.io/>< repository:tag>: hittades inte

Lösning: Kontrollera att avbildningsnamnet är korrekt

Om du ser det här felet kontrollerar du att avbildningsnamnet är helt korrekt. Du bör kontrollera registernamnet, registerinloggningsservern, lagringsplatsens namn och taggen. Ett vanligt misstag är att inloggningsservern anges som "azureacr.io" i stället för "azurecr.io".

Om avbildningsnamnet inte är helt korrekt kan felet 401 Obehörig också inträffa eftersom AKS alltid försöker hämta anonymt oavsett om containerregistret har aktiverat anonym pull-åtkomst.

Orsak 3: 403 Förbjudet fel

Det gick inte att hämta avbildningen "<acrname.azurecr.io/>< repository:tag>": rpc error: code = Unknown desc = failed to pull and unpack image "<acrname.azurecr.io/>< repository:tag>": det gick inte att matcha referensen "<acrname.azurecr.io/>< repository:tag>": det gick inte att auktorisera: det gick inte att hämta anonym token: oväntad status: 403 Förbjuden

Lösning 1: Kontrollera att länken för det virtuella AKS-nätverket har angetts i containerregistrets Privat DNS zon

Om nätverksgränssnittet för containerregistrets privata slutpunkt och AKS-klustret finns i olika virtuella nätverk kontrollerar du att den virtuella nätverkslänken för AKS-klustrets virtuella nätverk har angetts i Privat DNS zonen i containerregistret. (Länken heter "privatelink.azurecr.io" som standard.) Om länken för det virtuella nätverket inte finns i Privat DNS-zonen i containerregistret lägger du till den på något av följande sätt:

• I Azure Portal väljer du den privata DNS-zonen "privatelink.azurecr.io", väljer Virtuella nätverkslänkar>Lägg till under panelen Inställningar och väljer sedan ett namn och det virtuella nätverket för AKS-klustret. Välj OK.

  Kommentar

  Det är valfritt att välja funktionen "Aktivera automatisk registrering" .

• Skapa en virtuell nätverkslänk till den angivna Privat DNS-zonen med hjälp av Azure CLI.

Lösning 2: Lägg till AKS Load Balancers offentliga IP-adress till det tillåtna IP-adressintervallet för containerregistret

Om AKS-klustret ansluter offentligt till containerregistret (INTE via en privat länk eller en slutpunkt) och containerregistrets offentliga nätverksåtkomst är begränsad till valda nätverk lägger du till AKS Load Balancers offentliga IP-adress till containerregistrets tillåtna IP-adressintervall:

1. Kontrollera att den offentliga nätverksåtkomsten är begränsad till valda nätverk.

   I Azure Portal navigerar du till containerregistret. Under Inställningar väljer du Nätverk. På fliken Offentlig åtkomst är offentlig nätverksåtkomst inställd på Valda nätverk eller Inaktiverad.

2. Hämta AKS Load Balancers offentliga IP-adress med något av följande sätt:

   • I Azure Portal navigerar du till AKS-klustret. Under Inställningar väljer du Egenskaper, väljer en av vm-skalningsuppsättningarna i infrastrukturresursgruppen och kontrollerar den offentliga IP-adressen för AKS Load Balancer.

   • Kör följande kommando:

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

3. Tillåt åtkomst från AKS Load Balancers offentliga IP-adress genom att använda något av följande sätt:

   • Kör az acr network-rule add kommandot på följande sätt:

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

     Mer information finns i Lägga till nätverksregel i registret.

   • I Azure Portal navigerar du till containerregistret. Under Inställningar väljer du Nätverk. På fliken Offentlig åtkomst under Brandvägg lägger du till AKS Load Balancers offentliga IP-adress i Adressintervall och väljer sedan Spara. Mer information finns i Åtkomst från det valda offentliga nätverket – portalen.

     Kommentar

     Om Åtkomst till offentligt nätverk har angetts till Inaktiverad växlar du först till Valda nätverk .

     

Orsak 4: "i/o-timeoutfel"

Det gick inte att hämta avbildningen "<acrname.azurecr.io/>< repository:tag>": rpc error: code = Unknown desc = failed to pull and unpack image "<acrname.azurecr.io/>< repository:tag>": det gick inte att matcha referensen "<acrname.azurecr.io/>< repository:tag>": det gick inte att göra en begäran: Head "https://< acrname.azurecr.io/v2/>< repository>/manifest/v1": dial tcp <acrprivateipaddress>:443: i/o timeout

Lösning 1: Kontrollera att peering för virtuella nätverk används

Om nätverksgränssnittet för containerregistrets privata slutpunkt och AKS-klustret finns i olika virtuella nätverk kontrollerar du att peering för virtuella nätverk används för båda de virtuella nätverken. Du kan kontrollera peering för virtuella nätverk genom att köra Azure CLI-kommandot az network vnet peering list --resource-group <MyResourceGroup> --vnet-name <MyVirtualNetwork> --output table eller i Azure Portal genom att välja VNETs Peerings> under panelen Inställningar. Mer information om hur du listar alla peerings för ett angivet virtuellt nätverk finns i az network vnet peering list .

Om peering för virtuella nätverk används för båda de virtuella nätverken kontrollerar du att statusen är "Ansluten". Om statusen är Frånkopplad tar du bort peering från båda de virtuella nätverken och skapar den igen. Om statusen är "Ansluten" läser du felsökningsguiden: Peering-statusen är "Ansluten".

För ytterligare felsökning ansluter du till en av AKS-noderna eller poddarna och testar sedan anslutningen till containerregistret på TCP-nivå med hjälp av verktyget Telnet eller Netcat. Kontrollera IP-adressen med nslookup <acrname>.azurecr.io kommandot och kör telnet <ip-address-of-the-container-registry> 443 sedan kommandot .

Mer information om hur du ansluter till AKS-noder finns i Ansluta med SSH till AKS-klusternoder (Azure Kubernetes Service) för underhåll eller felsökning.

Lösning 2: Använda Azure Firewall Service

Om nätverksgränssnittet för containerregistrets privata slutpunkt och AKS-klustret finns i olika virtuella nätverk, förutom peering för virtuella nätverk, kan du använda Azure Firewall Service för att konfigurera en nätverkstopologi för hub-spoke i Azure. När du konfigurerar brandväggsregeln måste du använda nätverksregler för att uttryckligen tillåta den utgående anslutningen till containerregistrets privata slutpunkts-IP-adresser.

Orsak 5: Ingen matchning för plattform i manifest

Värdoperativsystemet (nodoperativsystem) är inte kompatibelt med den avbildning som används för podden eller containern. Om du till exempel schemalägger en podd för att köra en Linux-container på en Windows-nod eller en Windows-container på en Linux-nod uppstår följande fel:

Det gick inte att hämta avbildningen "<acrname.azurecr.io/>< repository:tag>":
[
  rpc-fel:
  code = Ej hittad
  desc = kunde inte hämta och packa upp avbildningen "<acrname.azurecr.io/>< repository:tag>": ingen matchning för plattformen i manifestet: hittades inte,
]

Det här felet kan inträffa för en avbildning som hämtas från valfri källa, så länge avbildningen inte är kompatibel med värdoperativsystemet. Felet är inte begränsat till avbildningar som hämtas från containerregistret.

Lösning: Konfigurera fältet nodeSelector korrekt i podden eller distributionen

Ange rätt nodeSelector fält i konfigurationsinställningarna för din podd eller distribution. Rätt värde för det här fältets inställning säkerställer att podden schemaläggs kubernetes.io/os på rätt typ av nod. I följande tabell visas hur du anger inställningen kubernetes.io/os i YAML:

Följande YAML-kod beskriver till exempel en podd som måste schemaläggas på en Linux-nod:

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

Orsak 6: Kubelet överskrider standardgränsen för bildhämtningshastighet

När flera jobb hämtar samma bilder kan kubelets standardgräns för pull-hastighet överskridas. I det här fallet visas ett felmeddelande som liknar följande:

Det gick inte att hämta bilden "acrname.azurecr.io/repo/nginx:latest": begäran om bilder överskred QPS-gränsen. Detta inträffade för pod <podname> den 2025-04-22, kl. 12:48:32.000 UTC.

Mer information om gränsen finns i registryPullQPS-konfigurationen.

Lösning: Ändra värdet för imagePullPolicy till IfNotPresent

Lös problemet genom att ändra värdet för imagePullPolicy från Always till IfNotPresent i YAML-distributionsfilen för att förhindra onödiga hämtningar. IfNotPresent ser till att avbildningen endast hämtas från registret om den inte redan finns på noden.

Här är ett exempel på YAML-distributionsfilen:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-deployment
spec:
  replicas: 3
  selector:
    matchLabels:
      app: my-app
  template:
    metadata:
      labels:
        app: my-app
    spec:
      containers:
      - name: my-container
        image: myacr.azurecr.io/my-image:latest
        imagePullPolicy: IfNotPresent

Mer information

Om felsökningsguiden i den här artikeln inte hjälper dig att lösa problemet kan du tänka på följande:

• Kontrollera nätverkssäkerhetsgrupper och routningstabeller som är associerade med undernät, om du har något av dessa objekt.

• Om en virtuell installation som en brandvägg styr trafiken mellan undernät kontrollerar du åtkomstreglerna för brandväggen och brandväggen.

Ansvarsfriskrivning för information från tredje part

De produkter från andra tillverkare som diskuteras i denna artikel tillverkas oberoende av Microsoft. Produkternas funktion eller tillförlitlighet kan därför inte garanteras.

Kontakta oss för att få hjälp

Om du har frågor eller behöver hjälp skapar du en supportförfrågan eller frågar Azure community support. Du kan också skicka produktfeedback till Azure-feedbackcommunityn.