GitLab CI自动化部署异常：K8s无法拉取ACR镜像

我来帮你排查这个GitLab CI显示成功但K8s拉取ACR镜像失败的问题，这种衔接类的故障很常见，咱们一步步拆解可能的原因和解决办法：

1. AKS与ACR的权限关联没配置到位 #

这是最常见的原因——AKS集群默认没有拉取ACR镜像的权限，哪怕你在GitLab里推送镜像成功了，K8s节点还是没权限去拉。

• 先验证关联状态：在本地或者GitLab CI的部署步骤里执行这条命令

  az aks check-acr --name <你的AKS集群名> --resource-group <资源组名> --acr <你的ACR名称>
  

• 如果显示未关联，立刻用这条命令绑定：

  az aks update --name <你的AKS集群名> --resource-group <资源组名> --attach-acr <你的ACR名称>
  

• 要是用的是AKS托管身份，记得去ACR的**访问控制(IAM)**里，给AKS的AksAgentPool系统身份分配AcrPull角色，确保节点有权限拉取镜像。

2. Helm Chart里的镜像配置出错 #

GitLab推送的镜像信息和Helm部署时用的不匹配，比如标签写错、ACR地址少了后缀，都会导致K8s找不到镜像。

• 先对比GitLab CI里的推送命令（比如docker push myacr.azurecr.io/myapp:v1.0.0）和Helm values.yaml里的配置：

  image:
    repository: myacr.azurecr.io/myapp  # 要和推送的完全一致
    tag: v1.0.0  # 标签不能错
  

• 去K8s里看Pod的详细错误：执行kubectl describe pod <出问题的Pod名>，看Events里的具体提示——比如是不是image not found或者invalid reference format，一眼就能定位配置错误。

3. GitLab CI部署阶段的认证有漏洞 #

GitLab CI显示部署成功，不代表它真的有权限正确配置AKS，或者Helm部署时没传递正确的镜像拉取凭证。

• 检查GitLab CI里的部署步骤：是不是用az aks get-credentials正确获取了kubeconfig？执行这条命令的服务主体有没有AKS的管理员权限？
• 如果没用到AKS-ACR自动关联，而是手动用imagePullSecrets：
  1. 确认K8s里已经创建了对应ACR的secret：kubectl get secrets
  2. 检查Helm Chart里有没有指定这个secret：

     imagePullSecrets:
       - name: acr-pull-secret  # 要和你创建的secret名称一致
     

4. 镜像推送后的同步延迟 #

GitLab刚推完镜像就立刻执行Helm部署，ACR可能还没完成镜像的同步（尤其是跨区域的ACR），这时候K8s去拉就会失败，但GitLab因为部署命令执行完了就标记成功。

• 解决办法是在部署前加个验证步骤，等镜像在ACR里存在了再继续：

  # 循环检查镜像标签是否存在，直到找到再退出
  until az acr repository show-tags --name <你的ACR名称> --repository <镜像名> --query "[?@ == '<你的镜像标签>']" --output tsv; do
    echo "等待镜像同步..."
    sleep 10
  done
  

• 嫌麻烦的话也可以加个sleep 30，给ACR一点缓冲时间。

最后提醒下：一定要去K8s里看Pod的事件日志，这是定位镜像拉取问题最直接的方式，比光看GitLab CI的成功提示有用多了。

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