KubeSphere 与 Harbor 安全集成：HTTPS 协议下的镜像仓库配置指南

2025年11月15日 互联网

一、引言：为什么选择 HTTPS 集成 Harbor？

在容器化部署的浪潮中，镜像仓库的安全性成为企业关注的重点。Harbor 作为开源的企业级镜像仓库，提供了强大的权限控制、镜像扫描等功能。而 KubeSphere 作为一款开源的容器平台，支持多云与多集群管理。通过 HTTPS 协议集成 Harbor，不仅能保障数据传输的安全性，还能利用 KubeSphere 的可视化界面简化镜像管理流程。本文将详细阐述如何配置这一集成方案。

二、前置条件与准备工作

1. 环境准备

  • KubeSphere 环境：确保已安装 KubeSphere（建议版本 3.x 及以上），且集群状态正常。
  • Harbor 环境：部署 Harbor 镜像仓库（建议版本 2.x 及以上），并配置 HTTPS 访问。
  • 证书准备：获取 Harbor 的 HTTPS 证书（包括 .crt 和 .key 文件），或通过 Let’s Encrypt 等工具自动生成。

2. 证书配置

Harbor 的 HTTPS 证书需包含域名信息，且该域名需在 KubeSphere 节点及客户端可解析。例如，若 Harbor 域名是 harbor.example.com，则需在 /etc/hosts 或 DNS 中配置解析。

证书存放路径

将证书文件存放至 KubeSphere 节点可访问的路径，例如 /etc/docker/certs.d/harbor.example.com。目录结构如下：

  1. /etc/docker/certs.d/harbor.example.com/
  2. ├── harbor.example.com.crt  # 证书文件
  3. └── harbor.example.com.key  # 私钥文件

三、KubeSphere 集成 Harbor 的步骤

1. 登录 KubeSphere 控制台

以管理员身份登录 KubeSphere，进入“平台管理”→“集群设置”→“镜像仓库”。

2. 添加镜像仓库

  1. 基本信息：

    • 名称：自定义（如 harbor-https）。
    • 地址：填写 Harbor 的 HTTPS 地址（如 https://harbor.example.com）。
    • 认证信息：勾选“需要认证”，输入 Harbor 的用户名和密码。

  2. 高级设置：

    • 跳过 TLS 验证：若证书为自签名且未配置信任链，可勾选此项（不推荐生产环境使用）。
    • 证书内容：若证书未自动加载，可手动粘贴证书内容（PEM 格式）。

3. 配置 Docker 信任 Harbor 证书

在 KubeSphere 节点上执行以下操作，确保 Docker 信任 Harbor 的证书：

  1. # 创建证书目录（若不存在）
  2. sudo mkdir -p /etc/docker/certs.d/harbor.example.com
  4. # 复制证书文件
  5. sudo cp /path/to/harbor.example.com.crt /etc/docker/certs.d/harbor.example.com/
  6. sudo cp /path/to/harbor.example.com.key /etc/docker/certs.d/harbor.example.com/
  8. # 重启 Docker 服务
  9. sudo systemctl restart docker

4. 验证集成

  1. 拉取镜像测试：
    在 KubeSphere 的“应用负载”→“工作负载”中创建测试 Pod，指定使用 Harbor 中的镜像。例如：

    1. apiVersion: v1
    2. kind: Pod
    3. metadata:
    4.   name: test-pod
    5. spec:
    6.   containers:
    7.   - name: nginx
    8.     image: harbor.example.com/library/nginx:latest
    9.     imagePullPolicy: Always

  2. 日志检查：
    通过 kubectl logs test-pod 查看是否成功拉取镜像。若出现 x509: certificate signed by unknown authority 错误，需检查证书配置。

四、常见问题与解决方案

1. 证书无效错误

现象：Docker 报错 x509: certificate signed by unknown authority。

原因：证书未被 Docker 信任。

解决方案：

  • 确保证书文件存放在 /etc/docker/certs.d/<域名> 目录下。
  • 检查证书格式是否为 PEM（Base64 编码）。

2. 连接超时

现象：KubeSphere 无法访问 Harbor，报错 connection timed out。

原因：网络策略或防火墙阻止了访问。

解决方案：

  • 检查 KubeSphere 节点与 Harbor 之间的网络连通性。
  • 在 KubeSphere 的“网络策略”中放行 Harbor 的 443 端口。

3. 认证失败

现象：输入用户名密码后提示 unauthorized: authentication required。

原因：Harbor 的用户权限不足或密码错误。

解决方案：

  • 确保使用的 Harbor 账户有 project admin 或更高权限。
  • 重置密码并重新测试。

五、优化建议

  1. 自动化证书管理：
    使用 Cert-Manager 或 Let’s Encrypt 自动化 Harbor 证书的续期。

  2. 多集群集成：
    在 KubeSphere 的多集群环境中，为每个集群单独配置 Harbor 镜像仓库，避免单点故障。

  3. 镜像扫描集成：
    结合 Harbor 的镜像扫描功能，在 KubeSphere 中设置镜像拉取前的安全检查策略。

六、总结

通过 HTTPS 协议集成 Harbor 镜像仓库，KubeSphere 用户可以享受到安全、高效的镜像管理体验。本文从环境准备、证书配置到集成验证，提供了完整的操作指南。在实际部署中，需特别注意证书的有效性和网络策略的配置，以确保集成的稳定性。未来，随着容器技术的演进，KubeSphere 与 Harbor 的集成将进一步优化，为企业提供更强大的容器化解决方案。

最新文章
热门标签