Nie można ściągnąć obrazów z Azure Container Registry do klastra Azure Kubernetes Service

Uwaga

Czy ten artykuł był pomocny? Twoje dane wejściowe są dla nas ważne. Użyj przycisku Opinie na tej stronie, aby poinformować nas, jak dobrze działa ten artykuł dla Ciebie lub jak możemy go ulepszyć.

W przypadku korzystania z usługi Microsoft Azure Container Registry wraz z usługą Azure Kubernetes Service (AKS) należy ustanowić mechanizm uwierzytelniania. Integrację usługi AKS z usługą Container Registry można skonfigurować przy użyciu kilku prostych poleceń interfejsu wiersza polecenia platformy Azure lub Azure PowerShell. Ta integracja przypisuje rolę AcrPull dla tożsamości kubelet skojarzonej z klastrem USŁUGI AKS w celu ściągania obrazów z rejestru kontenerów.

W niektórych przypadkach próba ściągnięcia obrazów z rejestru kontenerów do klastra usługi AKS kończy się niepowodzeniem. Ten artykuł zawiera wskazówki dotyczące rozwiązywania typowych błędów występujących podczas ściągania obrazów z rejestru kontenerów do klastra usługi AKS.

Przed rozpoczęciem

W tym artykule przyjęto założenie, że masz istniejący klaster usługi AKS i istniejący rejestr kontenerów. Zobacz następujące przewodniki Szybki start:

Musisz również zainstalować i skonfigurować interfejs wiersza polecenia platformy Azure w wersji 2.0.59 lub nowszej. Uruchom polecenie az version , aby określić wersję. Jeśli musisz zainstalować lub uaktualnić, zobacz Instalowanie interfejsu wiersza polecenia platformy Azure.

Objawy i początkowe rozwiązywanie problemów

Stan zasobnika Kubernetes toImagePullBackOff lub ErrImagePull. Aby uzyskać szczegółowe informacje o błędzie, uruchom następujące polecenie i sprawdź zdarzenia z danych wyjściowych.

kubectl describe pod <podname> -n <namespace>

Zalecamy rozpoczęcie rozwiązywania problemów od sprawdzenia kondycji rejestru kontenerów i sprawdzenia, czy rejestr kontenerów jest dostępny z klastra usługi AKS.

Aby sprawdzić kondycję rejestru kontenerów, uruchom następujące polecenie:

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

Jeśli problem zostanie wykryty, zawiera kod błędu i opis. Aby uzyskać więcej informacji na temat błędów i możliwych rozwiązań, zobacz Dokumentacja błędów sprawdzania kondycji.

Uwaga

Jeśli wystąpią błędy związane z programem Helm lub Notary, nie oznacza to, że problem ma wpływ na usługę Container Registry lub AKS. Wskazuje tylko, że program Helm lub notariusz nie jest zainstalowany lub interfejs wiersza polecenia platformy Azure nie jest zgodny z bieżącą zainstalowaną wersją programu Helm lub Notary itd.

Aby sprawdzić, czy rejestr kontenerów jest dostępny z klastra usługi AKS, uruchom następujące polecenie az aks check-acr :

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

Poniższe sekcje ułatwiają rozwiązywanie problemów z najczęstszymi błędami wyświetlanymi w obszarze Zdarzenia w danych wyjściowych kubectl describe pod polecenia.

Przyczyna 1: błąd 401 Brak autoryzacji

Klaster usługi AKS wymaga tożsamości. Ta tożsamość może być tożsamością zarządzaną lub jednostką usługi. Jeśli klaster usługi AKS używa tożsamości zarządzanej, tożsamość kubelet jest używana do uwierzytelniania za pomocą usługi ACR. Jeśli klaster usługi AKS używa jako tożsamości jednostki usługi, sama jednostka usługi jest używana do uwierzytelniania za pomocą usługi ACR. Niezależnie od tożsamości wymagana jest właściwa autoryzacja używana do ściągania obrazu z rejestru kontenerów. W przeciwnym razie może wystąpić następujący błąd "401 Brak autoryzacji":

Nie można ściągnąć obrazu "<acrname.azurecr.io/<> repository:tag>": [błąd rpc: kod = Nieznany desc = nie można ściągnąć i rozpakować obrazu "<acrname.azurecr.io/>< repository:tag>": nie można rozpoznać odwołania "<acrname.azurecr.io/>< repository:tag>": nie można autoryzować: nie można pobrać tokenu oauth: nieoczekiwany stan: 401 Brak autoryzacji

Kilka rozwiązań może pomóc w rozwiązaniu tego błędu, z zastrzeżeniem następujących ograniczeń:

Rozwiązanie 1. Upewnij się, że przypisanie roli AcrPull zostało utworzone dla tożsamości

Integracja usług AKS i Container Registry tworzy przypisanie roli AcrPull na poziomie rejestru kontenerów dla tożsamości kubelet klastra AKS. Upewnij się, że przypisanie roli zostało utworzone.

Aby sprawdzić, czy przypisanie roli AcrPull zostało utworzone, użyj jednej z następujących metod:

Oprócz roli AcrPull niektóre wbudowane role i role niestandardowe mogą również zawierać akcję "Microsoft.ContainerRegistry/registries/pull/read". Sprawdź te role, jeśli masz dowolną z nich.

Jeśli przypisanie roli AcrPull nie zostało utworzone, utwórz je, konfigurując integrację usługi Container Registry dla klastra usługi AKS za pomocą następującego polecenia:

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

Rozwiązanie 2. Upewnij się, że jednostka usługi nie wygasła

Upewnij się, że wpis tajny jednostki usługi skojarzonej z klastrem usługi AKS nie wygasł. Aby sprawdzić datę wygaśnięcia jednostki usługi, uruchom następujące polecenia:

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

az ad sp credential list --id "$SP_ID" --query "[].endDate" -o tsv

Aby uzyskać więcej informacji, zobacz Sprawdzanie daty wygaśnięcia jednostki usługi.

Jeśli wpis tajny wygasł, zaktualizuj poświadczenia klastra usługi AKS.

Rozwiązanie 3. Upewnij się, że rola AcrPull została przypisana do poprawnej jednostki usługi

W niektórych przypadkach przypisanie roli rejestru kontenerów nadal odnosi się do starej jednostki usługi. Na przykład gdy jednostka usługi klastra AKS zostanie zastąpiona nową. Aby upewnić się, że przypisanie roli rejestru kontenerów odwołuje się do prawidłowej jednostki usługi, wykonaj następujące kroki:

  1. Aby sprawdzić jednostkę usługi używaną przez klaster usługi AKS, uruchom następujące polecenie:

    az aks show --resource-group <myResourceGroup> \
        --name <myAKSCluster> \
        --query servicePrincipalProfile.clientId \
        --output tsv
    
  2. Aby sprawdzić jednostkę usługi, do którego odwołuje się przypisanie roli rejestru kontenerów, uruchom następujące polecenie:

    az role assignment list --scope /subscriptions/<subscriptionID>/resourceGroups/<resourcegroupname>/providers/Microsoft.ContainerRegistry/registries/<acrname> -o table
    
  3. Porównaj dwie jednostki usługi. Jeśli nie są one zgodne, ponownie zintegruj klaster usługi AKS z rejestrem kontenerów.

Rozwiązanie 4. Upewnij się, że tożsamość kubelet jest przywoływane w usłudze AKS VMSS

Gdy tożsamość zarządzana jest używana do uwierzytelniania za pomocą usługi ACR, tożsamość zarządzana jest znana jako tożsamość kubelet. Domyślnie tożsamość kubelet jest przypisywana na poziomie usługi AKS VMSS. Jeśli tożsamość kubelet zostanie usunięta z usługi AKS VMSS, węzły usługi AKS nie będą mogły ściągać obrazów z usługi ACR.

Aby znaleźć tożsamość kubelet klastra usługi AKS, uruchom następujące polecenie:

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

Następnie możesz wyświetlić listę tożsamości maszyn wirtualnych usługi AKS, otwierając usługę VMSS z grupy zasobów węzła i wybierając pozycję Użytkownik tożsamości>przypisany w Azure Portal lub uruchamiając następujące polecenie:

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

Jeśli tożsamość kubelet klastra usługi AKS nie jest przypisana do usługi AKS VMSS, przypisz ją z powrotem.

Uwaga

Modyfikowanie usługi AKS VMSS przy użyciu interfejsów API IaaS lub z Azure Portal nie jest obsługiwane i żadna operacja usługi AKS nie może usunąć tożsamości kubelet z usługi AKS VMSS. Oznacza to, że coś nieoczekiwanego usunęło go, na przykład ręczne usunięcie wykonywane przez członka zespołu. Aby zapobiec takiemu usunięciu lub modyfikacji, możesz rozważyć użycie funkcji NRGLockdown.

Ponieważ modyfikacje usługi AKS VMSS nie są obsługiwane, nie są propagowane na poziomie usługi AKS. Aby ponownie przypisać tożsamość kubelet do usługi AKS VMSS, wymagana jest operacja uzgadniania. Aby to zrobić, uruchom następujące polecenie:

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

Rozwiązanie 5. Upewnij się, że jednostka usługi jest poprawna, a wpis tajny jest prawidłowy

Jeśli ściągasz obraz przy użyciu wpisu tajnego ściągnięcia obrazu i że klucz tajny kubernetes został utworzony przy użyciu wartości jednostki usługi, upewnij się, że skojarzona jednostka usługi jest poprawna, a wpis tajny jest nadal prawidłowy. Wykonaj następujące czynności:

  1. Uruchom następujące polecenie kubectl get i base64 , aby wyświetlić wartości wpisu tajnego kubernetes:

    kubectl get secret <secret-name> --output="jsonpath={.data.\.dockerconfigjson}" | base64 --decode
    
  2. Sprawdź datę wygaśnięcia, uruchamiając następujące polecenie az ad sp credential list . Nazwa użytkownika jest wartością jednostki usługi.

    az ad sp credential list --id "<username>" --query "[].endDate" --output tsv
    
  3. W razie potrzeby zresetuj wpis tajny tej jednostki usługi, uruchamiając następujące polecenie az ad sp credential reset :

    az ad sp credential reset --name "$SP_ID" --query password --output tsv
    
  4. Odpowiednio zaktualizuj lub ponownie utwórz wpis tajny platformy Kubernetes.

Rozwiązanie 6. Upewnij się, że wpis tajny kubernetes ma poprawne wartości konta administratora rejestru kontenerów

Jeśli ściągasz obraz przy użyciu wpisu tajnego ściągnięcia obrazu i że klucz tajny kubernetes został utworzony przy użyciu wartości konta administratora rejestru kontenerów, upewnij się, że wartości w wpisie tajnym Kubernetes są takie same jak wartości konta administratora rejestru kontenerów. Wykonaj następujące czynności:

  1. Uruchom następujące polecenie kubectl get i base64 , aby wyświetlić wartości wpisu tajnego kubernetes:

    kubectl get secret <secret-name> --output="jsonpath={.data.\.dockerconfigjson}" | base64 --decode
    
  2. W Azure Portal wyszukaj i wybierz pozycję Rejestry kontenerów.

  3. Na liście rejestrów kontenerów wybierz rejestr kontenerów.

  4. W okienku nawigacji rejestru kontenerów wybierz pozycję Klucze dostępu.

  5. Na stronie Klucze dostępu dla rejestru kontenerów porównaj wartości rejestru kontenerów z wartościami w wpisie tajnym kubernetes.

  6. Jeśli wartości nie są zgodne, odpowiednio zaktualizuj lub ponownie utwórz wpis tajny kubernetes.

Uwaga

Jeśli wystąpiła operacja ponownego generowania hasła, na stronie Dziennika aktywności rejestru kontenerów zostanie wyświetlona operacja o nazwie "Ponowne generowanie poświadczeń logowania rejestru kontenerów". Dziennik aktywności ma 90-dniowy okres przechowywania.

Przyczyna 2. Błąd nie znaleziono obrazu

Nie można ściągnąć obrazu "<acrname.azurecr.io/<> repository:tag>": [błąd rpc: code = NotFound desc = nie można ściągnąć i rozpakować obrazu "<acrname.azurecr.io/>< repository:tag>": nie można rozpoznać odwołania "<acrname.azurecr.io/<> repository:tag>": <acrname.azurecr.io/>< repository:tag>: nie znaleziono

Rozwiązanie: Upewnij się, że nazwa obrazu jest poprawna

Jeśli zostanie wyświetlony ten błąd, upewnij się, że nazwa obrazu jest w pełni poprawna. Należy sprawdzić nazwę rejestru, serwer logowania rejestru, nazwę repozytorium i tag. Typowym błędem jest to, że serwer logowania jest określany jako "azureacr.io" zamiast "azurecr.io".

Jeśli nazwa obrazu nie jest w pełni poprawna, błąd 401 Brak autoryzacji może również wystąpić, ponieważ usługa AKS zawsze próbuje anonimowego ściągania niezależnie od tego, czy rejestr kontenerów włączył anonimowy dostęp do ściągnięcia.

Przyczyna 3: Błąd 403 Zabronione

Nie można ściągnąć obrazu "<acrname.azurecr.io/<> repository:tag>": błąd rpc: kod = Nieznany desc = nie można ściągnąć i rozpakować obrazu "<acrname.azurecr.io/>< repository:tag>": nie można rozpoznać odwołania "<acrname.azurecr.io/>< repository:tag>": nie można autoryzować: nie można pobrać tokenu anonimowego: nieoczekiwany stan: 403 Zabronione

Jeśli interfejs sieciowy prywatnego punktu końcowego rejestru kontenerów i klastra USŁUGI AKS znajdują się w różnych sieciach wirtualnych, upewnij się, że łącze sieci wirtualnej dla sieci wirtualnej klastra AKS jest ustawione w strefie Prywatna strefa DNS rejestru kontenerów. (Ten link domyślnie nosi nazwę "privatelink.azurecr.io"). Jeśli łącze sieci wirtualnej nie znajduje się w strefie Prywatna strefa DNS rejestru kontenerów, dodaj je przy użyciu jednego z następujących sposobów:

Rozwiązanie 2. Dodawanie publicznego adresu IP usługi AKS Load Balancer do dozwolonego zakresu adresów IP rejestru kontenerów

Jeśli klaster usługi AKS łączy się publicznie z rejestrem kontenerów (NIE za pośrednictwem łącza prywatnego lub punktu końcowego), a dostęp do sieci publicznej rejestru kontenerów jest ograniczony do wybranych sieci, dodaj publiczny adres IP usługi AKS Load Balancer do dozwolonego zakresu adresów IP rejestru kontenerów:

  1. Sprawdź, czy dostęp do sieci publicznej jest ograniczony do wybranych sieci.

    W Azure Portal przejdź do rejestru kontenerów. W obszarze Ustawienia wybierz pozycję Sieć. Na karcie Dostęp publicznydostęp publiczny jest ustawiony na wartość Wybrane sieci lub Wyłączone.

  2. Uzyskaj publiczny adres IP usługi AKS Load Balancer przy użyciu jednego z następujących sposobów:

    • W Azure Portal przejdź do klastra usługi AKS. W obszarze Ustawienia wybierz pozycję Właściwości, wybierz jeden z zestawów skalowania maszyn wirtualnych w grupie zasobów infrastruktury i sprawdź publiczny adres IP Load Balancer usługi AKS.

    • Uruchom następujące polecenie:

      az network public-ip show --resource-group <infrastructure-resource-group> --name <public-IP-name> --query ipAddress -o tsv
      
  3. Zezwalaj na dostęp z publicznego adresu IP usługi AKS Load Balancer przy użyciu jednego z następujących sposobów:

    • Uruchom az acr network-rule add polecenie w następujący sposób:

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

      Aby uzyskać więcej informacji, zobacz Dodawanie reguły sieci do rejestru.

    • W Azure Portal przejdź do rejestru kontenerów. W obszarze Ustawienia wybierz pozycję Sieć. Na karcie Dostęp publiczny w obszarze Zapora dodaj publiczny adres IP usługi AKS Load Balancer do zakresu adresów, a następnie wybierz pozycję Zapisz. Aby uzyskać więcej informacji, zobacz Dostęp z wybranej sieci publicznej — portal.

      Uwaga

      Jeśli dostęp do sieci publicznej jest ustawiony na Wartość Wyłączone, przełącz go najpierw do pozycji Wybrane sieci .

      Zrzut ekranu przedstawiający dodawanie publicznego adresu IP usługi AKS Load Balancer do zakresu adresów

Przyczyna 4: błąd przekroczenia limitu czasu 443

Nie można ściągnąć obrazu "<acrname.azurecr.io/>< repository:tag>": błąd rpc: kod = Nieznany desc = nie można ściągnąć i rozpakować obrazu "<acrname.azurecr.io/>< repository:tag>": nie można rozpoznać odwołania "<acrname.azurecr.io/>< repository:tag>": nie można wykonać żądania: Head "https://< acrname.azurecr.io/v2/<> repository>/manifests/v1": dial tcp <acrprivateipaddress>:443: i/o timeout

Uwaga

Błąd "Limit czasu 443" występuje tylko wtedy, gdy łączysz się prywatnie z rejestrem kontenerów przy użyciu Azure Private Link.

Rozwiązanie 1. Upewnij się, że jest używana komunikacja równorzędna sieci wirtualnych

Jeśli interfejs sieciowy prywatnego punktu końcowego rejestru kontenerów i klastra USŁUGI AKS znajdują się w różnych sieciach wirtualnych, upewnij się, że komunikacja równorzędna sieci wirtualnych jest używana dla obu sieci wirtualnych. Komunikację równorzędna sieci wirtualnych można sprawdzić, uruchamiając polecenie interfejsu wiersza polecenia az network vnet peering list --resource-group <MyResourceGroup> --vnet-name <MyVirtualNetwork> --output table platformy Azure lub w Azure Portal, wybierając komunikacjęrównorzędnesieci wirtualnych> w panelu Ustawienia. Aby uzyskać więcej informacji na temat wyświetlania listy wszystkich komunikacji równorzędnej określonej sieci wirtualnej, zobacz az network vnet peering list (AZ network vnet peering list).

Jeśli komunikacja równorzędna sieci wirtualnych jest używana dla obu sieci wirtualnych, upewnij się, że stan to "Połączono". Jeśli stan to Rozłączono, usuń komunikację równorzędną z obu sieci wirtualnych, a następnie utwórz ją ponownie. Jeśli stan to "Połączono", zobacz przewodnik rozwiązywania problemów: Stan komunikacji równorzędnej to "Połączono".

W celu dalszego rozwiązywania problemów połącz się z jednym z węzłów lub zasobników usługi AKS, a następnie przetestuj łączność z rejestrem kontenerów na poziomie TCP przy użyciu narzędzia Telnet lub Netcat. Sprawdź adres IP za nslookup <acrname>.azurecr.io pomocą polecenia , a następnie uruchom telnet <ip-address-of-the-container-registry> 443 polecenie .

Aby uzyskać więcej informacji na temat nawiązywania połączenia z węzłami usługi AKS, zobacz Nawiązywanie połączenia za pomocą protokołu SSH z węzłami klastra Azure Kubernetes Service (AKS) w celu konserwacji lub rozwiązywania problemów.

Rozwiązanie 2: Korzystanie z usługi Azure Firewall

Jeśli interfejs sieciowy prywatnego punktu końcowego rejestru kontenerów i klastra AKS znajdują się w różnych sieciach wirtualnych, oprócz komunikacji równorzędnej sieci wirtualnych, możesz użyć usługi Azure Firewall Service do skonfigurowania topologii sieci piasty i szprych na platformie Azure. Podczas konfigurowania reguły zapory należy użyć reguł sieci, aby jawnie zezwolić na połączenie wychodzące z adresami IP prywatnego punktu końcowego rejestru kontenerów.

Przyczyna 5. Brak dopasowania dla platformy w manifeście

System operacyjny hosta (system operacyjny węzła) jest niezgodny z obrazem używanym dla zasobnika lub kontenera. Jeśli na przykład planujesz uruchomienie kontenera systemu Linux w węźle systemu Windows lub kontenera systemu Windows w węźle systemu Linux, występuje następujący błąd:

Nie można ściągnąć obrazu "<acrname.azurecr.io/>< repository:tag>":
[
  błąd rpc:
  code = NotFound
  desc = nie można ściągnąć i rozpakować obrazu "<acrname.azurecr.io/>< repository:tag>": brak dopasowania dla platformy w manifeście: nie znaleziono,
]

Ten błąd może wystąpić w przypadku obrazu pobieranego z dowolnego źródła, o ile obraz jest niezgodny z systemem operacyjnym hosta. Błąd nie jest ograniczony do obrazów pobieranych z rejestru kontenerów.

Rozwiązanie: Poprawnie skonfiguruj pole nodeSelector w zasobniku lub wdrożeniu

Określ poprawne nodeSelector pole w ustawieniach konfiguracji zasobnika lub wdrożenia. Poprawna wartość ustawienia tego pola kubernetes.io/os gwarantuje, że zasobnik zostanie zaplanowany na prawidłowy typ węzła. W poniższej tabeli przedstawiono sposób ustawiania ustawienia w języku kubernetes.io/os YAML:

Typ kontenera Ustawienie YAML
Kontener systemu Linux "kubernetes.io/os": linux
Kontener systemu Windows "kubernetes.io/os": windows

Na przykład poniższy kod YAML opisuje zasobnik, który należy zaplanować w węźle systemu 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

Więcej informacji

Jeśli wskazówki dotyczące rozwiązywania problemów w tym artykule nie pomogą Ci rozwiązać problemu, oto kilka innych kwestii, które należy wziąć pod uwagę:

  • Sprawdź sieciowe grupy zabezpieczeń i tabele tras skojarzone z podsieciami, jeśli masz którykolwiek z tych elementów.

  • Jeśli urządzenie wirtualne, takie jak zapora, kontroluje ruch między podsieciami, sprawdź reguły dostępu zapory i zapory.

Zastrzeżenie dotyczące innych firm

Produkty innych firm omówione w tym artykule są wytwarzane przez producentów niezależnych od firmy Microsoft. Firma Microsoft nie udziela żadnych gwarancji, dorozumianych ani żadnego innego rodzaju, w odniesieniu do wydajności lub niezawodności tych produktów.

Skontaktuj się z nami, aby uzyskać pomoc

Jeśli masz pytania lub potrzebujesz pomocy, utwórz wniosek o pomoc techniczną lub zadaj pytanie w społeczności wsparcia dla platformy Azure. Możesz również przesłać opinię o produkcie do społeczności opinii platformy Azure.