Kubernetes镜像拉取失败排查：手动部署正常但YAML部署失败

核心差异：镜像拉取策略（imagePullPolicy） #

你遇到的问题根源在于两种部署方式的镜像拉取策略不一致：

• 手动执行kubectl create deployment时，Kubernetes会自动将无远程仓库前缀的本地镜像的拉取策略设为IfNotPresent——即本地已有该镜像时直接使用，不会尝试去远程仓库拉取。
• 你的deployment.yml里显式设置了imagePullPolicy: Always——该策略会强制Kubernetes每次尝试从远程镜像仓库拉取镜像，而你的rts.api:1.0.0.1仅存在本地，远程仓库无对应镜像，因此触发拉取权限报错。

验证配置差异 #

执行以下命令查看手动部署的完整配置，确认拉取策略：

kubectl get deployment manual-test3 -o yaml

输出中容器部分的配置会类似：

containers:
- image: rts.api:1.0.0.1
  imagePullPolicy: IfNotPresent
  # 其他配置项...

解决方案 #

修改deployment.yml中的imagePullPolicy为IfNotPresent（推荐，兼顾本地镜像使用与远程镜像更新场景）或Never（完全依赖本地镜像，不尝试拉取）：

apiVersion: apps/v1
kind: Deployment
metadata:
  name: rts-api    
spec:
  replicas: 1
  selector:
    matchLabels:
      app: rts-api
  template:
    metadata:
      labels:
        app: rts-api
    spec:
      containers:
      - name: rts-api
        image: rts.api:1.0.0.1
        imagePullPolicy: IfNotPresent  # 修改此处

修改后重新部署：

kubectl apply -f .\deployment.yml

额外排查思路 #

• 查看Pod的完整事件与配置：kubectl describe pod [pod-name]，能获取比get events更详细的错误细节和Pod配置信息
• 确认本地镜像存在：docker images | grep rts.api，确保镜像标签与YAML中的配置完全一致
• 检查节点镜像缓存：Docker Desktop的Kubernetes节点与本地Docker共享镜像，只要本地存在镜像，节点即可直接访问，无需额外配置镜像仓库凭证

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