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

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

In alcuni casi, il tentativo di eseguire il pull delle 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 riscontrati quando si estraggono immagini da un registro contenitori a un cluster del servizio Azure Kubernetes.

Operazioni preliminari

Questo articolo presuppone che si disponga di un cluster del servizio Azure Kubernetes esistente e di 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 (ACR), crearne uno usando l'interfaccia della riga di comando di Azure o il portale di Azure.

È necessaria anche l'interfaccia della riga di comando di Azure 2.0.59 o una versione successiva da installare e configurare. 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 sull'errore, eseguire il comando seguente e controllare Eventi dall'output.

kubectl describe pod <podname> -n <namespace>

È consigliabile iniziare 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 sull'errore di controllo integrità.

Per verificare se il registro contenitori è accessibile dal cluster 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 Registro Azure Container. Se il cluster del servizio Azure Kubernetes usa come identità un'entità servizio, l'entità servizio viene usata per l'autenticazione con 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>": [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 fetch oauth token: unexpected status: 401 Unauthorized

Diverse soluzioni consentono di risolvere l'errore, soggetto 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 creare l'assegnazione di ruolo a livello di Registro Container per l'identità del servizio Azure Kubernetes.

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

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

L'integrazione tra servizio Azure Kubernetes e 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, utilizzare uno dei metodi seguenti:

• Esegui questo comando:

  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> Assegnare ruoli (IAM)>Controllo di accesso. 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 presenti.

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 associata 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 app credential list --id "SP_ID" --query "[].endDateTime" --output 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 l'identità kubelet sia a cui si fa riferimento nel set di scalabilità di macchine virtuali del servizio Azure Kubernetes

Quando viene usata un'identità gestita 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 set di scalabilità di macchine virtuali del servizio Azure Kubernetes. Se l'identità kubelet viene rimossa dal set di scalabilità di macchine virtuali del servizio Azure Kubernetes, i nodi del servizio Azure Kubernetes non possono eseguire il pull delle 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 set di scalabilità di macchine virtuali del servizio Azure Kubernetes aprendo il set di scalabilità di macchine virtuali dal gruppo di risorse del nodo e selezionando Identità>utente 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 set di scalabilità di macchine virtuali del servizio Azure Kubernetes, assegnarla di nuovo.

Poiché le modifiche apportate al set di scalabilità di macchine virtuali del servizio Azure Kubernetes non sono supportate, non vengono propagate a livello del servizio Azure Kubernetes. Per riassegnare l'identità kubelet al set di scalabilità di macchine virtuali 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 pull dell'immagine e che il 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. Seguire questa 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 il segreto Kubernetes di conseguenza.

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 pull dell'immagine e che il segreto Kubernetes è stato creato usando i valori dell'account amministratore del registro contenitori, assicurarsi che i valori nel segreto Kubernetes corrispondano ai valori dell'account amministratore del registro contenitori. Seguire questa 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. Nella 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 il segreto Kubernetes di conseguenza.

Causa 2: Errore immagine non trovata

Impossibile eseguire il pull dell'immagine "<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

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, l'errore 401 Non autorizzato può verificarsi anche perché il servizio Azure Kubernetes tenta sempre il pull anonimo indipendentemente dal fatto che il registro contenitori abbia abilitato l'accesso pull anonimo.

Causa 3: Errore 403 Accesso negato

Impossibile eseguire il pull dell'immagine "<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 anonymous token: unexpected status: 403 Forbidden

Soluzione 1: Assicurarsi che il collegamento alla rete virtuale del servizio Azure Kubernetes sia impostato nella zona di DNS privato del registro contenitori

Se l'interfaccia di rete dell'endpoint privato del registro contenitori e il 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, questo collegamento è denominato "privatelink.azurecr.io". Se il collegamento alla rete virtuale non si trova nella zona DNS privato del registro contenitori, aggiungerlo usando uno dei modi seguenti:

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

  Note

  È 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 del servizio Azure Kubernetes all'intervallo di indirizzi IP consentito del registro contenitori

Se il cluster del servizio Azure Kubernetes si connette pubblicamente al registro contenitori (NOT 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 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 pubblico l'accesso alla rete pubblica è impostato su Reti selezionate o Disabilitato.

2. Ottenere l'indirizzo IP pubblico 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.

   • Esegui questo comando:

     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 usando uno dei modi seguenti:

   • Eseguire il az acr network-rule add comando come segue:

     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 del servizio Azure Kubernetes all'intervallo di indirizzi e quindi selezionare Salva. Per altre informazioni, vedere Accesso dalla rete pubblica selezionata - Portale.

     Note

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

     

Causa 4: "Errore di timeout i/o"

Impossibile eseguire il pull dell'immagine "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.failed to resolve reference "acrname.failed to pull image "<acrname.azurecr.io/ repository:tag": failed to resolve reference "acrname.failed to pull image "acrname.azurecr.io/ repository:tag": failed to resolve reference "<acrname.failed> to pull image "acrname.azurecr.io/ repository:tag": failed to pull image "acrname.azurecr.io/ repository:tag>>": failed to pull image "<acrname.azurecr.io/>>< re azurecr.io/< repository:tag>": failed to do request: Head "https://< acrname.azurecr.io/v2/>< repository>/manifests/v1": dial tcp <acrprivateipaddress>:443: i/o timeout

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

Se l'interfaccia di rete dell'endpoint privato del registro contenitori e il 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 nella portale di Azure selezionando i> peering reti 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 altre operazioni di 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 del servizio Azure Kubernetes 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 il cluster del servizio Azure Kubernetes si trovano in reti virtuali diverse, oltre al peering di rete virtuale, è possibile usare Firewall di Azure Servizio 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 eseguire un contenitore Linux in un nodo Windows o 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 = failed to pull and unpack image "<acrname.azurecr.io/<> repository:tag>": no match for platform in manifest: not found,
]

Questo errore può verificarsi per un'immagine estratta da qualsiasi origine, purché l'immagine non sia compatibile con il sistema operativo host. L'errore non è limitato alle immagini 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 di nodo corretto. La tabella seguente illustra come impostare l'impostazione kubernetes.io/os in YAML:

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 il materiale sussidiario per la risoluzione dei problemi in questo articolo non consente di risolvere il problema, ecco alcuni altri aspetti da considerare:

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

• 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.