一、背景与需求分析

在 Kubernetes 生态中，Harbor 作为企业级镜像仓库，提供了权限控制、镜像扫描等核心功能。而 KubeSphere 作为开源容器平台，需要与 Harbor 深度集成以实现镜像的集中管理。HTTPS 协议的引入可确保数据传输的安全性，避免镜像在传输过程中被篡改或窃取。

1.1 为什么需要 HTTPS 集成？

数据安全：防止镜像元数据和镜像层在传输过程中被窃听或篡改。
合规要求：满足金融、医疗等行业对数据传输加密的强制要求。
信任链建立：通过 CA 签发的证书验证 Harbor 服务端的身份。

1.2 典型应用场景

私有云环境中 KubeSphere 集群使用内部 Harbor 仓库。
跨数据中心或混合云场景下通过公网访问 Harbor。
需要与 CI/CD 流水线集成的自动化镜像构建与部署。

二、前置条件准备

2.1 Harbor 环境配置

HTTPS 证书生成：
- 使用 OpenSSL 生成自签名证书（测试环境）或申请 CA 签发证书（生产环境）：
```
openssl req -x509 -nodes -days 365 -newkey rsa:2048 \
  -keyout harbor.key -out harbor.crt \
  -subj "/CN=harbor.example.com"
```
- 将证书文件放置在 /data/cert/ 目录（Harbor 默认配置路径）。

Harbor 配置修改：

编辑 harbor.yml 文件：

hostname: harbor.example.com
https:
  certificate: /data/cert/harbor.crt
  private_key: /data/cert/harbor.key

执行 ./install.sh 重新部署 Harbor。

2.2 KubeSphere 环境检查

确认集群节点可访问 Harbor 的 HTTPS 端口（默认 443）。
准备集群管理员权限的 kubectl 配置。

三、KubeSphere 集成步骤

3.1 创建 Docker 凭证

登录 KubeSphere 控制台：
- 进入「平台管理」→「配置中心」→「密钥」。

创建 Secret 资源：

选择类型为 kubernetes.io/dockerconfigjson。

内容格式（Base64 编码的 .docker/config.json）：

{
  "auths": {
    "https://harbor.example.com": {
      "auth": "username:password的Base64编码",
      "email": "admin@example.com"
    }
  }
}

或通过命令行创建：

kubectl create secret generic harbor-secret \
  --from-file=.dockerconfigjson=<(echo '{"auths":{"https://harbor.example.com":{"auth":"base64-auth","email":"admin@example.com"}}}') \
  --type=kubernetes.io/dockerconfigjson -n kube-system

3.2 配置镜像仓库（可选）

对于 KubeSphere 3.x 版本，可通过「系统设置」→「镜像仓库」添加 Harbor：

仓库地址：https://harbor.example.com
认证方式：选择已创建的 Secret。
验证连接性：点击「测试连接」确认可访问。

3.3 项目级镜像拉取配置

在项目内创建 Secret：
- 路径：项目 → 配置 → 密钥 → 创建。
- 类型选择 Docker 仓库密钥，填写 Harbor 地址、用户名和密码。

在 Deployment 中引用：

spec:
  containers:
  - name: nginx
    image: harbor.example.com/library/nginx:latest
  imagePullSecrets:
  - name: harbor-secret  # 引用前面创建的Secret

四、高级配置与故障排查

4.1 自签名证书处理

若使用自签名证书，需在所有节点配置信任：

将证书添加到系统信任库：

# Linux 节点操作
sudo cp harbor.crt /usr/local/share/ca-certificates/
sudo update-ca-certificates

Docker 配置：

编辑 /etc/docker/daemon.json：

{
  "insecure-registries": [],
  "registry-mirrors": [],
  "allow-nondistributable-artifacts": ["harbor.example.com"]
}

重启 Docker 服务：systemctl restart docker

4.2 常见问题解决

问题现象	可能原因	解决方案
`x509: certificate signed by unknown authority`	证书未信任	配置节点信任链或使用 CA 签发证书
`401 Unauthorized`	认证失败	检查 Secret 中的用户名/密码是否正确
`Connection refused`	网络不通	检查防火墙规则和 Harbor 服务状态

五、最佳实践建议

证书管理：
- 生产环境使用 Let’s Encrypt 或企业 CA 签发证书。
- 证书过期前 30 天设置告警。
权限控制：
- 在 Harbor 中为不同项目创建独立用户。
- 通过 KubeSphere 的 RBAC 限制镜像拉取权限。
性能优化：
- 对 Harbor 启用镜像缓存和 P2P 加速。
- 在 KubeSphere 集群就近部署 Harbor 节点。

六、总结与展望

通过 HTTPS 协议集成 Harbor 镜像仓库，KubeSphere 用户可获得：

端到端的数据传输加密
符合等保 2.0 三级要求的安全架构
与企业现有 CA 体系的无缝对接

未来可探索：

与 Vault 集成实现证书自动轮换
支持 OCI 规范的艺术品仓库扩展
基于 Service Mesh 的镜像传输监控

提示：完整操作示例代码和配置文件已上传至 GitHub 仓库 kubesphere-harbor-integration，包含 Terraform 自动化部署脚本和 Helm Chart 模板。

KubeSphere 集成 Harbor HTTPS 镜像仓库全流程指南