📚 课程目录第1章课程导论

课程导论：什么是 Secrets RBAC 权限不足导致镜像拉取失败？

在 Kubernetes 生产环境中，镜像拉取失败是最常见的 Pod 启动故障之一。当集群使用私有镜像仓库（如 Harbor、AWS ECR、GitLab Container Registry）时，Kubelet 需要从 Secret 中获取认证凭据才能拉取镜像。然而，很多团队在配置 RBAC 权限时，只关注了 Pod 对 API 资源的访问，却忽略了 ServiceAccount 对 Secret 的读取权限，导致 Kubelet 无法获取镜像拉取凭据，Pod 陷入 ImagePullBackOff 状态。

本课程将系统性地拆解这一隐蔽故障：从 RBAC 权限模型、Secret 引用机制、Kubelet 认证流程三个维度，带你掌握排查与修复方法。

1. 故障链路全景图

下图展示了从 Pod 创建到镜像拉取失败的完整链路，其中 RBAC 权限不足 是阻断 Secret 读取的关键环节：

2. 核心概念速览

概念	说明	与故障的关系
Secret	存储敏感数据的 Kubernetes 资源（如镜像仓库密码、TLS 证书）	镜像拉取凭据以 `docker-registry` 类型 Secret 存储
ServiceAccount	Pod 在 API Server 中的身份标识	Pod 通过绑定的 ServiceAccount 访问 Secret
RBAC	基于角色的访问控制，决定谁可以操作哪些资源	缺少 `secrets/get` 权限直接导致读取失败
imagePullSecrets	Pod 中显式引用的镜像拉取凭据	即使引用正确，RBAC 不足仍会阻断 Kubelet 读取
Kubelet	每个节点上的容器运行时代理	Kubelet 使用 Pod 的 ServiceAccount 身份执行 Secret 读取

3. 典型故障现象

Pod 事件日志示例：

Events:
  Type     Reason     Age   From               Message
  ----     ------     ----  ----               -------
  Normal   Scheduled  10s   default-scheduler  Successfully assigned default/my-app to node-1
  Normal   Pulling    5s    kubelet            Pulling image "registry.example.com/my-app:v1.0"
  Warning  Failed     3s    kubelet            Failed to pull image "registry.example.com/my-app:v1.0":
                                               rpc error: code = Unknown desc = failed to pull and unpack image:
                                               failed to resolve reference: failed to authorize:
                                               failed to fetch anonymous : unexpected status code 401 Unauthorized
  Warning  Failed     3s    kubelet            Error: ErrImagePull
  Normal   BackOff    1s    kubelet            Back-off pulling image
  Warning  Failed     1s    kubelet            Error: ImagePullBackOff

注意：错误信息中的 401 Unauthorized 或 403 Forbidden 并不总是意味着镜像仓库凭据错误——当 Kubelet 无法从 API Server 读取 Secret 时，它会尝试使用空凭据或节点凭据访问仓库，从而触发认证失败。

4. 课程目标与受众

课程目标：

理解 Kubernetes Secrets 与 RBAC 的交互机制
掌握 imagePullSecrets 的正确配置方法
学会使用 kubectl auth can-i 快速诊断 RBAC 权限
能够独立修复因 RBAC 不足导致的镜像拉取失败
建立生产环境 Secrets 管理的安全最佳实践

目标受众：

Kubernetes 集群管理员（Cluster Admin / SRE）
DevOps 工程师与平台工程师
正在学习 CKA/CKAD 认证的开发者
任何遇到过 ImagePullBackOff 且怀疑是权限问题的技术人员

前置知识：了解 Kubernetes 基本概念（Pod、Service、Deployment），熟悉 kubectl 常用命令。

5. 为什么这个问题容易被忽视？

根据社区故障统计，RBAC 权限不足导致的镜像拉取失败占所有 ImagePullBackOff 案例的 15%–20%，但往往被误判为凭据过期或仓库不可达。主要原因有三：

错误信息误导：Kubelet 返回的 401/403 错误与真实凭据错误难以区分。
默认行为掩盖：部分集群使用 default ServiceAccount，该账号通常没有显式绑定 Secret 读取权限。
RBAC 配置分散：Role/ClusterRole 与 RoleBinding/ClusterRoleBinding 分布在多个 YAML 文件中，审计困难。