Impossibile eseguire il pull di immagini da Registro Azure Container a cluster servizio Azure Kubernetes

Nota

Questo articolo è stato utile? Diamo importanza al contributo degli utenti. Usare il pulsante Feedback in questa pagina per comunicare se questo articolo è stato utile o come possiamo migliorarlo.

Quando si usa Microsoft Registro Azure Container insieme a servizio Azure Kubernetes ,è necessario stabilire un meccanismo di autenticazione. È possibile configurare l'integrazione del servizio Azure Kubernetes in Registro Contenitori usando alcuni semplici comandi dell'interfaccia della riga di comando di Azure o Azure PowerShell. Questa integrazione assegna il ruolo AcrPull per l'identità kubelet associata al cluster del servizio Azure Kubernetes per eseguire il pull di immagini da un registro contenitori.

In alcuni casi, il tentativo di eseguire il pull di immagini da un registro contenitori a un cluster del servizio Azure Kubernetes ha esito negativo. Questo articolo fornisce indicazioni per la risoluzione degli errori più comuni che si verificano quando si esegue il pull di immagini da un registro contenitori a un cluster del servizio Azure Kubernetes.

Prima di iniziare

Questo articolo presuppone che siano presenti un cluster del servizio Azure Kubernetes esistente e un registro contenitori esistente. Vedere le guide introduttive seguenti:

• Se è necessario un cluster del servizio Azure Kubernetes, distribuirne uno usando l'interfaccia della riga di comando di Azure o il portale di Azure.

• Se è necessario un Registro Azure Container (Registro Azure Container), crearne uno usando l'interfaccia della riga di comando di Azure o il portale di Azure.

È anche necessario installare e configurare l'interfaccia della riga di comando di Azure versione 2.0.59 o successiva. Eseguire az version per determinare la versione. Se è necessario installare o aggiornare, vedere Installare l'interfaccia della riga di comando di Azure.

Sintomi e risoluzione dei problemi iniziali

Lo stato del pod Kubernetes è ImagePullBackOff o ErrImagePull. Per ottenere informazioni dettagliate sugli errori, eseguire il comando seguente e controllare Eventi dall'output.

kubectl describe pod <podname> -n <namespace>

È consigliabile avviare la risoluzione dei problemi controllando l'integrità del registro contenitori e verificando se il registro contenitori è accessibile dal cluster del servizio Azure Kubernetes.

Per controllare l'integrità del Registro contenitori, eseguire il comando seguente:

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

Se viene rilevato un problema, fornisce un codice di errore e una descrizione. Per altre informazioni sugli errori e sulle possibili soluzioni, vedere Informazioni di riferimento sugli errori di controllo dell'integrità.

Nota

Se si verificano errori correlati a Helm o notarile, non significa che un problema influisca sul Registro Contenitori o sul servizio Azure Kubernetes. Indica solo che Helm o Notary non è installato o che l'interfaccia della riga di comando di Azure non è compatibile con la versione installata corrente di Helm o Notary e così via.

Per verificare se il registro contenitori è accessibile dal cluster del servizio Azure Kubernetes, eseguire il comando az aks check-acr seguente:

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

Le sezioni seguenti consentono di risolvere gli errori più comuni visualizzati in Eventi nell'output del kubectl describe pod comando.

Causa 1: 401 Errore non autorizzato

Un cluster del servizio Azure Kubernetes richiede un'identità. Questa identità può essere un'identità gestita o un'entità servizio. Se il cluster del servizio Azure Kubernetes usa un'identità gestita, l'identità kubelet viene usata per l'autenticazione con il Registro Azure Container. Se il cluster del servizio Azure Kubernetes usa come identità un'entità servizio, l'entità servizio stessa viene usata per l'autenticazione con il Registro Azure Container. Indipendentemente dall'identità, è necessaria l'autorizzazione appropriata usata per eseguire il pull di un'immagine da un registro contenitori. In caso contrario, è possibile che venga visualizzato l'errore "401 Non autorizzato":

Impossibile eseguire il pull dell'immagine "<acrname.azurecr.io/<> repository:tag>": [errore rpc: 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 Unauthorized status: 401 Unauthorized

Diverse soluzioni consentono di risolvere questo errore, in base ai vincoli seguenti:

• Le soluzioni 2, 3 e 5 sono applicabili solo ai cluster del servizio Azure Kubernetes che usano un'entità servizio.

• Le soluzioni 1, 2, 3 e 4 sono applicabili al metodo di Azure per la creazione dell'assegnazione di ruolo a livello di Registro Contenitori per l'identità del servizio Azure Kubernetes.

• Le soluzioni 5 e 6 sono applicabili per il metodo Kubernetes per il pull di un segreto Kubernetes.

Soluzione 1: Assicurarsi che l'assegnazione di ruolo AcrPull venga creata per l'identità

L'integrazione tra il servizio Azure Kubernetes e il Registro Container crea un'assegnazione di ruolo AcrPull a livello di registro contenitori per l'identità kubelet del cluster del servizio Azure Kubernetes. Assicurarsi che l'assegnazione di ruolo sia stata creata.

Per verificare se viene creata l'assegnazione di ruolo AcrPull, usare uno dei metodi seguenti:

• Eseguire il comando riportato di seguito:

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

• Archiviare il portale di Azure selezionando Registro Azure Container>Access control (IAM)>Role assignments (Assegnazioni di ruolo). Per altre informazioni, vedere Elencare le assegnazioni di ruolo di Azure usando il portale di Azure.

Oltre al ruolo AcrPull, alcuni ruoli predefiniti e ruoli personalizzati possono contenere anche l'azione "Microsoft.ContainerRegistry/registries/pull/read". Controllare questi ruoli se sono disponibili.

Se l'assegnazione di ruolo AcrPull non viene creata, crearla configurando l'integrazione del Registro Container per il cluster del servizio Azure Kubernetes con il comando seguente:

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

Soluzione 2: assicurarsi che l'entità servizio non sia scaduta

Assicurarsi che il segreto dell'entità servizio associato al cluster del servizio Azure Kubernetes non sia scaduto. Per controllare la data di scadenza dell'entità servizio, eseguire i comandi seguenti:

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

Per altre informazioni, vedere Controllare la data di scadenza dell'entità servizio.

Se il segreto è scaduto, aggiornare le credenziali per il cluster del servizio Azure Kubernetes.

Soluzione 3: assicurarsi che il ruolo AcrPull sia assegnato all'entità servizio corretta

In alcuni casi, l'assegnazione di ruolo del Registro contenitori fa ancora riferimento all'entità servizio precedente. Ad esempio, quando l'entità servizio del cluster del servizio Azure Kubernetes viene sostituita con una nuova. Per assicurarsi che l'assegnazione di ruolo del Registro contenitori faccia riferimento all'entità servizio corretta, seguire questa procedura:

1. Per controllare l'entità servizio usata dal cluster del servizio Azure Kubernetes, eseguire il comando seguente:

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

2. Per controllare l'entità servizio a cui fa riferimento l'assegnazione di ruolo del Registro contenitori, eseguire il comando seguente:

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

3. Confrontare le due entità servizio. Se non corrispondono, integrare di nuovo il cluster del servizio Azure Kubernetes con il registro contenitori.

Soluzione 4: assicurarsi che all'identità kubelet venga fatto riferimento nel servizio VM del servizio Azure Kubernetes

Quando un'identità gestita viene usata per l'autenticazione con il Registro Azure Container, l'identità gestita è nota come identità kubelet. Per impostazione predefinita, l'identità kubelet viene assegnata a livello di servizio VM del servizio Azure Kubernetes. Se l'identità kubelet viene rimossa dal servizio VM del servizio Azure Kubernetes, i nodi del servizio Azure Kubernetes non possono eseguire il pull di immagini dal Registro Azure Container.

Per trovare l'identità kubelet del cluster del servizio Azure Kubernetes, eseguire il comando seguente:

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

È quindi possibile elencare le identità del servizio VM del servizio Azure Kubernetes aprendo il servizio VMS dal gruppo di risorse del nodo e selezionando Identity>User assegnato nel portale di Azure o eseguendo il comando seguente:

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

Se l'identità kubelet del cluster del servizio Azure Kubernetes non è assegnata al servizio VM del servizio Azure Kubernetes, assegnarla nuovamente.

Nota

La modifica del servizio VM del servizio Azure Kubernetes usando le API IaaS o dal portale di Azure non è supportata e nessuna operazione del servizio Azure Kubernetes può rimuovere l'identità kubelet dal servizio VM del servizio Azure Kubernetes. Ciò significa che qualcosa di imprevisto l'ha rimossa, ad esempio una rimozione manuale eseguita da un membro del team. Per evitare tale rimozione o modifica, è possibile usare la funzionalità NRGLockdown.

Poiché le modifiche al servizio VM del servizio Azure Kubernetes non sono supportate, non vengono propagate a livello di servizio Azure Kubernetes. Per riassegnare l'identità kubelet al servizio VM del servizio Azure Kubernetes, è necessaria un'operazione di riconciliazione. A tale scopo, utilizzare il seguente comando:

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

Soluzione 5: assicurarsi che l'entità servizio sia corretta e che il segreto sia valido

Se si esegue il pull di un'immagine usando un segreto di pull dell'immagine e tale segreto Kubernetes è stato creato usando i valori di un'entità servizio, assicurarsi che l'entità servizio associata sia corretta e che il segreto sia ancora valido. attenersi alla seguente procedura:

1. Eseguire il comando kubectl get e base64 seguente per visualizzare i valori del segreto Kubernetes:

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

2. Controllare la data di scadenza eseguendo il comando az ad sp credential list seguente. Il nome utente è il valore dell'entità servizio.

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

3. Se necessario, reimpostare il segreto dell'entità servizio eseguendo il comando az ad sp credential reset seguente:

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

4. Aggiornare o ricreare di conseguenza il segreto Kubernetes.

Soluzione 6: assicurarsi che il segreto Kubernetes abbia i valori corretti dell'account amministratore del Registro contenitori

Se si esegue il pull di un'immagine usando un segreto di pull dell'immagine e tale segreto Kubernetes è stato creato usando i valori dell'account amministratore del Registro contenitori, assicurarsi che i valori nel segreto Kubernetes siano uguali ai valori dell'account di amministrazione del Registro contenitori. attenersi alla seguente procedura:

1. Eseguire il comando kubectl get e base64 seguente per visualizzare i valori del segreto Kubernetes:

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

2. Nel portale di Azure cercare e selezionare Registri contenitori.

3. Nell'elenco dei registri contenitori selezionare il registro contenitori.

4. Nel riquadro di spostamento per il registro contenitori selezionare Chiavi di accesso.

5. Nella pagina Chiavi di accesso per il registro contenitori confrontare i valori del Registro contenitori con i valori nel segreto Kubernetes.

6. Se i valori non corrispondono, aggiornare o ricreare di conseguenza il segreto Kubernetes.

Nota

Se si è verificata un'operazione Regenerate password, verrà visualizzata un'operazione denominata "Regenerate Container Registry Login Credentials" (Rigenera credenziali di accesso del Registro contenitori) nella pagina Log attività del Registro contenitori. Il log attività ha un periodo di conservazione di 90 giorni.

Causa 2: Errore dell'immagine non trovata

Impossibile eseguire il pull dell'immagine "<acrname.azurecr.io/<> repository:tag>": [errore rpc: 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

Soluzione: assicurarsi che il nome dell'immagine sia corretto

Se viene visualizzato questo errore, assicurarsi che il nome dell'immagine sia completamente corretto. È necessario controllare il nome del Registro di sistema, il server di accesso del Registro di sistema, il nome del repository e il tag. Un errore comune è che il server di accesso viene specificato come "azureacr.io" anziché "azurecr.io".

Se il nome dell'immagine non è completamente corretto, potrebbe verificarsi anche l'errore 401 Non autorizzato perché il servizio Azure Kubernetes prova sempre il pull anonimo indipendentemente dal fatto che il Registro Contenitori abbia abilitato l'accesso pull anonimo.

Causa 3: 403 Errore non consentito

Impossibile eseguire il pull dell'immagine "<acrname.azurecr.io/<> repository:tag>": errore rpc: 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 anonymous token: unexpected status: 403 Forbidden

Soluzione 1: assicurarsi che il collegamento alla rete virtuale del servizio Azure Kubernetes sia impostato nella zona DNS privato del Registro Container

Se l'interfaccia di rete dell'endpoint privato del registro contenitori e del cluster del servizio Azure Kubernetes si trovano in reti virtuali diverse, assicurarsi che il collegamento di rete virtuale per la rete virtuale del cluster del servizio Azure Kubernetes sia impostato nella zona DNS privato del registro contenitori. Per impostazione predefinita, il collegamento è denominato "privatelink.azurecr.io". Se il collegamento alla rete virtuale non è presente nella zona DNS privato del Registro contenitori, aggiungerlo usando uno dei modi seguenti:

• Nel portale di Azure selezionare la zona DNS privata "privatelink.azurecr.io", selezionare Collegamenti >di rete virtualeAggiungi nel pannello Impostazioni e quindi selezionare un nome e la rete virtuale del cluster del servizio Azure Kubernetes. Seleziona OK.

  Nota

  È facoltativo selezionare la funzionalità "Abilita registrazione automatica".

• Creare un collegamento di rete virtuale alla zona di DNS privato specificata usando l'interfaccia della riga di comando di Azure.

Soluzione 2: Aggiungere l'indirizzo IP pubblico di Load Balancer del servizio Azure Kubernetes all'intervallo di indirizzi IP consentiti del Registro Contenitori

Se il cluster del servizio Azure Kubernetes si connette pubblicamente al registro contenitori (NON tramite un collegamento privato o un endpoint) e l'accesso alla rete pubblica del registro contenitori è limitato alle reti selezionate, aggiungere l'indirizzo IP pubblico di Load Balancer del servizio Azure Kubernetes all'intervallo di indirizzi IP consentito del registro contenitori:

1. Verificare che l'accesso alla rete pubblica sia limitato alle reti selezionate.

   Nel portale di Azure passare al registro contenitori. In Impostazioni selezionare Rete. Nella scheda Accesso pubblicol'accesso alla rete pubblica è impostato su Reti selezionate o Disabilitato.

2. Ottenere l'indirizzo IP pubblico dell'Load Balancer del servizio Azure Kubernetes usando uno dei modi seguenti:

   • Nel portale di Azure passare al cluster del servizio Azure Kubernetes. In Impostazioni selezionare Proprietà, selezionare uno dei set di scalabilità di macchine virtuali nel gruppo di risorse dell'infrastruttura e controllare l'indirizzo IP pubblico del servizio Azure Kubernetes Load Balancer.

   • Eseguire il comando riportato di seguito:

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

3. Consentire l'accesso dall'indirizzo IP pubblico del servizio Azure Kubernetes Load Balancer usando uno dei modi seguenti:

   • Eseguire az acr network-rule add il comando come indicato di seguito:

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

     Per altre informazioni, vedere Aggiungere una regola di rete al Registro di sistema.

   • Nel portale di Azure passare al registro contenitori. In Impostazioni selezionare Rete. Nella scheda Accesso pubblico, in Firewall, aggiungere l'indirizzo IP pubblico dell'Load Balancer del servizio Azure Kubernetes all'intervallo di indirizzi e quindi selezionare Salva. Per altre informazioni, vedere Accesso dalla rete pubblica selezionata - portale.

     Nota

     Se l'accesso alla rete pubblica è impostato su Disabilitato, passare prima a Reti selezionate .

     

Causa 4: Errore di timeout 4: 443

Impossibile eseguire il pull dell'immagine "<acrname.azurecr.io/<> repository:tag>": errore rpc: code = Unknown desc = failed to pull and unpack image "<acrname.azurecr.io/<> repository:tag>": failed to resolve reference "<acrname.azurecr.io/>< repository:tag>": impossibile eseguire la richiesta: Head "https://< acrname.azurecr.io/v2/<> repository>/manifests/v1": dial tcp <acrprivateipaddress>:443: i/o timeout

Nota

L'errore "timeout 443" si verifica solo quando ci si connette privatamente a un registro contenitori usando collegamento privato di Azure.

Soluzione 1: assicurarsi che venga usato il peering di rete virtuale

Se l'interfaccia di rete dell'endpoint privato del registro contenitori e del cluster del servizio Azure Kubernetes si trovano in reti virtuali diverse, assicurarsi che il peering di rete virtuale venga usato per entrambe le reti virtuali. È possibile controllare il peering di rete virtuale eseguendo il comando dell'interfaccia della riga di comando az network vnet peering list --resource-group <MyResourceGroup> --vnet-name <MyVirtualNetwork> --output table di Azure o nel portale di Azure selezionandopeeringreti> virtuali nel pannello Impostazioni. Per altre informazioni sull'elenco di tutti i peering di una rete virtuale specificata, vedere az network vnet peering list.

Se il peering di rete virtuale viene usato per entrambe le reti virtuali, assicurarsi che lo stato sia "Connesso". Se lo stato è Disconnesso, eliminare il peering da entrambe le reti virtuali e quindi ricrearlo. Se lo stato è "Connesso", vedere la guida alla risoluzione dei problemi: lo stato del peering è "Connesso".

Per un'ulteriore risoluzione dei problemi, connettersi a uno dei nodi o dei pod del servizio Azure Kubernetes e quindi testare la connettività con il registro contenitori a livello TCP usando l'utilità Telnet o Netcat. Controllare l'indirizzo IP con il nslookup <acrname>.azurecr.io comando e quindi eseguire il telnet <ip-address-of-the-container-registry> 443 comando .

Per altre informazioni sulla connessione ai nodi del servizio Azure Kubernetes, vedere Connettersi con SSH ai nodi del cluster servizio Azure Kubernetes (AKS) per la manutenzione o la risoluzione dei problemi.

Soluzione 2: Usare il servizio Firewall di Azure

Se l'interfaccia di rete dell'endpoint privato del registro contenitori e del cluster del servizio Azure Kubernetes si trovano in reti virtuali diverse, oltre al peering di rete virtuale, è possibile usare il servizio Firewall di Azure per configurare una topologia di rete hub-spoke in Azure. Quando si configura la regola del firewall, è necessario usare le regole di rete per consentire in modo esplicito la connessione in uscita agli indirizzi IP dell'endpoint privato del registro contenitori.

Causa 5: Nessuna corrispondenza per la piattaforma nel manifesto

Il sistema operativo host (sistema operativo del nodo) non è compatibile con l'immagine usata per il pod o il contenitore. Ad esempio, se si pianifica un pod per l'esecuzione di un contenitore Linux in un nodo Windows o in un contenitore Windows in un nodo Linux, si verifica l'errore seguente:

Impossibile eseguire il pull dell'immagine "<acrname.azurecr.io/<> repository:tag>":
[
  Errore rpc:
  code = NotFound
  desc = impossibile eseguire il pull e decomprimere l'immagine "<acrname.azurecr.io/>< repository:tag>": nessuna corrispondenza per la piattaforma nel manifesto: non trovata,
]

Questo errore può verificarsi per un'immagine che viene estratta da qualsiasi origine, purché l'immagine non sia compatibile con il sistema operativo host. L'errore non è limitato alle immagini che vengono estratte dal registro contenitori.

Soluzione: configurare correttamente il campo nodeSelector nel pod o nella distribuzione

Specificare il campo corretto nodeSelector nelle impostazioni di configurazione del pod o della distribuzione. Il valore corretto per l'impostazione di kubernetes.io/os questo campo garantisce che il pod venga pianificato nel tipo corretto di nodo. Nella tabella seguente viene illustrato come impostare l'impostazione kubernetes.io/os in YAML:

Tipo di contenitore	Impostazione YAML
Contenitore Linux	"kubernetes.io/os": linux
Contenitore Windows	"kubernetes.io/os": windows

Ad esempio, il codice YAML seguente descrive un pod che deve essere pianificato in un nodo 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

Ulteriori informazioni

Se le indicazioni per la risoluzione dei problemi in questo articolo non consentono di risolvere il problema, ecco alcune altre cose da considerare:

• Controllare i gruppi di sicurezza di rete e le tabelle di route associate alle subnet, se sono presenti elementi di questo tipo.

• Se un'appliance virtuale come un firewall controlla il traffico tra subnet, controllare le regole di accesso del firewall e del firewall.

Dichiarazione di non responsabilità sulle informazioni di terze parti

I prodotti di terzi citati in questo articolo sono prodotti da società indipendenti da Microsoft. Microsoft non rilascia alcuna garanzia implicita o esplicita relativa alle prestazioni o all'affidabilità di tali prodotti

Contattaci per ricevere assistenza

In caso di domande o bisogno di assistenza, creare una richiesta di supporto tecnico oppure formula una domanda nel Supporto della community di Azure. È possibile anche inviare un feedback sul prodotto al feedback della community di Azure.