一、背景与需求分析

在 Kubernetes 生态中，KubeSphere 作为开源容器平台，为开发者提供了可视化的 DevOps、微服务治理及多租户管理能力。而 Harbor 作为 CNCF 毕业项目，已成为企业级私有镜像仓库的首选方案。当需要在 KubeSphere 中通过 HTTPS 协议安全访问 Harbor 镜像仓库时，开发者常面临证书配置复杂、网络策略调整等挑战。本文将系统梳理从证书生成到平台集成的全流程，确保镜像拉取与推送操作的安全性。

二、前置条件准备

1. 环境基础要求

KubeSphere 版本：建议使用 3.3.0 及以上版本（支持更细粒度的仓库认证配置）
Harbor 版本：2.4.0+（已内置 HTTPS 支持）
证书类型：推荐使用 RSA 2048 位或 ECC 256 位证书
网络连通性：确保 KubeSphere 节点可访问 Harbor 的 443 端口

2. 证书文件准备

需准备三类证书文件：

CA 根证书：ca.crt（用于验证 Harbor 服务器身份）
客户端证书：client.crt + client.key（可选，用于双向认证场景）
服务器证书：server.crt + server.key（Harbor 侧配置）

建议通过 Let’s Encrypt 或企业 PKI 系统生成证书。示例使用 OpenSSL 生成自签名证书：

# 生成 CA 私钥
openssl genrsa -out ca.key 2048
# 生成 CA 证书
openssl req -new -x509 -days 3650 -key ca.key -out ca.crt \
  -subj "/CN=Harbor-CA/O=MyOrg"
# 生成服务器私钥
openssl genrsa -out server.key 2048
# 生成证书签名请求
openssl req -new -key server.key -out server.csr \
  -subj "/CN=harbor.example.com/O=MyOrg"
# 使用 CA 签发服务器证书
openssl x509 -req -days 3650 -in server.csr -CA ca.crt -CAkey ca.key \
  -CAcreateserial -out server.crt

三、Harbor 侧 HTTPS 配置

1. 配置文件修改

编辑 /etc/harbor/harbor.yml，关键配置项：

hostname: harbor.example.com
https:
  certificate: /path/to/server.crt
  private_key: /path/to/server.key

2. 启动服务验证

执行配置重载并重启服务：

cd /usr/local/harbor
./install.sh --with-trivy --with-chartmuseum
systemctl restart harbor

通过浏览器访问 https://harbor.example.com，确认显示安全锁图标且证书信息正确。

四、KubeSphere 集成步骤

1. 创建镜像仓库凭证

登录 KubeSphere 控制台
进入「平台管理」→「凭证」→「创建」
选择类型为「用户名密码」，填写：
- 凭证名称：harbor-https-secret
- 用户名：Harbor 管理员账号
- 密码：对应密码或 Token

如需双向认证，需额外创建包含 client.crt 和 client.key 的 Secret：

kubectl create secret generic harbor-client-cert \
--from-file=tls.crt=client.crt \
--from-file=tls.key=client.key \
-n kubesphere-system

2. 添加镜像仓库

进入「平台管理」→「镜像仓库」→「添加」
填写基本信息：
- 名称：harbor-https
- 地址：https://harbor.example.com
- 认证类型：选择「使用凭证」并关联上一步创建的 Secret
高级设置（可选）：
- 跳过 TLS 验证：不推荐，仅用于测试环境
- 自定义 CA 证书：上传 ca.crt 文件

3. 验证集成效果

创建测试 Pod 引用 Harbor 镜像：

apiVersion: v1
kind: Pod
metadata:
  name: nginx-test
spec:
  containers:
  - name: nginx
    image: harbor.example.com/library/nginx:latest
    imagePullPolicy: IfNotPresent
  imagePullSecrets:
  - name: harbor-https-secret

执行 kubectl apply -f test.yaml，通过 kubectl describe pod nginx-test 确认镜像拉取成功。

五、常见问题处理

1. 证书验证失败

现象：x509: certificate signed by unknown authority
解决方案：

检查是否上传了正确的 CA 证书
确认系统时间同步（ntpdate pool.ntp.org）

对于自签名证书，需在所有节点执行：

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

2. 权限拒绝错误

现象：Error response from daemon: Head ... denied
解决方案：

检查 Harbor 项目是否设置为「公开」或已为当前用户分配角色
确认 KubeSphere 凭证中的账号具有对应项目的 push/pull 权限

3. 网络策略限制

现象：Timeout waiting for connection
解决方案：

检查安全组/防火墙是否放行 443 端口

对于私有网络环境，配置 CoreDNS 解析：

apiVersion: v1
kind: ConfigMap
metadata:
name: coredns
namespace: kube-system
data:
Corefile: |
  .:53 {
      hosts {
          192.168.1.10 harbor.example.com
          fallthrough
      }
      ...
  }

六、最佳实践建议

证书轮换策略：建议每 2 年更新证书，通过 Harbor 的 rotate-ca 命令自动化处理
多命名空间支持：为不同业务线创建独立的 Harbor 项目和 KubeSphere 凭证
监控告警：通过 Prometheus 监控 Harbor 的 API 响应时间和镜像拉取成功率
灾备方案：配置 Harbor 的复制策略，将关键镜像同步至异地仓库

通过上述步骤，开发者可在 KubeSphere 中实现 Harbor 镜像仓库的安全集成，既保障了数据传输的加密性，又维持了 DevOps 流程的顺畅性。实际部署时，建议先在测试环境验证证书链的完整性，再逐步推广至生产环境。

KubeSphere 集成 Harbor HTTPS 镜像仓库全攻略