görüntüleri Azure Container Registry Azure Kubernetes Service kümesine çekeme

Not

Bu makale yardımcı oldu mu? Girdileriniz bizim için önemlidir. Bu makalenin sizin için ne kadar iyi çalıştığını veya nasıl geliştirebileceğimizi bize bildirmek için lütfen bu sayfadaki Geri Bildirim düğmesini kullanın.

Microsoft Azure Container Registry'ı Azure Kubernetes Service (AKS) ile birlikte kullanırken bir kimlik doğrulama mekanizması oluşturulmalıdır. Birkaç basit Azure CLI veya Azure PowerShell komutu kullanarak AKS'yi Container Registry tümleştirmesine ayarlayabilirsiniz. Bu tümleştirme, AKS kümesiyle ilişkili kubelet kimliğine bir kapsayıcı kayıt defterinden görüntü çekmek için AcrPull rolünü atar.

Bazı durumlarda, kapsayıcı kayıt defterinden AKS kümesine görüntü çekme denemesi başarısız olur. Bu makalede, kapsayıcı kayıt defterinden AKS kümesine görüntü çekerken karşılaştığınız en yaygın hataları gidermeye yönelik yönergeler sağlanır.

Başlamadan önce

Bu makalede, mevcut bir AKS kümeniz ve var olan bir kapsayıcı kayıt defteriniz olduğu varsayılır. Aşağıdaki hızlı başlangıçlara bakın:

  • AKS kümesine ihtiyacınız varsa Azure CLI veya Azure portal kullanarak bir küme dağıtın.

  • bir Azure Container Registry (ACR) gerekiyorsa Azure CLI veya Azure portal kullanarak bir tane oluşturun.

Ayrıca Azure CLI sürüm 2.0.59 veya sonraki bir sürümün yüklenip yapılandırılması gerekir. Sürümü belirlemek için az version komutunu çalıştırın. Yüklemeniz veya yükseltmeniz gerekiyorsa bkz. Azure CLI'yı yükleme.

Belirtiler ve ilk sorun giderme

Kubernetes podunun STATUS değeriImagePullBackOff veya ErrImagePull şeklindedir. Ayrıntılı hata bilgilerini almak için aşağıdaki komutu çalıştırın ve çıkıştan Olaylar'ı denetleyin.

kubectl describe pod <podname> -n <namespace>

Kapsayıcı kayıt defterinin durumunu denetleyerek ve kapsayıcı kayıt defterinin AKS kümesinden erişilebilir olup olmadığını denetleyerek sorun gidermeye başlamanızı öneririz.

Kapsayıcı kayıt defterinin durumunu denetlemek için aşağıdaki komutu çalıştırın:

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

Bir sorun algılanırsa bir hata kodu ve açıklama sağlar. Hatalar ve olası çözümler hakkında daha fazla bilgi için bkz . Sistem durumu denetimi hata başvurusu.

Not

Helm ile ilgili veya Noter ile ilgili hatalar alıyorsanız, bu bir sorunun Container Registry'yi veya AKS'yi etkilediği anlamına gelmez. Yalnızca Helm veya Noter'in yüklü olmadığını ya da Azure CLI'nin yüklü helm veya noter sürümüyle uyumlu olmadığını vb. gösterir.

Kapsayıcı kayıt defterinin AKS kümesinden erişilebilir olup olmadığını doğrulamak için aşağıdaki az aks check-acr komutunu çalıştırın:

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

Aşağıdaki bölümler, komutun çıkışındaki kubectl describe podOlaylar bölümünde görüntülenen en yaygın hataları gidermenize yardımcı olur.

Neden 1: 401 Yetkisiz hata

AKS kümesi bir kimlik gerektirir. Bu kimlik yönetilen kimlik veya hizmet sorumlusu olabilir. AKS kümesi yönetilen kimlik kullanıyorsa kubelet kimliği, ACR ile kimlik doğrulaması için kullanılır. AKS kümesi hizmet sorumlusu kimliği olarak kullanıyorsa, hizmet sorumlusunun kendisi ACR ile kimlik doğrulaması için kullanılır. Kimlik ne olursa olsun, kapsayıcı kayıt defterinden görüntü çekmek için kullanılan uygun yetkilendirme gereklidir. Aksi takdirde, aşağıdaki "401 Yetkisiz" hatasını alabilirsiniz:

"<acrname.azurecr.io/>< repository:tag>" görüntüsü çekilemedi: [rpc hatası: kod = Bilinmeyen desc = "acrname.azurecr.io/ repository:tag": "<<acrname.azurecr.io/<><> repository:tag>>" başvurusu çözümlenemedi: yetkilendirilemedi: oauth belirtecini getiremedi: beklenmeyen durum: 401 Yetkisiz

Aşağıdaki kısıtlamalara tabi olarak bu hatayı çözmenize yardımcı olabilecek çeşitli çözümler vardır:

Çözüm 1: Kimlik için AcrPull rol ataması oluşturulduğuna emin olun

AKS ile Container Registry arasındaki tümleştirme, AKS kümesinin kubelet kimliği için kapsayıcı kayıt defteri düzeyinde bir AcrPull rol ataması oluşturur. Rol atamasının oluşturulduğundan emin olun.

AcrPull rol atamasının oluşturulup oluşturulmadığını denetlemek için aşağıdaki yöntemlerden birini kullanın:

  • Aşağıdaki komutu çalıştırın:

    az role assignment list --scope /subscriptions/<subscriptionID>/resourceGroups/<resourcegroupname>/providers/Microsoft.ContainerRegistry/registries/<acrname> -o table
    
  • Azure Container Registry Access denetimi (IAM)>Rol atamaları'nı seçerek Azure portal> iade edin. Daha fazla bilgi için bkz. Azure portal kullanarak Azure rol atamalarını listeleme.

AcrPull rolünün yanı sıra bazı yerleşik roller ve özel roller de "Microsoft.ContainerRegistry/registries/pull/read" eylemini içerebilir. Bu rollerden herhangi birine sahipseniz bu rolleri denetleyin.

AcrPull rol ataması oluşturulmazsa, aşağıdaki komutla AKS kümesi için Container Registry tümleştirmesini yapılandırarak oluşturun:

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

Çözüm 2: Hizmet sorumlusu süresinin dolmadığından emin olun

AKS kümesiyle ilişkili hizmet sorumlusunun gizli dizisinin süresinin dolmadığından emin olun. Hizmet sorumlunuzun sona erme tarihini denetlemek için aşağıdaki komutları çalıştırın:

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

Daha fazla bilgi için bkz. Hizmet sorumlunuzun son kullanma tarihini denetleme.

Gizli dizinin süresi dolduysa AKS kümesinin kimlik bilgilerini güncelleştirin.

Çözüm 3: Doğru hizmet sorumlusuna AcrPull rolünün atandığından emin olun

Bazı durumlarda kapsayıcı kayıt defteri rol ataması yine de eski hizmet sorumlusuna başvurur. Örneğin, AKS kümesinin hizmet sorumlusu yenisiyle değiştirildiğinde. Kapsayıcı kayıt defteri rol atamasının doğru hizmet sorumlusuna başvurduğundan emin olmak için şu adımları izleyin:

  1. AKS kümesi tarafından kullanılan hizmet sorumlusunu denetlemek için aşağıdaki komutu çalıştırın:

    az aks show --resource-group <myResourceGroup> \
        --name <myAKSCluster> \
        --query servicePrincipalProfile.clientId \
        --output tsv
    
  2. Kapsayıcı kayıt defteri rol ataması tarafından başvuruda bulunan hizmet sorumlusunu denetlemek için aşağıdaki komutu çalıştırın:

    az role assignment list --scope /subscriptions/<subscriptionID>/resourceGroups/<resourcegroupname>/providers/Microsoft.ContainerRegistry/registries/<acrname> -o table
    
  3. İki hizmet sorumlusunu karşılaştırın. Eşleşmiyorsa AKS kümesini kapsayıcı kayıt defteriyle yeniden tümleştirin.

Çözüm 4: AKS VMSS'de kubelet kimliğine başvurulduğundan emin olun

ACR ile kimlik doğrulaması için yönetilen kimlik kullanıldığında, yönetilen kimlik kubelet kimliği olarak bilinir. Varsayılan olarak kubelet kimliği AKS VMSS düzeyinde atanır. Kubelet kimliği AKS VMSS'den kaldırılırsa AKS düğümleri ACR'den görüntü çekemez.

AKS kümenizin kubelet kimliğini bulmak için aşağıdaki komutu çalıştırın:

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

Ardından, düğüm kaynak grubundan VMSS'yi açıp Azure portal atanan Kimlik>Kullanıcısı'nı seçerek veya aşağıdaki komutu çalıştırarak AKS VMSS'nin kimliklerini listeleyebilirsiniz:

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

AKS kümenizin kubelet kimliği AKS VMSS'ye atanmamışsa yeniden atayın.

Not

IaaS API'lerini veya Azure portal kullanarak AKS VMSS'nin değiştirilmesi desteklenmez ve hiçbir AKS işlemi AKS VMSS'den kubelet kimliğini kaldıramaz. Bu, beklenmeyen bir şeyin bunu kaldırdığı anlamına gelir; örneğin, bir ekip üyesi tarafından gerçekleştirilen el ile kaldırma. Bu tür kaldırma veya değişiklikleri önlemek için NRGLockdown özelliğini kullanmayı düşünebilirsiniz.

AKS VMSS'de yapılan değişiklikler desteklenmediğinden AKS düzeyinde yayılmaz. Kubelet kimliğini AKS VMSS'ye yeniden atamak için bir mutabakat işlemi gerekir. Bunu yapmak için aşağıdaki komutu çalıştırın:

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

Çözüm 5: Hizmet sorumlusunun doğru olduğundan ve gizli dizinin geçerli olduğundan emin olun

Görüntü çekme gizli dizisi kullanarak bir görüntü çekerseniz ve kubernetes gizli dizisi bir hizmet sorumlusunun değerleri kullanılarak oluşturulduysa, ilişkili hizmet sorumlusunun doğru ve gizli dizinin hala geçerli olduğundan emin olun. Şu adımları izleyin:

  1. Kubernetes gizli dizisinin değerlerini görmek için aşağıdaki kubectl get ve base64 komutunu çalıştırın:

    kubectl get secret <secret-name> --output="jsonpath={.data.\.dockerconfigjson}" | base64 --decode
    
  2. Aşağıdaki az ad sp credential list komutunu çalıştırarak sona erme tarihini denetleyin. Kullanıcı adı hizmet sorumlusu değeridir.

    az ad sp credential list --id "<username>" --query "[].endDate" --output tsv
    
  3. Gerekirse, aşağıdaki az ad sp credential reset komutunu çalıştırarak bu hizmet sorumlusunun gizli dizisini sıfırlayın:

    az ad sp credential reset --name "$SP_ID" --query password --output tsv
    
  4. Kubernetes gizli dizisini uygun şekilde güncelleştirin veya yeniden oluşturun.

Çözüm 6: Kubernetes gizli dizisinin kapsayıcı kayıt defteri yönetici hesabının doğru değerlerine sahip olduğundan emin olun

Görüntü çekme gizli dizisi kullanarak bir görüntü çekerseniz ve kubernetes gizli dizisi kapsayıcı kayıt defteri yönetici hesabının değerleri kullanılarak oluşturulduysa, Kubernetes gizli dizisindeki değerlerin kapsayıcı kayıt defteri yönetici hesabının değerleriyle aynı olduğundan emin olun. Şu adımları izleyin:

  1. Kubernetes gizli dizisinin değerlerini görmek için aşağıdaki kubectl get ve base64 komutunu çalıştırın:

    kubectl get secret <secret-name> --output="jsonpath={.data.\.dockerconfigjson}" | base64 --decode
    
  2. Azure portalKapsayıcı kayıt defterleri'ni arayın ve seçin.

  3. Kapsayıcı kayıt defterleri listesinde kapsayıcı kayıt defterinizi seçin.

  4. Kapsayıcı kayıt defterinin gezinti bölmesinde Erişim anahtarları'nı seçin.

  5. Kapsayıcı kayıt defterinin Erişim anahtarları sayfasında, kapsayıcı kayıt defteri değerlerini Kubernetes gizli dizisindeki değerlerle karşılaştırın.

  6. Değerler eşleşmiyorsa Kubernetes gizli dizisini uygun şekilde güncelleştirin veya yeniden oluşturun.

Not

Parolayı yeniden oluştur işlemi gerçekleştiyse, kapsayıcı kayıt defterinin Etkinlik günlüğü sayfasında "Kapsayıcı Kayıt Defteri Oturum Açma Kimlik Bilgilerini Yeniden Oluştur" adlı bir işlem görüntülenir. Etkinlik günlüğünün90 günlük saklama süresi vardır.

Neden 2: Görüntü bulunamadı hatası

"<acrname.azurecr.io/>< repository:tag>" görüntüsü çekilemedi: [rpc hatası: kod = NotFound desc = "acrname.azurecr.io/ repository:tag>": "<<acrname.azurecr.io/>< repository:tag>" başvurusu çözümlenemedi: <acrname.azurecr.io/>< repository:tag>: bulunamadı><

Çözüm: Görüntü adının doğru olduğundan emin olun

Bu hatayı görürseniz, görüntü adının tamamen doğru olduğundan emin olun. Kayıt defteri adını, kayıt defteri oturum açma sunucusunu, depo adını ve etiketi denetlemeniz gerekir. Yaygın bir hata, oturum açma sunucusunun "azurecr.io" yerine "azureacr.io" olarak belirtiliyor olmasıdır.

Görüntü adı tam olarak doğru değilse, AKS kapsayıcı kayıt defterinin anonim çekme erişimini etkinleştirip etkinleştirmediğine bakılmaksızın her zaman anonim çekmeyi denediğinden 401 Yetkisiz hatası da oluşabilir.

Neden 3: 403 Yasak hatası

"<acrname.azurecr.io/<> repository:tag>" görüntüsü çekilemedi: rpc hatası: kod = Bilinmeyen desc = "acrname.azurecr.io/ repository:tag": "<<acrname.azurecr.io/<><> repository:tag>>" başvurusu çözümlenemedi: yetkilendirilemedi: anonim belirteci getiremedi: beklenmeyen durum: 403 Yasak

Kapsayıcı kayıt defterinin özel uç noktasının ve AKS kümesinin ağ arabirimi farklı sanal ağlardaysa, AKS kümesinin sanal ağı için sanal ağ bağlantısının kapsayıcı kayıt defterinin Özel DNS bölgesinde ayarlandığından emin olun. (Bu bağlantı varsayılan olarak "privatelink.azurecr.io" olarak adlandırılır.) Sanal ağ bağlantısı kapsayıcı kayıt defterinin Özel DNS bölgesinde değilse, aşağıdaki yollardan birini kullanarak ekleyin:

Çözüm 2: KAPSAYıCı kayıt defterinin izin verilen IP adresi aralığına AKS Load Balancer genel IP adresini ekleme

AKS kümesi kapsayıcı kayıt defterine genel olarak bağlanıyorsa (özel bağlantı veya uç nokta üzerinden BAĞLANMıYORsa) ve kapsayıcı kayıt defterinin genel ağ erişimi seçili ağlarla sınırlıysa, AKS Load Balancer'ın genel IP adresini kapsayıcı kayıt defterinin izin verilen IP adresi aralığına ekleyin:

  1. Genel ağ erişiminin seçili ağlara sınırlı olduğunu doğrulayın.

    Azure portal kapsayıcı kayıt defterine gidin. Ayarlar'ın altında Ağ'ı seçin. Genel erişim sekmesinde, Genel ağ erişimiSeçili ağlar veya Devre Dışı olarak ayarlanır.

  2. Aşağıdaki yollardan birini kullanarak AKS Load Balancer genel IP adresini alın:

    • Azure portal AKS kümesine gidin. Ayarlar'ın altında Özellikler'i seçin, altyapı kaynak grubundaki sanal makine ölçek kümelerinden birini seçin ve AKS Load Balancer genel IP adresini denetleyin.

    • Aşağıdaki komutu çalıştırın:

      az network public-ip show --resource-group <infrastructure-resource-group> --name <public-IP-name> --query ipAddress -o tsv
      
  3. Aşağıdaki yollardan birini kullanarak AKS Load Balancer genel IP adresinden erişime izin verin:

    • Komutu aşağıdaki gibi çalıştırın az acr network-rule add :

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

      Daha fazla bilgi için bkz. Kayıt defterine ağ kuralı ekleme.

    • Azure portal kapsayıcı kayıt defterine gidin. Ayarlar'ın altında Ağ'ı seçin. Genel erişim sekmesindeki Güvenlik Duvarı'nın altında AKS Load Balancer genel IP adresini Adres aralığına ekleyin ve kaydet'i seçin. Daha fazla bilgi için bkz. Seçili ortak ağdan erişim - portal.

      Not

      Genel ağ erişimiDevre Dışı olarak ayarlandıysa, önce Seçili ağlar'a geçin.

      AKS Load Balancer genel IP adresini Adres aralığına ekleme hakkında ekran görüntüsü

Neden 4: 443 zaman aşımı hatası

"<acrname.azurecr.io/<> repository:tag>" görüntüsü çekilemedi: rpc hatası: kod = Bilinmeyen desc = "<acrname.azurecr.io/<> repository:tag>" görüntüsünü çekip çıkaramadı: "<acrname.azurecr.io/<> repository:tag>": istek yapılamadı: Head "https://< acrname.azurecr.io/v2/<> repository>/manifests/v1": dial tcp <acrprivateipaddress>:443: i/o zaman aşımı

Çözüm 1: Sanal ağ eşlemenin kullanıldığından emin olun

Kapsayıcı kayıt defterinin özel uç noktasının ve AKS kümesinin ağ arabirimi farklı sanal ağlardaysa, sanal ağ eşlemesinin her iki sanal ağ için de kullanıldığından emin olun. Sanal ağ eşlemesini denetlemek için Azure CLI komutunu az network vnet peering list --resource-group <MyResourceGroup> --vnet-name <MyVirtualNetwork> --output table veya Azure portal Ayarlar panelinin altındaki VNETs>Eşlemeleri'ni seçebilirsiniz. Belirtilen bir sanal ağın tüm eşlemelerini listeleme hakkında daha fazla bilgi için bkz. az network vnet peering list.

Sanal ağ eşlemesi her iki sanal ağ için de kullanılıyorsa, durumun "Bağlı" olduğundan emin olun. Durum Bağlantısı Kesildi ise, eşlemeyi her iki sanal ağdan da silin ve sonra yeniden oluşturun. Durum "Bağlandı" ise sorun giderme kılavuzuna bakın: Eşleme durumu "Bağlandı".

Daha fazla sorun giderme için AKS düğümlerinden veya podlarından birine bağlanın ve ardından Telnet veya Netcat yardımcı programını kullanarak kapsayıcı kayıt defteriyle bağlantıyı TCP düzeyinde test edin. KOMUTUyla nslookup <acrname>.azurecr.io IP adresini denetleyin ve komutunu çalıştırın telnet <ip-address-of-the-container-registry> 443 .

AKS düğümlerine bağlanma hakkında daha fazla bilgi için bakım veya sorun giderme için bkz. SSH ile Azure Kubernetes Service (AKS) küme düğümlerine bağlanma.

Çözüm 2: Azure Güvenlik Duvarı Hizmetini kullanma

Kapsayıcı kayıt defterinin özel uç noktasının ve AKS kümesinin ağ arabirimi, sanal ağ eşlemesine ek olarak farklı sanal ağlardaysa, Azure'da hub-spoke ağ topolojisi ayarlamak için Azure Güvenlik Duvarı Hizmeti'ni kullanabilirsiniz. Güvenlik duvarı kuralını ayarlarken, kapsayıcı kayıt defteri özel uç nokta IP adreslerine giden bağlantıya açıkça izin vermek için ağ kurallarını kullanmanız gerekir.

Neden 5: Bildirimde platform için eşleşme yok

Konak işletim sistemi (düğüm işletim sistemi), pod veya kapsayıcı için kullanılan görüntüyle uyumsuz. Örneğin, bir Windows düğümünde Linux kapsayıcısı veya Linux düğümünde bir Windows kapsayıcısı çalıştırmak için bir pod zamanlarsanız aşağıdaki hata oluşur:

"<acrname.azurecr.io/>< repository:tag>" görüntüsü çekilemedi:
[
  rpc hatası:
  code = NotFound
  desc = "<acrname.azurecr.io/>< repository:tag>" görüntüsünü çekemedi ve paketten çıkaramadı: bildirimdeki platform için eşleşme yok: bulunamadı,
]

Bu hata, görüntü konak işletim sistemiyle uyumsuz olduğu sürece herhangi bir kaynaktan çekilen bir görüntü için oluşabilir. Hata, kapsayıcı kayıt defterinden çekilen görüntülerle sınırlı değildir.

Çözüm: Pod veya dağıtımınızda nodeSelector alanını doğru yapılandırma

Podunuzun veya dağıtımınızın yapılandırma ayarlarında doğru nodeSelector alanı belirtin. Bu alanın kubernetes.io/os ayarı için doğru değer, podun doğru düğüm türünde zamanlanmasını sağlar. Aşağıdaki tabloda YAML'de ayarın kubernetes.io/os nasıl ayarlanacağı gösterilmektedir:

Kapsayıcı türü YAML ayarı
Linux kapsayıcısı "kubernetes.io/os": linux
Windows kapsayıcısı "kubernetes.io/os": windows

Örneğin, aşağıdaki YAML kodu bir Linux düğümünde zamanlanması gereken bir podu açıklar:

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

Daha fazla bilgi

Bu makaledeki sorun giderme kılavuzu sorunu çözmenize yardımcı olmazsa, göz önünde bulundurmanız gereken diğer bazı noktalar şunlardır:

  • Bu öğelerden herhangi birine sahipseniz alt ağlarla ilişkili ağ güvenlik gruplarını ve yönlendirme tablolarını denetleyin.

  • Güvenlik duvarı gibi bir sanal gerecin alt ağlar arasındaki trafiği denetlemesi durumunda güvenlik duvarı ve Güvenlik duvarı erişim kurallarını denetleyin.

Üçüncü taraf bilgileri hakkında yasal uyarı

Bu makalede adı geçen üçüncü taraf ürünleri Microsoft'tan bağımsız şirketler tarafından üretilmektedir. Microsoft, bu ürünlerin performansı veya güvenilirliği ile ilgili örtük veya başka türlü hiçbir garanti vermez.

Yardım için bize ulaşın

Sorularınız veya yardıma ihtiyacınız varsa bir destek isteği oluşturun veya Azure topluluk desteği isteyin. Ürün geri bildirimini Azure geri bildirim topluluğuna da gönderebilirsiniz.