K8S 拉取私有仓库镜像：认证、配置与最佳实践

在 Kubernetes（K8S）集群中部署应用时，拉取私有镜像仓库的镜像是常见需求。然而，由于私有仓库的访问权限限制，直接拉取镜像往往会因认证失败而报错。本文将从认证方式、配置步骤、安全策略及故障排查四个方面，系统讲解 K8S 如何拉取私有仓库镜像，帮助开发者与运维人员高效解决这一问题。

一、私有仓库镜像拉取的必要性

随着企业容器化进程的加速，私有镜像仓库（如 Harbor、Nexus、AWS ECR、阿里云 ACR 等）已成为存储和管理私有镜像的主流选择。相较于公有仓库（如 Docker Hub），私有仓库具有以下优势：

安全性：避免敏感镜像泄露，防止恶意镜像注入。
合规性：满足企业数据主权和审计要求。
性能：私有仓库通常位于内网或高速网络中，拉取速度更快。
成本控制：避免公有仓库的流量费用或镜像数量限制。

然而，K8S 默认无法直接拉取私有仓库的镜像，必须通过认证配置实现。

二、K8S 拉取私有仓库镜像的认证方式

K8S 支持多种认证方式拉取私有仓库镜像，常见方案包括：

1. Secret 认证（推荐）

K8S 通过 Secret 对象存储私有仓库的认证信息（用户名/密码或 Token），并在 Pod 或 Deployment 中引用该 Secret。

步骤 1：创建 Docker Registry Secret

使用 kubectl create secret docker-registry 命令创建 Secret：

kubectl create secret docker-registry my-registry-secret \
  --docker-server=https://my-registry.example.com \
  --docker-username=my-username \
  --docker-password=my-password \
  --docker-email=my-email@example.com

--docker-server：私有仓库地址（如 Harbor 的 https://harbor.example.com）。
--docker-username/--docker-password：仓库登录凭证。
--docker-email：可选字段，部分仓库可能要求。

步骤 2：在 Pod 或 Deployment 中引用 Secret

在 Pod 或 Deployment 的 spec.containers.imagePullSecrets 字段中引用 Secret：

apiVersion: v1
kind: Pod
metadata:
  name: my-pod
spec:
  containers:
  - name: my-container
    image: my-registry.example.com/my-image:latest
  imagePullSecrets:
  - name: my-registry-secret

2. 全局默认 Secret（适用于所有 Namespace）

若需让所有 Namespace 的 Pod 默认使用某个 Secret 拉取镜像，可将 Secret 标记为 imagePullSecrets 的默认值：

kubectl patch serviceaccount default -p '{"imagePullSecrets": [{"name": "my-registry-secret"}]}'

此操作会修改 default ServiceAccount，使其自动附加 Secret。

3. 使用 ConfigMap 或环境变量（不推荐）

部分场景下，可通过 ConfigMap 存储认证信息，并在 Pod 中通过环境变量或脚本动态配置 docker login。但此方式安全性较低，易引发凭证泄露，仅建议用于测试环境。

三、配置步骤详解

1. 私有仓库准备

确保私有仓库已部署并可访问：

测试仓库连通性：curl -v https://my-registry.example.com/v2/
登录仓库：docker login my-registry.example.com

2. 创建 K8S Secret

按上述 Secret 认证方式创建 Secret，并验证其存在：

kubectl get secret my-registry-secret --output=yaml

输出应包含 dockerconfigjson 字段，其值为 Base64 编码的认证信息。

3. 部署应用时引用 Secret

在 Deployment 或 StatefulSet 中引用 Secret：

apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-app
spec:
  replicas: 3
  selector:
    matchLabels:
      app: my-app
  template:
    metadata:
      labels:
        app: my-app
    spec:
      containers:
      - name: my-app
        image: my-registry.example.com/my-app:latest
      imagePullSecrets:
      - name: my-registry-secret

4. 验证镜像拉取

查看 Pod 事件，确认镜像是否成功拉取：

kubectl describe pod <pod-name> | grep "Failed to pull image"

若无错误，则表示拉取成功。

四、安全策略与最佳实践

1. 最小权限原则

为 Secret 分配最小必要的权限（如仅限读取镜像）。
避免在 Secret 中存储高敏感信息（如数据库密码）。

2. 定期轮换凭证

设置凭证过期时间，定期更新 Secret。
使用短期 Token（如 AWS ECR 的临时凭证）替代长期密码。

3. 网络隔离与 TLS

私有仓库应部署在内网或通过 VPN 访问。
强制使用 HTTPS（TLS 1.2+），禁用 HTTP。

4. 审计与监控

记录镜像拉取日志，监控异常访问。
使用 K8S Audit Log 或第三方工具（如 Falco）检测可疑行为。

五、故障排查指南

1. 认证失败（401 Unauthorized）

检查 Secret 中的用户名/密码是否正确。
确认仓库地址是否包含协议（https://）。
验证仓库是否支持基本认证（部分仓库需使用 Token）。

2. 网络连通性问题

检查 Node 是否能访问私有仓库（ping 或 curl）。
若仓库位于内网，确保 Node 已加入 VPN 或内网网络。

3. Secret 未正确引用

确认 Pod 的 imagePullSecrets 字段名称与 Secret 名称一致。
检查 Namespace 是否匹配（Secret 和 Pod 需在同一 Namespace）。

4. 镜像标签错误

确认镜像标签（如 :latest）在仓库中存在。
使用 docker pull 本地测试镜像是否存在。

六、高级场景：多仓库认证

若需从多个私有仓库拉取镜像，可创建多个 Secret 并在 Pod 中同时引用：

spec:
  imagePullSecrets:
  - name: my-registry-secret-1
  - name: my-registry-secret-2

七、总结

K8S 拉取私有仓库镜像的核心在于正确配置认证信息（Secret）并在部署时引用。通过以下步骤可确保流程顺畅：

准备私有仓库并测试连通性。
创建 Docker Registry Secret。
在 Pod/Deployment 中引用 Secret。
验证镜像拉取并排查常见问题。

遵循安全策略（最小权限、TLS、审计）可进一步提升系统安全性。掌握这些技能后，开发者与运维人员将能高效管理 K8S 集群中的私有镜像部署。

K8S 私有镜像拉取全攻略：认证、配置与最佳实践