Edit

Verify the connection to the container registry

  • Article

This article is part of a series. Start with the overview.

To successfully deploy containerized applications in your Azure Kubernetes Service (AKS) cluster, it's essential to verify the connectivity between the cluster and the container registry. This step guarantees that your worker nodes have the necessary permissions to pull the required container images from the registry.

Identify symptoms

When the kubelet that runs on an agent node creates the containers for a pod, one or more container might end up in the waiting state because of the ImagePullBackOff error. ImagePullBackoff is a common error message in Kubernetes that indicates a failure to pull the required container image from a public or private registry. Various factors can cause this error, including network connectivity problems, an incorrect image name or tag, insufficient permissions, or missing credentials.

The BackOff part of the status signifies that Kubernetes continuously attempts to pull the image with an increasing delay between each subsequent attempt. The delay gradually increases until it reaches a predetermined limit, which is typically set to 300 seconds (5 minutes) in Kubernetes.

It's important to double-check the registry and image name for accuracy. Additionally, ensure that your AKS cluster has the necessary permissions to pull images from the appropriate container registry.

Role assignments

When you attach a container registry to an existing AKS cluster, the AcrPull role is automatically assigned over the registry to the Microsoft Entra managed identity that's associated with the agent pools in your AKS cluster. For more information, see Authenticate with Container Registry from AKS.

Run the following command to retrieve the kubelet managed identity of a Kubernetes cluster and its current role assignments:

# Get the kubelet managed identity.
ASSIGNEE=$(az aks show -g $RESOURCE_GROUP -n $NAME --query identityProfile.kubeletidentity.clientId -o tsv)
az role assignment list --assignee $ASSIGNEE --all -o table

Run the following command to assign the AcrPull role to the kubelet managed identity:

AZURE_CONTAINER_REGISTRY_ID=$(az acr show --name <container-registry-name> --query id --output tsv)
az role assignment create --assignee $ASSIGNEE --scope $AZURE_CONTAINER_REGISTRY_ID --role acrpull

Troubleshoot Container Registry problems

The following sections provide guides that you can refer to if you encounter networking, sign-in, or performance problems with an Azure container registry.

Troubleshoot networking problems

If you encounter problems that are related to accessing an Azure container registry in a virtual network or behind a firewall or proxy server, consider the following solutions:

Troubleshoot sign-in problems

If you encounter authentication and authorization problems when you sign in to an Azure container registry, consider the following solutions:

Troubleshoot performance problems

If you encounter performance issues with an Azure container registry, consider the following solutions:

These guides can help you ensure seamless image retrieval for your AKS cluster and ensure smooth operation of your workloads.

Integrate a third-party container registry

When you use a third-party container registry, you need to create the appropriate ImagePullSecret credentials for the registry so your AKS cluster can securely access the container images. For more information, see Create an image pull secret. Ensure that you set up the correct permissions and credentials so you can verify the connection to the container registry and enable your AKS cluster to successfully pull the required container images during deployments. This best practice helps ensure smooth and reliable execution of your containerized workloads in Kubernetes.

Contributors

This article is maintained by Microsoft. It was originally written by the following contributors.

Principal authors:

To see non-public LinkedIn profiles, sign in to LinkedIn.

Next steps