AKS绑定ACR后执行Helm安装拉取镜像出现401未授权错误

算力阿峰

2026-9-26

AKS绑定ACR后拉取镜像返回401未授权故障排查方案

第一步：验证AKS与ACR的绑定是否真实生效
执行官方校验命令，直接检测AKS是否有权限访问ACR：
```
az aks check-acr -n <你的AKS名称> -g <AKS所在资源组名称> --acr <你的ACR名称>
```
如果命令返回错误，说明之前的az aks update --attach-acr并未实际完成权限配置。
第二步：检查ACR访问限制配置
如果你的ACR开启了IP白名单、私有端点等访问控制规则，需要确认已将AKS集群的出站公网IP、集群所在VNET网段加入ACR的允许访问列表，网络层面的拦截也会触发401类授权报错。
第三步：校验Helm命令中ACR地址变量的正确性
检查你执行命令时的$ACR_URL环境变量取值，是否为ACR的登录服务器地址（格式为xxx.azurecr.io，不可带有https://、http://前缀，也不可额外加后缀路径），格式错误会导致镜像拉取请求无法正确匹配ACR的授权规则。
第四步：手动补配ACR拉取权限
如果上述校验均未发现问题，可手动为AKS的kubelet托管身份授予ACR拉取权限，规避自动绑定未生效的问题：
1. 获取AKS kubelet身份的客户端ID：
```
az aks show -n <你的AKS名称> -g <AKS所在资源组> --query identityProfile.kubeletidentity.clientId -o tsv
```
1. 获取ACR的资源ID：
```
az acr show -n <你的ACR名称> -g <ACR所在资源组> --query id -o tsv
```
1. 为kubelet身份分配AcrPull角色：
```
az role assignment create --assignee <上一步获取的kubelet客户端ID> --role "AcrPull" --scope <上一步获取的ACR资源ID>
```
权限配置生效需要1-2分钟，完成后重新执行Helm安装命令即可。
临时验证方法
你可以通过部署测试Pod快速验证权限是否正常：
```
kubectl run test-acr --image=<你的ACR登录地址>/<镜像名>:<标签> --restart=Never
```
执行kubectl describe pod test-acr查看事件，确认镜像是否可以正常拉取。