一、背景与需求分析

在 Kubernetes 生态中，镜像仓库是容器化应用部署的核心组件。Harbor 作为开源的企业级镜像仓库，提供权限管理、镜像复制等功能，而 KubeSphere 作为领先的容器管理平台，支持多租户、自动化运维等特性。两者通过 HTTPS 协议集成，既能保障数据传输安全，又能实现镜像的统一管理。

典型场景：企业内网环境中，KubeSphere 集群需要从私有 Harbor 仓库拉取镜像，但 Harbor 启用了自签名证书或 CA 签发的证书，此时需正确配置信任链以避免连接失败。

二、配置前准备

1. 环境确认

KubeSphere 版本：建议使用 3.3.0 及以上版本（支持更完善的镜像仓库管理）。
Harbor 版本：2.0+（已内置 HTTPS 支持）。
网络连通性：KubeSphere 节点需能访问 Harbor 的 HTTPS 端口（默认 443）。

2. 证书准备

Harbor 的 HTTPS 证书分为两种情况：

CA 签发证书：需获取 CA 根证书（.crt 或 .pem 文件）。
自签名证书：需导出 Harbor 服务器的证书（通过浏览器或 openssl 命令）。

示例：使用 openssl 导出证书

# 获取 Harbor 服务器证书（假设域名是 harbor.example.com）
openssl s_client -connect harbor.example.com:443 -showcerts </dev/null 2>/dev/null | openssl x509 -outform PEM > harbor-cert.pem

三、KubeSphere 集成 Harbor 的 HTTPS 配置步骤

1. 登录 KubeSphere 控制台

以 admin 用户登录，进入 平台管理 → 集群管理 → 系统组件 → 镜像仓库。

2. 添加镜像仓库

基本信息：
- 名称：自定义（如 harbor-https）。
- 类型：选择 Harbor。
- 地址：填写 Harbor 的 HTTPS 地址（如 https://harbor.example.com）。
- 认证信息：输入 Harbor 的用户名和密码（或使用 Token）。
证书配置：
- 启用 自定义证书 选项。
- 上传之前导出的证书文件（harbor-cert.pem）。
- 点击验证按钮，确保 KubeSphere 能成功连接 Harbor。
测试连接：
- 点击 测试连接，若显示“连接成功”，则配置正确。
- 若失败，检查证书是否完整、网络是否通畅。

3. 命令行配置（可选）

对于自动化部署场景，可通过 kubectl 修改 KubeSphere 的配置：

# 编辑 KubeSphere 的镜像仓库配置（需获取具体 ConfigMap 名称）
kubectl edit configmap -n kubesphere-system ks-installer

在配置中添加 Harbor 的 HTTPS 地址和证书路径（需提前将证书挂载到 Pod）。

四、常见问题与解决方案

1. 证书不受信任

现象：KubeSphere 控制台报错 x509: certificate signed by unknown authority。
原因：未正确配置 CA 证书或自签名证书未被信任。
解决：

确保上传的证书包含完整的信任链（从根证书到服务器证书）。
如果是自签名证书，需确保证书未过期且域名匹配。

2. 网络策略限制

现象：KubeSphere 节点无法访问 Harbor 的 443 端口。
解决：

检查防火墙规则（如 iptables 或云服务商的安全组）。
确保 Harbor 的 Ingress 或 LoadBalancer 配置正确。

3. 认证失败

现象：提示 Unauthorized 或 401 错误。
解决：

确认 Harbor 的用户名/密码或 Token 是否正确。
检查 Harbor 的权限策略（如项目是否允许匿名访问）。

五、最佳实践建议

证书轮换：定期更新 Harbor 的证书，并在 KubeSphere 中同步更新。
多环境隔离：为开发、测试、生产环境分别配置不同的 Harbor 仓库。
监控告警：通过 KubeSphere 的监控功能，实时跟踪镜像拉取的延迟和成功率。
备份策略：定期备份 Harbor 的元数据和镜像（可通过 Harbor 的备份插件实现）。

六、总结

通过 HTTPS 协议集成 Harbor 镜像仓库，KubeSphere 用户可以实现安全的镜像管理，避免中间人攻击和数据泄露。本文详细介绍了配置前的准备工作、具体操作步骤以及常见问题的解决方案，帮助用户快速完成集成。在实际生产环境中，建议结合企业的安全策略，进一步优化证书管理和访问控制。

KubeSphere 与 Harbor HTTPS 集成：安全镜像管理实践指南