Error al extraer imágenes de Azure Container Registry a Azure Kubernetes Service clúster

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 a 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 a 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 a 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 los siguientes inicios rápidos:

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

• Si necesita una Azure Container Registry (ACR), cree una mediante la CLI de Azure o el 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 y solución de problemas inicial

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 en 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 recibe errores relacionados con Helm o notario, no significa que un problema afecte a Container Registry o AKS. Solo indica 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 Notario, 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 ayudan 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 de 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 Unauthorized":

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 ha creado la asignación de roles de AcrPull para la identidad.

La integración entre AKS y Container Registry crea una asignación de roles de AcrPull en el nivel de registro de contenedor para la identidad de 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 de 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 el Azure Portal, seleccione Azure Container Registry>Acceso control (IAM)>Asignaciones de roles. Para obtener más información, consulte Enumeración de asignaciones de roles de Azure mediante el 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, creela configurando 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 sp credential list --id "$SP_ID" --query "[].endDate" -o 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 sigue haciendo referencia a la entidad de servicio anterior. 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 de 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 LA VMSS de AKS, los nodos de AKS no pueden extraer imágenes del ACR.

Para buscar la identidad de 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 LA VMSS de AKS abriendo el VMSS desde el grupo de recursos del nodo y seleccionando Usuario de identidad>asignado en el Azure Portal o ejecutando el siguiente comando:

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

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

Nota:

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

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

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

Solución 5: Asegúrese de que la entidad de servicio es correcta y que el secreto es 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 es correcta y que el secreto sigue 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. Compruebe la fecha de expiración ejecutando el siguiente comando az ad sp credential list . 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 tiene 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 ese 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 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 el 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 encontrada

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 es 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, también puede producirse el error 401 Unauthorized porque AKS siempre intenta extraer de forma anónima independientemente de si el registro de contenedor ha habilitado el acceso de extracción anónimo.

Causa 3: 403 Error prohibido

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 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 redes virtuales diferentes, 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 maneras siguientes:

• En el Azure Portal, seleccione la zona DNS privada "privatelink.azurecr.io", seleccione Vínculos> de red virtualAgregar 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 al intervalo de direcciones IP permitido 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 redes seleccionadas, agregue la dirección IP pública de AKS Load Balancer al intervalo de direcciones IP permitidas del registro de contenedor:

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

   En el 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 del Load Balancer de AKS mediante una de las siguientes maneras:

   • En el 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 Load Balancer 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. Permitir el acceso desde la dirección IP pública de AKS Load Balancer mediante una de las siguientes maneras:

   • Ejecute az acr network-rule add el comando como se indica a continuación:

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

     Para obtener más información, vea Agregar regla de red al Registro.

   • En el 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 de AKS Load Balancer 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 443

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 do request: Head "https://< acrname.azurecr.io/v2/<> repository>/manifests/v1": dial tcp <acrprivateipaddress>:443: i/o timeout

Nota:

El error "Tiempo de espera 443" 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 redes virtuales

Si la interfaz de red del punto de conexión privado del registro de contenedor y el clúster de AKS están en redes virtuales diferentes, 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 el Azure Portal seleccionandoemparejamientos> de redes virtualesen 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 se usa el emparejamiento de red virtual para ambas redes virtuales, asegúrese de que el estado es "Conectado". Si el estado es 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 del 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 obtener 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 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 se encuentran en redes virtuales diferentes, además del emparejamiento de redes virtuales, puede usar Azure Firewall Service 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 (sistema operativo de nodo) no es compatible con la imagen que se usa para el pod o contenedor. Por ejemplo, si programa un pod para ejecutar un contenedor 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 = no se pudo extraer y desempaquetar la imagen "<acrname.azurecr.io/>< repository:tag>": no se encontró ninguna coincidencia para la plataforma en el manifiesto: no se encontró,
]

Este error puede producirse para una imagen extraída de cualquier origen, siempre que la imagen no sea compatible con el sistema operativo host. El error no se limita a las imágenes extraídas 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 de Linux	"kubernetes.io/os": linux
Contenedor de 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, estos son algunos otros aspectos a tener en cuenta:

• Compruebe los grupos de seguridad de red y las tablas de rutas asociadas a 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 del firewall y del 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.