Verify the connection to the container registry
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:
- Configure client firewall access.
- Configure public access to the registry.
- Configure virtual network access.
- Configure access for services.
Troubleshoot sign-in problems
If you encounter authentication and authorization problems when you sign in to an Azure container registry, consider the following solutions:
- Check the Docker configuration in your environment.
- Specify the correct registry name.
- Verify the credentials to access the registry.
- Configure the public access to the registry.
- Troubleshoot registry sign-in problems.
- Check that credentials aren't expired.
Troubleshoot performance problems
If you encounter performance issues with an Azure container registry, consider the following solutions:
- Enable the artifact cache.
- Check the network connection speed.
- Inspect client hardware that might affect image layer compression or extraction speed.
- Review configured limits in the registry service tier or environment.
- Configure the geo-replicated registry for optimal performance with replicas in nearby regions.
- Optimize DNS configuration for pulling from a geographically distant registry replica.
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:
- Paolo Salvatori | Principal Customer Engineer
- Francis Simy Nazareth | Senior Technical Specialist
To see non-public LinkedIn profiles, sign in to LinkedIn.