GitLab Runner K8s执行器拉取镜像报Back-off pulling image错误如何解决

报错核心定位 #

该错误是GitLab Runner调用Kubernetes执行器时，无法拉取指定的CI运行镜像，导致Pod初始化失败任务终止。

可能的原因 #

• 镜像名称/标签拼写错误：你使用的镜像标签为3.6-strech，Debian官方版本的正确拼写为stretch，拼写错误是优先级最高的排查点。
• 对应镜像仓库为私有仓库，当前Kubernetes的sai命名空间未配置镜像拉取凭证，无权限拉取镜像。
• 指定的镜像标签确实不存在于私有仓库中，可能已被删除或废弃。
• Kubernetes集群节点与私有镜像仓库网络不通，无法连接到仓库拉取镜像。

处理方案 #

1. 优先排查镜像基础信息 #

先登录你的私有镜像仓库后台，核对aie-docker-dev-mydockerrepo/python:3.6-strech是否真实存在，确认镜像名称、标签拼写是否正确。如果是拼写错误，修正.gitlab-ci.yml中指定的镜像名称即可解决问题。

2. 配置ImagePullSecret（私有仓库无权限场景） #

你可以根据需求选择全局配置或单任务配置两种方式：

方式一：GitLab Runner全局配置（所有该Runner调度的任务都生效）

如果是直接部署的GitLab Runner，修改config.toml配置文件，在对应的[runners.kubernetes]配置段添加如下内容：

[runners.kubernetes]
  namespace = "sai"
  # 替换为你提前在sai命名空间创建的镜像拉取Secret名称
  image_pull_secrets = ["私有仓库拉取Secret名称"]

如果是用Helm部署的GitLab Runner，直接在values.yaml中修改对应配置：

runners:
  kubernetes:
    imagePullSecrets:
      - name: 私有仓库拉取Secret名称

配置完成后重启GitLab Runner即可生效。

方式二：单CI任务配置（仅当前任务生效）

在.gitlab-ci.yml对应任务的配置段中添加image_pull_secrets字段：

your-job-name:
  image: aie-docker-dev-mydockerrepo/python:3.6-strech
  image_pull_secrets:
    - 私有仓库拉取Secret名称
  script:
    # 替换为你的实际任务脚本
    - echo "run job"

注意：两种配置方式都要求你提前在Kubernetes的sai命名空间中创建好对应私有仓库的ImagePullSecret，创建命令参考：
kubectl create secret docker-registry 自定义Secret名称 --docker-server=私有仓库地址 --docker-username=仓库账号 --docker-password=仓库密码 -n sai

3. 其他场景排查 #

• 登录Kubernetes节点，测试节点是否可以正常访问私有镜像仓库，排查网络策略、防火墙、代理配置是否限制了节点到仓库的访问。
• 确认镜像标签未被仓库清理规则删除，如有需要更换为可用的镜像标签。

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