从零到一：K8S与Harbor私有仓库的权限握手协议

1. 容器生态中的权限挑战

在云原生技术栈中，容器镜像作为应用交付的标准载体，其安全管理一直是企业级部署的核心议题。当Kubernetes集群需要从Harbor私有仓库拉取镜像时，401 Unauthorized错误如同一位严格的守门人，拒绝所有未经授权的访问尝试。这个看似简单的HTTP状态码背后，实则隐藏着一套精密的认证协议体系。

现代容器编排系统与镜像仓库的交互，本质上是一场精心设计的"数字握手"。Docker Registry V2规范定义了这套握手流程：当kubelet尝试拉取私有镜像时，会经历"挑战-响应"的认证过程。Harbor作为企业级Registry实现，在此基础上增加了角色权限控制、项目隔离等高级特性，使得认证流程更具层次感。

典型认证失败场景示例：

Events:
  Type     Reason   Age                From     Message
  ----     ------   ----               ----     -------
  Warning  Failed   12s (x3 over 46s)  kubelet  Failed to pull image "harbor.example.com/project/app:v1": 
  rpc error: code = Unknown desc = Error response from daemon: 
  unauthorized: unauthorized to access repository: project/app, action: pull

2. 认证协议深度解析

2.1 HTTP与HTTPS的认证差异

协议选择直接影响认证流程的安全性：

特性	HTTP协议	HTTPS协议
认证流程	基础认证	Token认证
凭证传输	Base64编码明文	加密通道传输
中间人攻击风险	高	低
配置复杂度	低（需设置insecure-registry）	高（需配置证书）
企业级适用性	测试环境	生产环境

安全提示：即使在内网环境，也建议启用HTTPS并配置可信证书。自签名证书需在所有节点执行：

mkdir -p /etc/docker/certs.d/harbor.example.com
cp harbor-ca.crt /etc/docker/certs.d/harbor.example.com/ca.crt

2.2 Docker Registry认证流程

1. 初始请求：Kubelet向Registry发起镜像拉取请求
2. 挑战响应：Registry返回401状态码及WWW-Authenticate头，包含认证服务地址
3. 令牌获取：Kubelet携带Secret凭证向认证服务请求Bearer Token
4. 最终访问：Kubelet使用Token重新请求镜像数据

关键日志分析：

# 认证成功流程
GET /v2/project/app/manifests/v1 HTTP/1.1
Host: harbor.example.com
Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...

# 失败案例（缺少认证头）
GET /v2/project/app/manifests/v1 HTTP/1.1
Host: harbor.example.com
< 401 Unauthorized
Www-Authenticate: Bearer realm="https://harbor.example.com/service/token",service="harbor-registry"

3. 机器人账号的自动化管理

Harbor的机器人账号(Robot Account)是专为CI/CD设计的特殊凭证，相比普通用户账号具有以下优势：

• 权限最小化：可精确到项目级别的读写权限控制
• 令牌轮换：支持定期自动更新访问令牌
• 审计追踪：独立记录机器人账号的操作日志

创建机器人账号的API示例：

POST /api/v2.0/projects/{project_name}/robots
{
  "name": "k8s-puller",
  "description": "For Kubernetes cluster auto scaling",
  "access": [
    {
      "resource": "repository",
      "action": "pull",
      "name": "project/app"
    }
  ]
}

权限矩阵参考：

角色类型	镜像拉取	镜像推送	项目管理	用户管理
项目管理员	✓	✓	✓	✗
开发者	✓	✓	✗	✗
只读用户	✓	✗	✗	✗
机器人账号	✓	可配置	✗	✗

4. Kubernetes Secret配置实战

4.1 手动创建docker-registry Secret

命令行方式：

kubectl create secret docker-registry harbor-creds \
  --docker-server=harbor.example.com \
  --docker-username='robot$k8s-puller' \
  --docker-password='a1b2c3d4-e5f6-7890' \
  --docker-email='devops@company.com' \
  -n application

YAML声明式配置：

apiVersion: v1
kind: Secret
metadata:
  name: harbor-creds
  namespace: application
type: kubernetes.io/dockerconfigjson
data:
  .dockerconfigjson: ewogICJhdXRocyI6IHsKICAgICJoYXJib3IuZXhhbXBsZS5jb20iOiB7CiAgICAgICJhdXRoIjogImFXNW1kQzFwYmkxelpXRnlZMmd1WTI5dE9USXpORFU9IgogICAgfQogIH0KfQ==

Base64解码技巧：

echo "ewogICJhdXRocyI6IHsKICAgICJoYXJib3IuZXhhbXBsZS5jb20iOiB7CiAgICAgICJhdXRoIjogImFXNW1kQzFwYmkxelpXRnlZMmd1WTI5dE9USXpORFU9IgogICAgfQogIH0KfQ==" | base64 -d

4.2 多租户场景下的Secret管理

在具有多个命名空间的环境中，推荐采用以下策略：

1. 全局凭证：在kube-system命名空间创建基础Secret

   kubectl create secret docker-registry global-harbor-creds \
     --docker-server=harbor.example.com \
     --docker-username='robot$global-puller' \
     --docker-password='x1y2z3' \
     -n kube-system
   

2. 命名空间覆盖：特定项目使用独立凭证

   kubectl create secret docker-registry project-special-creds \
     --docker-server=harbor.example.com \
     --docker-username='robot$project-puller' \
     --docker-password='p1q2r3' \
     -n special-project
   

3. 自动注入：通过ServiceAccount绑定

   kubectl patch serviceaccount default \
     -n application \
     -p '{"imagePullSecrets":[{"name":"harbor-creds"}]}'
   

5. 高级配置与故障排查

5.1 containerd运行时特殊配置

当使用containerd作为CRI运行时，需额外配置registry mirrors：

# /etc/containerd/config.toml
[plugins."io.containerd.grpc.v1.cri".registry]
  [plugins."io.containerd.grpc.v1.cri".registry.mirrors]
    [plugins."io.containerd.grpc.v1.cri".registry.mirrors."harbor.example.com"]
      endpoint = ["https://harbor.example.com"]
  
  [plugins."io.containerd.grpc.v1.cri".registry.configs]
    [plugins."io.containerd.grpc.v1.cri".registry.configs."harbor.example.com".auth]
      username = "robot$k8s-puller"
      password = "a1b2c3d4-e5f6-7890"

应用配置后重启服务：

systemctl restart containerd

5.2 常见故障排查指南

问题现象：持续出现ImagePullBackOff状态

诊断步骤：

1. 检查Pod描述获取详细事件

   kubectl describe pod/myapp -n application
   

2. 验证Secret配置正确性

   kubectl get secret harbor-creds -n application -o yaml
   

3. 手动测试凭证有效性

   docker login harbor.example.com -u robot\$k8s-puller -p a1b2c3d4-e5f6-7890
   

4. 检查网络连通性

   curl -vk https://harbor.example.com/v2/_catalog
   

5. 查看containerd日志（如适用）

   journalctl -u containerd -f
   

证书相关错误处理：

# 忽略证书验证（仅测试环境）
kubectl create secret generic insecure-registry \
  --from-file=.dockerconfigjson=$HOME/.docker/config.json \
  --type=kubernetes.io/dockerconfigjson

6. 安全加固最佳实践

1. 凭证轮换策略：

   • 设置机器人账号有效期（如90天）
   • 使用Harbor API自动更新Secret

   # 定期更新脚本示例
   NEW_TOKEN=$(curl -s -X POST -H "Content-Type: application/json" \
     -u admin:$HARBOR_ADMIN_PW \
     "https://harbor.example.com/api/v2.0/robots" \
     -d '{"name":"k8s-puller","expires_at":1835000000}' | jq -r .token)
   
   kubectl create secret docker-registry harbor-creds \
     --docker-server=harbor.example.com \
     --docker-username='robot$k8s-puller' \
     --docker-password="$NEW_TOKEN" \
     --dry-run=client -o yaml | kubectl apply -f -
   

2. 网络策略限制：

   apiVersion: networking.k8s.io/v1
   kind: NetworkPolicy
   metadata:
     name: allow-harbor-access
     namespace: application
   spec:
     podSelector: {}
     policyTypes:
     - Egress
     egress:
     - to:
       - namespaceSelector:
           matchLabels:
             networking/allow-harbor: "true"
       ports:
       - protocol: TCP
         port: 443
   

3. 审计日志监控：

   • 启用Harbor操作日志
   • 配置K8S审计策略跟踪Secret访问
   • 使用Falco等工具检测异常拉取行为

在实际生产环境中，我们曾遇到一个典型案例：某次集群扩容时，新节点因时间不同步导致NTP验证失败，引发TLS握手错误。这个案例提醒我们，在排查401问题时，需要将认证体系视为一个包含时间同步、DNS解析、证书链验证在内的完整生态系统。