No se pueden extraer imágenes de Azure Container Registry al clúster de Azure Kubernetes Service

Nota:

¿Le resultó útil este artículo? Su opinión es importante para nosotros. Use el botón Comentarios de esta página para indicarnos lo bien que ha funcionado este artículo o cómo podemos mejorarlo.

Cuando se usa Microsoft Azure Container Registry junto con Azure Kubernetes Service (AKS), se debe establecer un mecanismo de autenticación. Puede configurar la integración de AKS en Container Registry mediante algunos comandos sencillos de la CLI de Azure o Azure PowerShell. Esta integración asigna el rol AcrPull para la identidad de kubelet asociada al clúster de AKS para extraer imágenes de un registro de contenedor.

En algunos casos, se produce un error al intentar extraer imágenes de un registro de contenedor en un clúster de AKS. En este artículo se proporcionan instrucciones para solucionar los errores más comunes que se producen al extraer imágenes de un registro de contenedor en un clúster de AKS.

Antes de empezar

En este artículo se supone que tiene un clúster de AKS existente y un registro de contenedor existente. Consulte las siguientes guías de inicio rápido:

• Si necesita un clúster de AKS, implemente uno mediante la CLI de Azure o Azure Portal.

• Si necesita una instancia de Azure Container Registry (ACR), cree una mediante la CLI de Azure o Azure Portal.

También necesita la versión 2.0.59 de la CLI de Azure o una versión posterior para instalarla y configurarla. Ejecute az version para determinar la versión. Si tiene que instalar o actualizar, consulte Instalación de la CLI de Azure.

Síntomas e solución de problemas iniciales

El estado del pod de Kubernetes es ImagePullBackOff o ErrImagePull. Para obtener información detallada sobre los errores, ejecute el siguiente comando y compruebe Eventos de la salida.

kubectl describe pod <podname> -n <namespace>

Se recomienda empezar a solucionar problemas comprobando el estado del registro de contenedor y comprobando si el registro de contenedor es accesible desde el clúster de AKS.

Para comprobar el estado del registro de contenedor, ejecute el siguiente comando:

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

Si se detecta un problema, proporciona un código de error y una descripción. Para obtener más información sobre los errores y las posibles soluciones, consulte Referencia de errores de comprobación de estado.

Nota:

Si obtiene errores relacionados con Helm o relacionados con notarios, no significa que un problema afecte a Container Registry o AKS. Indica solo que Helm o Notary no están instalados, o que la CLI de Azure no es compatible con la versión instalada actual de Helm o Notary, etc.

Para validar si el registro de contenedor es accesible desde el clúster de AKS, ejecute el siguiente comando az aks check-acr :

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

Las secciones siguientes le ayudarán a solucionar los errores más comunes que se muestran en Eventos en la salida del kubectl describe pod comando.

Causa 1: 401 Error no autorizado

Un clúster de AKS requiere una identidad. Esta identidad puede ser una identidad administrada o una entidad de servicio. Si el clúster de AKS usa una identidad administrada, la identidad kubelet se usa para autenticarse con ACR. Si el clúster de AKS usa como identidad una entidad de servicio, la propia entidad de servicio se usa para autenticarse con ACR. Independientemente de cuál sea la identidad, es necesaria la autorización adecuada que se usa para extraer una imagen de un registro de contenedor. De lo contrario, puede obtener el siguiente error "401 No autorizado":

No se pudo extraer la imagen "<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 oauth token: unexpected status: 401 Unauthorized

Varias soluciones pueden ayudarle a resolver este error, sujeto a las siguientes restricciones:

• Las soluciones 2, 3 y 5 solo se aplican a los clústeres de AKS que usan una entidad de servicio.

• Las soluciones 1, 2, 3 y 4 son aplicables al método de Azure para crear la asignación de roles en el nivel de Container Registry para la identidad de AKS.

• Las soluciones 5 y 6 son aplicables al método de Kubernetes para extraer un secreto de Kubernetes.

Solución 1: Asegúrese de que se crea la asignación de roles AcrPull para la identidad

La integración entre AKS y Container Registry crea una asignación de roles AcrPull en el nivel de registro de contenedor para la identidad kubelet del clúster de AKS. Asegúrese de que se crea la asignación de roles.

Para comprobar si se crea la asignación de roles AcrPull, use uno de los métodos siguientes:

• Ejecute el siguiente comando:

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

• Para proteger Azure Portal, seleccione Azure Container Registry>Access control (IAM)>Asignaciones de roles. Para más información, consulte Enumeración de asignaciones de roles de Azure mediante Azure Portal.

Además del rol AcrPull, algunos roles integrados y roles personalizados también pueden contener la acción "Microsoft.ContainerRegistry/registries/pull/read". Compruebe esos roles si tiene alguno de ellos.

Si no se crea la asignación de roles de AcrPull, créela mediante la configuración de la integración de Container Registry para el clúster de AKS con el siguiente comando:

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

Solución 2: Asegúrese de que la entidad de servicio no ha expirado

Asegúrese de que el secreto de la entidad de servicio asociada al clúster de AKS no ha expirado. Para comprobar la fecha de expiración de la entidad de servicio, ejecute los siguientes comandos:

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

Para obtener más información, consulte Comprobación de la fecha de expiración de la entidad de servicio.

Si el secreto ha expirado, actualice las credenciales del clúster de AKS.

Solución 3: Asegúrese de que el rol AcrPull está asignado a la entidad de servicio correcta

En algunos casos, la asignación de roles del registro de contenedor todavía hace referencia a la entidad de servicio antigua. Por ejemplo, cuando la entidad de servicio del clúster de AKS se reemplaza por una nueva. Para asegurarse de que la asignación de roles del registro de contenedor hace referencia a la entidad de servicio correcta, siga estos pasos:

1. Para comprobar la entidad de servicio que usa el clúster de AKS, ejecute el siguiente comando:

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

2. Para comprobar la entidad de servicio a la que hace referencia la asignación de roles del registro de contenedor, ejecute el siguiente comando:

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

3. Compare las dos entidades de servicio. Si no coinciden, vuelva a integrar el clúster de AKS con el registro de contenedor.

Solución 4: Asegúrese de que se hace referencia a la identidad de kubelet en VMSS de AKS

Cuando se usa una identidad administrada para la autenticación con ACR, la identidad administrada se conoce como identidad kubelet. De forma predeterminada, la identidad de kubelet se asigna en el nivel de VMSS de AKS. Si la identidad de kubelet se quita de VMSS de AKS, los nodos de AKS no pueden extraer imágenes de ACR.

Para buscar la identidad kubelet del clúster de AKS, ejecute el siguiente comando:

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

A continuación, puede enumerar las identidades de VMSS de AKS abriendo VMSS desde el grupo de recursos del nodo y seleccionando Identity User assigned in the Azure Portal (Usuario de identidad>asignado en Azure Portal) o ejecutando el siguiente comando:

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

Si la identidad kubelet del clúster de AKS no está asignada a VMSS de AKS, asígnela de nuevo.

Nota:

No se admite la modificación de VMSS de AKS mediante las API de IaaS o desde Azure Portal, y ninguna operación de AKS puede quitar la identidad de kubelet de VMSS de AKS. Esto significa que algo inesperado lo quitó, por ejemplo, una eliminación manual realizada por un miembro del equipo. Para evitar esta eliminación o modificación, puede considerar la posibilidad de usar la característica NRGLockdown.

Dado que no se admiten modificaciones en VMSS de AKS, no se propagan en el nivel de AKS. Para reasignar la identidad de kubelet a VMSS de AKS, se necesita una operación de conciliación. Para ello, ejecute el siguiente comando:

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

Solución 5: Asegúrese de que la entidad de servicio sea correcta y que el secreto sea válido

Si extrae una imagen mediante un secreto de extracción de imágenes y ese secreto de Kubernetes se creó mediante los valores de una entidad de servicio, asegúrese de que la entidad de servicio asociada sea correcta y que el secreto siga siendo válido. Siga estos pasos:

1. Ejecute el siguiente comando kubectl get y base64 para ver los valores del secreto de Kubernetes:

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

2. Ejecute el siguiente comando az ad sp credential list para comprobar la fecha de expiración. El nombre de usuario es el valor de la entidad de servicio.

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

3. Si es necesario, restablezca el secreto de esa entidad de servicio ejecutando el siguiente comando az ad sp credential reset :

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

4. Actualice o vuelva a crear el secreto de Kubernetes en consecuencia.

Solución 6: Asegúrese de que el secreto de Kubernetes tenga los valores correctos de la cuenta de administrador del registro de contenedor.

Si extrae una imagen mediante un secreto de extracción de imágenes y que el secreto de Kubernetes se creó mediante valores de la cuenta de administrador del registro de contenedor, asegúrese de que los valores del secreto de Kubernetes sean los mismos que los valores de la cuenta de administrador del registro de contenedor. Siga estos pasos:

1. Ejecute el siguiente comando kubectl get y base64 para ver los valores del secreto de Kubernetes:

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

2. En Azure Portal, busque y seleccione Registros de contenedor.

3. En la lista de registros de contenedor, seleccione el registro de contenedor.

4. En el panel de navegación del registro de contenedor, seleccione Claves de acceso.

5. En la página Claves de acceso del registro de contenedor, compare los valores del registro de contenedor con los valores del secreto de Kubernetes.

6. Si los valores no coinciden, actualice o vuelva a crear el secreto de Kubernetes en consecuencia.

Nota:

Si se produjo una operación Regenerar contraseña, se mostrará una operación denominada "Regenerar credenciales de inicio de sesión de Container Registry" en la página Registro de actividad del registro de contenedor. El registro de actividad tiene un período de retención de 90 días.

Causa 2: Error de imagen no encontrado

No se pudo extraer la imagen "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<<

Solución: asegúrese de que el nombre de la imagen sea correcto

Si ve este error, asegúrese de que el nombre de la imagen es totalmente correcto. Debe comprobar el nombre del Registro, el servidor de inicio de sesión del Registro, el nombre del repositorio y la etiqueta . Un error común es que el servidor de inicio de sesión se especifica como "azureacr.io" en lugar de "azurecr.io".

Si el nombre de la imagen no es totalmente correcto, el error 401 No autorizado también puede producirse porque AKS siempre intenta extraer anónimo independientemente de si el registro de contenedor ha habilitado el acceso de extracción anónimo.

Causa 3: Error 403 Prohibido

No se pudo extraer la imagen "<acrname.azurecr.io/ repository:tag>": error 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

Solución 1: Asegúrese de que el vínculo de red virtual de AKS esté establecido en la zona de DNS privado del registro de contenedor.

Si la interfaz de red del punto de conexión privado del registro de contenedor y el clúster de AKS están en diferentes redes virtuales, asegúrese de que el vínculo de red virtual de la red virtual del clúster de AKS esté establecido en la zona DNS privado del registro de contenedor. (Ese vínculo se denomina "privatelink.azurecr.io" de forma predeterminada). Si el vínculo de red virtual no está en la zona DNS privado del registro de contenedor, agréguelo mediante una de las siguientes maneras:

• En Azure Portal, seleccione la zona DNS privada "privatelink.azurecr.io", seleccione Vínculos>de red virtual Agregar en el panel Configuración y, a continuación, seleccione un nombre y la red virtual del clúster de AKS. Seleccione Aceptar.

  Nota:

  Es opcional seleccionar la característica "Habilitar registro automático".

• Cree un vínculo de red virtual a la zona de DNS privado especificada mediante la CLI de Azure.

Solución 2: Adición de la dirección IP pública de AKS Load Balancer a intervalo de direcciones IP permitidos del registro de contenedor

Si el clúster de AKS se conecta públicamente al registro de contenedor (NO a través de un vínculo privado o un punto de conexión) y el acceso a la red pública del registro de contenedor está limitado a las redes seleccionadas, agregue la dirección IP pública de AKS Load Balancer al intervalo de direcciones IP permitido del registro de contenedor:

1. Compruebe que el acceso a la red pública está limitado a las redes seleccionadas.

   En Azure Portal, vaya al registro de contenedor. En Configuración, seleccione Redes. En la pestaña Acceso público, el acceso a la red pública se establece en Redes seleccionadas o Deshabilitado.

2. Obtenga la dirección IP pública de AKS Load Balancer mediante una de las maneras siguientes:

   • En Azure Portal, vaya al clúster de AKS. En Configuración, seleccione Propiedades, seleccione uno de los conjuntos de escalado de máquinas virtuales en el grupo de recursos de infraestructura y compruebe la dirección IP pública del equilibrador de carga de AKS.

   • Ejecute el siguiente comando:

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

3. Permita el acceso desde la dirección IP pública de AKS Load Balancer mediante una de las siguientes maneras:

   • Ejecute el az acr network-rule add comando de la manera siguiente:

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

     Para obtener más información, consulte Adición de una regla de red al Registro.

   • En Azure Portal, vaya al registro de contenedor. En Configuración, seleccione Redes. En la pestaña Acceso público, en Firewall, agregue la dirección IP pública del equilibrador de carga de AKS al intervalo de direcciones y, a continuación, seleccione Guardar. Para obtener más información, consulte Acceso desde la red pública seleccionada: portal.

     Nota:

     Si el acceso a la red pública está establecido en Deshabilitado, cambie primero a Redes seleccionadas .

     

Causa 4: "Error de tiempo de espera de e/s"

No se pudo extraer la imagen "<acrname.azurecr.io/< repository:tag>": error 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 do request: Head "https://< acrname.azurecr.io/v2/>< repository>/manifests/v1": dial tcp <acrprivateipaddress>:443: i/o timeout

Nota:

El error "Tiempo de espera de e/s" solo se produce cuando se conecta de forma privada a un registro de contenedor mediante Azure Private Link.

Solución 1: Asegúrese de que se usa el emparejamiento de red virtual

Si la interfaz de red del punto de conexión privado del registro de contenedor y el clúster de AKS están en diferentes redes virtuales, asegúrese de que se usa el emparejamiento de redes virtuales para ambas redes virtuales. Para comprobar el emparejamiento de redes virtuales, ejecute el comando az network vnet peering list --resource-group <MyResourceGroup> --vnet-name <MyVirtualNetwork> --output table de la CLI de Azure o en Azure Portal seleccionando los emparejamientos de>redes virtuales en el panel Configuración. Para obtener más información sobre cómo enumerar todos los emparejamientos de una red virtual especificada, consulte az network vnet peering list.

Si el emparejamiento de red virtual se usa para ambas redes virtuales, asegúrese de que el estado es "Conectado". Si el estado está Desconectado, elimine el emparejamiento de ambas redes virtuales y vuelva a crearlo. Si el estado es "Conectado", consulte la guía de solución de problemas: El estado de emparejamiento es "Conectado".

Para solucionar problemas adicionales, conéctese a uno de los nodos o pods de AKS y, a continuación, pruebe la conectividad con el registro de contenedor en el nivel TCP mediante la utilidad Telnet o Netcat. Compruebe la dirección IP con el nslookup <acrname>.azurecr.io comando y, a continuación, ejecute el telnet <ip-address-of-the-container-registry> 443 comando .

Para más información sobre cómo conectarse a nodos de AKS, consulte Conexión con SSH a nodos de clúster de Azure Kubernetes Service (AKS) para tareas de mantenimiento o solución de problemas.

Solución 2: Uso del servicio Azure Firewall

Si la interfaz de red del punto de conexión privado del registro de contenedor y el clúster de AKS están en diferentes redes virtuales, además del emparejamiento de redes virtuales, puede usar El servicio Azure Firewall para configurar una topología de red en estrella tipo hub-spoke en Azure. Al configurar la regla de firewall, debe usar reglas de red para permitir explícitamente la conexión saliente a las direcciones IP del punto de conexión privado del registro de contenedor.

Causa 5: No hay coincidencia para la plataforma en el manifiesto

El sistema operativo host (so de nodo) no es compatible con la imagen que se usa para el pod o el contenedor. Por ejemplo, si programa un pod para ejecutar un contenedor de Linux en un nodo de Windows o un contenedor de Windows en un nodo de Linux, se produce el siguiente error:

No se pudo extraer la imagen "<acrname.azurecr.io/>< repository:tag>":
[
  error rpc:
  code = NotFound
  desc = failed to pull and unpack image "<acrname.azurecr.io/<> repository:tag>": no match for platform in manifest: not found,
]

Este error puede producirse para una imagen que se extraiga de cualquier origen, siempre y cuando la imagen sea incompatible con el sistema operativo host. El error no se limita a las imágenes que se extraen del registro de contenedor.

Solución: configure el campo nodeSelector correctamente en el pod o la implementación.

Especifique el campo correcto nodeSelector en los valores de configuración del pod o la implementación. El valor correcto para la configuración de kubernetes.io/os este campo garantiza que el pod se programará en el tipo correcto de nodo. En la tabla siguiente se muestra cómo establecer la kubernetes.io/os configuración en YAML:

Tipo de contenedor	Configuración de YAML
Contenedor Linux	"kubernetes.io/os": linux
Contenedor Windows	"kubernetes.io/os": windows

Por ejemplo, el siguiente código YAML describe un pod que debe programarse en un nodo de 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

Más información

Si la guía de solución de problemas de este artículo no le ayuda a resolver el problema, estas son otras cosas que se deben tener en cuenta:

• Compruebe los grupos de seguridad de red y las tablas de rutas asociadas a las subredes, si tiene alguno de esos elementos.

• Si una aplicación virtual como un firewall controla el tráfico entre subredes, compruebe las reglas de acceso de firewall y firewall.

Aviso de declinación de responsabilidades sobre la información de terceros

Los productos de otros fabricantes que se mencionan en este artículo han sido creados por compañías independientes de Microsoft. Microsoft no ofrece ninguna garantía, ya sea implícita o de otro tipo, sobre la confiabilidad o el rendimiento de dichos productos.

Ponte en contacto con nosotros para obtener ayuda

Si tiene preguntas o necesita ayuda, cree una solicitud de soporte o busque consejo en la comunidad de Azure. También puede enviar comentarios sobre el producto con los comentarios de la comunidad de Azure.