KubeSphere 使用 HTTPS 协议集成 Harbor 镜像仓库指南

2025年11月1日 互联网

KubeSphere 使用 HTTPS 协议集成 Harbor 镜像仓库指南

引言

在 Kubernetes 生态中，KubeSphere 作为开源的容器平台，提供了强大的企业级功能，包括应用管理、DevOps、多租户等。而 Harbor 是一个开源的企业级 Docker 镜像仓库，支持镜像管理、访问控制、安全审计等功能。将 KubeSphere 与 Harbor 通过 HTTPS 协议集成，能够确保镜像传输的安全性，提升整体系统的可靠性。本文将详细介绍如何在 KubeSphere 中使用 HTTPS 协议集成 Harbor 镜像仓库。

前置条件

在开始之前，请确保以下条件已满足：

  • 已安装并运行 KubeSphere 集群。
  • 已部署 Harbor 镜像仓库，并配置了 HTTPS 访问。
  • 拥有 Harbor 管理员权限或具有配置权限的账户。
  • 服务器之间网络互通，且防火墙规则允许 HTTPS 流量（默认端口 443）。

步骤一：准备 HTTPS 证书

Harbor 默认使用自签名证书或受信任的 CA 签发的证书。为了在 KubeSphere 中成功集成，需确保：

  1. 获取证书：如果是自签名证书，需将证书文件（通常为 .crt 或 .pem 格式）下载到本地。
  2. 证书格式转换：某些情况下，可能需要将证书转换为 Kubernetes Secret 能识别的格式。使用以下命令将证书和私钥合并为一个文件（假设证书为 harbor.crt，私钥为 harbor.key）： 
    1. openssl pkcs12 -export -in harbor.crt -inkey harbor.key -out harbor.p12 -name harbor
    2. kubectl create secret generic harbor-cert --from-file=tls.crt=harbor.crt --from-file=tls.key=harbor.key -n kubesphere-system

    或者，如果使用 PKCS12 格式：

    1. kubectl create secret generic harbor-cert --from-file=harbor.p12 -n kubesphere-system

步骤二：配置 Harbor 仓库

  1. 登录 Harbor：使用管理员账户登录 Harbor Web 界面。
  2. 创建项目（可选）：根据需求创建用于存放镜像的项目。
  3. 配置用户权限：确保用于集成的用户具有拉取和推送镜像的权限。
  4. 获取 Harbor 地址：记录下 Harbor 的 HTTPS 地址，如 https://harbor.example.com。

步骤三：在 KubeSphere 中集成 Harbor

方法一：通过 UI 界面集成

  1. 登录 KubeSphere：使用具有管理员权限的账户登录 KubeSphere Web 控制台。
  2. 进入系统设置：点击左上角平台管理，选择“集群管理”。
  3. 配置镜像仓库：
    • 在集群管理页面，选择“系统设置”下的“镜像仓库”。
    • 点击“添加镜像仓库”。
    • 填写名称（如 harbor）、地址（Harbor 的 HTTPS 地址）、用户名和密码。
    • 如果使用自签名证书，勾选“跳过 SSL 证书验证”（不推荐生产环境使用），或上传证书文件（如果支持）。
    • 点击“确定”保存配置。

方法二：通过 kubectl 和 YAML 文件集成

  1. 创建 Secret：如果 Harbor 使用用户名和密码认证，创建一个包含认证信息的 Secret：

    1. apiVersion: v1
    2. kind: Secret
    3. metadata:
    4.   name: harbor-secret
    5.   namespace: kubesphere-system
    6. type: kubernetes.io/basic-auth
    7. stringData:
    8.   username: "your_username"
    9.   password: "your_password"

    应用该 YAML 文件：

    1. kubectl apply -f harbor-secret.yaml

  2. 创建 ImagePullSecret（如果需要）：

    1. apiVersion: v1
    2. kind: Secret
    3. metadata:
    4.   name: harbor-image-pull-secret
    5.   namespace: your-namespace
    6. type: kubernetes.io/dockerconfigjson
    7. data:
    8.   .dockerconfigjson: |
    9.     {
    10.       "auths": {
    11.         "https://harbor.example.com": {
    12.           "auth": "$(echo -n 'your_username:your_password' | base64)"
    13.         }
    14.       }
    15.     }

    或者使用 kubectl create secret docker-registry 命令：

    1. kubectl create secret docker-registry harbor-image-pull-secret \
    2.   --docker-server=https://harbor.example.com \
    3.   --docker-username=your_username \
    4.   --docker-password=your_password \
    5.   --namespace=your-namespace

  3. 在 KubeSphere 中引用 Secret：在创建工作负载或部署时，在“容器镜像”部分的“镜像仓库”下拉菜单中选择已配置的 Harbor 仓库，或手动输入地址并选择对应的 Secret。

步骤四：验证集成

  1. 推送镜像：在本地或 CI/CD 流程中，使用 Docker 或 Podman 命令推送镜像到 Harbor：

    1. docker tag your_image harbor.example.com/your_project/your_image:tag
    2. docker push harbor.example.com/your_project/your_image:tag

  2. 在 KubeSphere 中拉取镜像：创建一个测试工作负载，使用从 Harbor 推送的镜像，观察是否能成功拉取并运行。

  3. 检查日志：查看工作负载的 Pod 日志，确认没有因认证或证书问题导致的错误。

常见问题与解决

  • 证书问题：如果遇到 x509: certificate signed by unknown authority 错误，说明客户端不信任 Harbor 的证书。解决方案包括：

    • 使用受信任的 CA 签发的证书。
    • 在客户端（如 Docker）配置信任自签名证书。
    • 在 KubeSphere 中上传证书文件。

  • 认证失败：检查用户名和密码是否正确，以及 Secret 是否正确创建和引用。

  • 网络问题：确保 KubeSphere 集群节点能够访问 Harbor 的 HTTPS 端口。

结论

通过 HTTPS 协议集成 Harbor 镜像仓库到 KubeSphere，不仅提升了镜像传输的安全性，还利用了 Harbor 强大的镜像管理功能。遵循上述步骤，您可以轻松完成集成，并根据实际需求调整配置。在生产环境中，建议使用受信任的 CA 签发的证书，并定期更新证书以确保安全性。

最新文章