📚 课程目录第3章镜像配置概念解析

3. 镜像配置概念解析：镜像仓库地址、镜像标签（tag）、拉取策略（imagePullPolicy）、私有仓库认证（imagePullSecrets）

在 Kubernetes 集群升级过程中，ConfigMap 中存储的镜像配置是决定工作负载能否平滑过渡的关键因素。镜像配置的四个核心要素——镜像仓库地址、镜像标签（tag）、拉取策略（imagePullPolicy）、私有仓库认证（imagePullSecrets）——共同决定了 Pod 在启动时如何获取容器镜像。理解这些概念及其在升级场景中的行为差异，是避免迁移故障的前提。

3.1 镜像仓库地址

镜像仓库地址（Image Registry Address）是容器镜像的存储位置标识，通常由 registry/namespace/repository:tag 四部分组成。在 ConfigMap 中，镜像仓库地址往往以字符串形式嵌入 Deployment、StatefulSet 或 DaemonSet 的 YAML 定义中。

组成部分	示例	说明
Registry 域名	`registry.cn-hangzhou.aliyuncs.com`	镜像仓库的访问入口，决定拉取速度与网络路径
命名空间（Namespace）	`mycompany`	组织或项目隔离，避免镜像名称冲突
镜像仓库（Repository）	`backend-api`	具体应用的镜像存储库
标签（Tag）	`v2.1.0`	镜像版本标识，决定拉取哪个版本的镜像

升级迁移要点： 集群升级时，镜像仓库地址可能因迁移至新仓库、切换云厂商或启用镜像代理而发生变更。ConfigMap 中硬编码的仓库地址必须同步更新，否则 Pod 将尝试从旧地址拉取镜像，导致拉取失败或拉取到过期版本。

3.2 镜像标签（tag）

镜像标签是镜像版本的唯一标识符。在 ConfigMap 中，标签通常与仓库地址拼接后赋值给 image 字段。标签的使用策略直接影响升级的可靠性与可追溯性。

语义化标签：如 v1.2.3、release-2025-03，明确标识版本号，适合生产环境。
可变标签：如 latest、stable，指向最新构建的镜像，但存在不确定性——不同节点可能拉取到不同版本的镜像。
摘要标签：如 sha256:abc123...，基于镜像内容哈希生成，保证唯一性与不可变性，是升级迁移中最安全的标签类型。

升级陷阱： 使用 latest 标签的 ConfigMap 在集群升级后可能自动拉取到新版本镜像，导致应用行为意外变化。建议在 ConfigMap 中始终使用不可变标签（语义化版本或摘要），并在升级前显式更新标签值。

3.3 拉取策略（imagePullPolicy）

拉取策略决定了 kubelet 在启动容器时是否从远程仓库拉取镜像。该策略在 Pod 的容器定义中通过 imagePullPolicy 字段设置，ConfigMap 中通常不直接存储该字段，但镜像配置变更会间接影响策略行为。

策略值	行为描述	适用场景
`Always`	每次启动容器都从远程仓库拉取镜像	开发环境、使用 `latest` 标签的场景
`IfNotPresent`	仅当本地不存在该镜像时才拉取	生产环境、使用不可变标签的场景
`Never`	仅使用本地已存在的镜像，不拉取	离线环境、预加载镜像的场景

  升级迁移建议： 当 ConfigMap 中的镜像标签从 v1.0.0 更新为 v2.0.0 时，若 imagePullPolicy 为 IfNotPresent，kubelet 会检测到本地没有 v2.0.0 镜像，自动触发拉取。若策略为 Never，则 Pod 会因镜像不存在而启动失败。升级前务必确认拉取策略与镜像标签的兼容性。

3.4 私有仓库认证（imagePullSecrets）

私有仓库认证通过 imagePullSecrets 字段将 Docker Registry 的凭据注入到 Pod 中，使 kubelet 能够拉取私有仓库中的镜像。在 ConfigMap 中，镜像配置变更后，必须确保对应的 imagePullSecrets 仍然有效且指向正确的 Secret 对象。

典型的私有仓库认证流程如下：

管理员创建 docker-registry 类型的 Secret，包含仓库地址、用户名和密码。
在 Pod 的 ServiceAccount 或 Pod 定义中引用该 Secret。
kubelet 拉取镜像时，自动使用 Secret 中的凭据进行认证。

# 创建私有仓库认证 Secret
kubectl create secret docker-registry my-registry-secret \
  --docker-server=https://registry.mycompany.com \
  --docker-username=admin \
  --docker-password=securepass123 \
  --docker-email=admin@mycompany.com

# 在 Pod 中引用 Secret
apiVersion: v1
kind: Pod
metadata:
  name: my-app
spec:
  containers:
  - name: app
    image: registry.mycompany.com/myapp:v2.0.0
  imagePullSecrets:
  - name: my-registry-secret

升级迁移陷阱： 集群升级后，若 Secret 所在的命名空间被重建、Secret 被误删除或仓库地址发生变更，imagePullSecrets 将失效。此时即使 ConfigMap 中的镜像地址正确，Pod 也无法拉取镜像。建议在升级前验证 Secret 的可用性，并考虑使用 kubectl get secret 检查凭据状态。

3.5 四要素协同关系图

以下 SVG 图展示了镜像配置四要素在 Pod 启动过程中的协同关系，以及 ConfigMap 在其中扮演的配置传递角色。

3.6 升级迁移中的配置验证清单

在集群升级前，建议对照以下清单逐一验证 ConfigMap 中的镜像配置，确保四要素均处于正确状态：

检查项	验证内容	常见问题
仓库地址	新仓库地址是否可解析、可访问	DNS 解析失败、仓库迁移后未更新 ConfigMap
镜像标签	标签是否指向正确的镜像版本	使用 `latest` 导致版本漂移、标签不存在
拉取策略	策略是否与标签类型兼容	`Never` 策略下镜像不存在导致启动失败
私有仓库认证	Secret 是否存在、凭据是否有效	Secret 被删除、凭据过期、仓库地址变更

最佳实践： 在 ConfigMap 中存储镜像配置时，建议将仓库地址、标签、拉取策略和认证 Secret 名称作为独立字段管理，而非拼接成字符串。这样在升级迁移时可以单独更新某个字段，降低配置错误风险。例如：IMAGE_REGISTRY=registry.mycompany.com、IMAGE_TAG=v2.0.0、IMAGE_PULL_POLICY=IfNotPresent、IMAGE_PULL_SECRET=my-registry-secret。