Edit

Deploy CanIPull to an Azure Kubernetes Service (AKS) cluster

CanIPull is a diagnostic tool for Azure Kubernetes Service (AKS). It checks whether a cluster node can resolve and authenticate to Azure Container Registry (ACR). To perform the check, CanIPull reads the cluster identity configuration from the selected node and validates that the identity can exchange a token with ACR. It doesn't pull an image or validate access to a specific repository.

This article shows you how to run CanIPull by using Azure Copilot or a Kubernetes manifest. CanIPull v0.1.0 runs on one AMD64 Linux node at a time. Repeat the check on other supported nodes to compare their connectivity or configuration.

Prerequisites

Before you begin, you need:

  • An existing AKS cluster with at least one AMD64 Linux node.
  • An existing ACR instance that you want to test.

To deploy CanIPull with Azure Copilot, you also need access to Azure Copilot in the Azure portal.

To deploy CanIPull manually, you also need:

  • Azure CLI installed.
  • An authenticated Azure CLI session with permissions to get user credentials for the AKS cluster and read the ACR instance.
  • kubectl configured to connect to your AKS cluster.
  • Kubernetes permissions to list nodes at cluster scope; create, get, list, watch, and delete pods in the default namespace; and get pod logs in the default namespace.

Deploy CanIPull with Azure Copilot

Azure Copilot can select the AKS cluster, AMD64 Linux node, and ACR instance and then deploy CanIPull for you.

  1. In the Azure portal, open Copilot.

  2. Enter one of the following prompts:

    • Help me deploy CanIPull to my AKS cluster.
    • Do I have access to a specific Azure Container Registry from my AKS cluster?
    • Help me test if ACR is attached to my AKS cluster.

  3. Select the AKS cluster and the AMD64 Linux node where you want CanIPull to run.

  4. Select the ACR instance that you want to test.

  5. Review the selections, and then confirm the deployment.

  6. After the deployment completes, follow the prompt to open the Run command pane.

  7. Review the CanIPull logs for DNS, cluster identity, and ACR token exchange results.

For more information about this experience, see Deploy AKS CanIPull and troubleshoot image pull issues.

Deploy CanIPull manually

Use a one-shot Kubernetes pod when you want to choose the target node and inspect the CanIPull logs directly with kubectl.

Important

The manifest mounts /etc/kubernetes/azure.json from the selected node. This file contains sensitive cluster identity configuration. Deploy the pod only if you're a trusted cluster administrator. Don't increase the CanIPull verbosity because higher levels can print access tokens. Delete the pod as soon as you finish the test.

Connect to the cluster and select a node

  1. Set variables for the AKS cluster and ACR instance.

    RESOURCE_GROUP=<resource-group>
CLUSTER_NAME=<aks-cluster-name>
ACR_NAME=<acr-name>

  2. Get the cluster credentials.

    az aks get-credentials \
  --resource-group $RESOURCE_GROUP \
  --name $CLUSTER_NAME

  3. Get the ACR login server. CanIPull expects the fully qualified login server, such as myregistry.azurecr.io, rather than the ACR resource name.

    ACR_LOGIN_SERVER=$(az acr show \
  --name $ACR_NAME \
  --query loginServer \
  --output tsv)

echo $ACR_LOGIN_SERVER

  4. List the AMD64 Linux nodes and choose the node where you want to run the diagnostic check. CanIPull v0.1.0 supports only AMD64 nodes.

    kubectl get nodes \
  --selector kubernetes.io/os=linux,kubernetes.io/arch=amd64 \
  --output wide

Create the CanIPull pod

  1. Create a file named canipull.yaml with the following manifest. Replace <target-linux-node> and <acr-login-server> with the node name and ACR login server from the previous section.

    apiVersion: v1
kind: Pod
metadata:
  name: canipull
  namespace: default
  labels:
    app: canipull
spec:
  automountServiceAccountToken: false
  nodeName: <target-linux-node>
  restartPolicy: Never
  containers:
    - name: canipull
      image: mcr.microsoft.com/aks/canipull:v0.1.0
      imagePullPolicy: IfNotPresent
      args:
        - <acr-login-server>
      securityContext:
        allowPrivilegeEscalation: false
        capabilities:
          drop:
            - ALL
        readOnlyRootFilesystem: true
      volumeMounts:
        - name: azure-config
          mountPath: /etc/kubernetes/azure.json
          readOnly: true
  volumes:
    - name: azure-config
      hostPath:
        path: /etc/kubernetes/azure.json
        type: File

  2. Create the pod.

    kubectl apply --filename canipull.yaml

  3. Wait for the pod to finish.

    kubectl get pod canipull --watch

    Press Ctrl+C when the pod status changes to Completed or Error.

Review the CanIPull results

View the diagnostic output.

kubectl logs canipull

A successful test includes the following results:

  • The ACR authentication server resolves through DNS.
  • CanIPull reads the Azure configuration from the node.
  • The cluster's kubelet identity or service principal can authenticate.
  • ACR accepts the initial token exchange.

The final success message resembles the following output:

Your cluster can pull images from <acr-login-server>!

Despite the wording of the CanIPull success message, the test doesn't pull an image or validate access to a specific repository, image manifest, or image layers. To verify an end-to-end image pull, deploy a workload that references an image in the target repository.

If the test fails, review the log line marked FAILED. Common causes include:

  • The ACR authentication server doesn't resolve from the selected node.
  • The selected node doesn't contain /etc/kubernetes/azure.json.
  • The cluster identity credentials aren't valid.
  • ACR rejects the token exchange for the kubelet identity or service principal.

If the token exchange fails because the identity isn't authorized to access ACR, see Authenticate with ACR from AKS.

Clean up resources

Delete the CanIPull pod and remove its access to the node configuration.

kubectl delete pod canipull

Related content

  • Last updated on