训练时无法从Azure容器注册表拉取Docker镜像求助

问题场景 #

通过Azure CLI提交Azure ML作业，使用已上传至Azure容器注册表（ACR）的自定义Docker镜像，执行命令：

az ml job create -f test.yaml --resource-group DefaultResourceGroup-EUS2 --workspace-name test-airflow

触发错误：

Failed to pull Docker image prateek2001.azurecr.io/test/dataprep:latest. This error may occur because the compute could not authenticate with the Docker registry to pull the image. If using ACR please ensure the ACR has Admin user enabled or a Managed Identity with AcrPull access to the ACR is assigned to the compute. If the ACR Admin user's password was changed recently it may be necessary to synchronize the workspace keys.

已完成以下操作但问题仍存在：

• 启用ACR管理员用户
• 为计算资源分配托管标识并赋予ACR的AcrPull权限

排查与解决方案 #

1. 验证托管标识权限的有效性 #

• 确认标识类型与配置：如果使用用户分配托管标识，需确保Azure ML计算资源的配置中明确选择了该标识（而非默认的系统分配标识）；系统分配标识需确认计算资源已启用该功能。
• 检查IAM权限的直接分配：确保AcrPull权限是直接分配给计算的托管标识，而非通过资源组继承（继承可能存在延迟或配置遗漏）。可通过以下CLI命令验证：

  # 替换为你的托管标识对象ID和ACR资源ID
  az role assignment list --assignee <managed-identity-object-id> --scope <acr-resource-id> --role AcrPull
  

  若无返回结果，需重新添加权限。

2. 检查Azure ML工作区与ACR的关联 #

• 确认ACR已关联到工作区：运行命令查看当前工作区绑定的容器注册表：

  az ml workspace show --resource-group DefaultResourceGroup-EUS2 --name test-airflow --query container_registry
  

  如果返回的ACR资源ID与目标ACR不符，执行以下命令关联：

  az ml workspace update --resource-group DefaultResourceGroup-EUS2 --name test-airflow --container-registry <target-acr-resource-id>
  

• 同步工作区密钥：若ACR管理员密码近期修改过，执行同步命令刷新工作区的凭据：

  az ml workspace sync-keys --resource-group DefaultResourceGroup-EUS2 --name test-airflow
  

3. 确认镜像的可用性与可访问性 #

• 本地测试镜像拉取：使用ACR管理员账号登录并尝试拉取镜像，验证镜像存在且标签正确：

  az acr login --name prateek2001
  docker pull prateek2001.azurecr.io/test/dataprep:latest
  

  若拉取失败，需重新推送正确的镜像至ACR。
• 检查ACR网络配置：如果ACR启用了专用端点或防火墙，需确保Azure ML计算所在的虚拟网络已被加入ACR的允许列表；测试阶段可临时设置ACR为允许所有网络访问，确认是否是网络限制导致的问题。

4. 核对作业YAML的配置细节 #

• 确认镜像地址无拼写错误：检查镜像路径、标签（如latest）是否与ACR中的完全一致。
• 配置托管标识拉取规则：若使用托管标识拉取镜像，需在作业YAML中明确指定标识信息：

  identity:
    type: managed
    resource_id: <your-managed-identity-resource-id>
  

  系统分配标识则设置type: system_assigned。

5. 重置计算资源状态 #

• 重启计算实例/集群：权限配置变更可能需要重启计算资源才能生效，尤其是系统分配托管标识的场景。
• 检查虚拟网络出站规则：若计算在虚拟网络中，确认NSG出站规则未阻止访问ACR的流量（Azure服务间默认允许访问，但自定义规则可能存在限制）。

内容的提问来源于stack exchange，提问作者Prateek Singh