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

一、背景与必要性

在容器化部署场景中，私有镜像仓库是企业保障软件供应链安全的核心组件。Harbor作为开源的企业级镜像仓库，提供RBAC权限控制、镜像复制、漏洞扫描等功能，而KubeSphere作为全栈的容器云平台，支持多租户管理。通过HTTPS协议集成两者，既能确保镜像传输的加密性，又能实现与KubeSphere权限体系的深度整合。

1.1 安全需求分析

数据加密：HTTPS通过TLS协议防止镜像拉取过程中的中间人攻击
身份验证：结合KubeSphere的OAuth2.0机制实现单点登录
合规要求：满足金融、政府等行业对数据传输加密的强制标准

二、集成前准备工作

2.1 Harbor端配置

证书准备：
- 生成CA证书：openssl req -newkey rsa:4096 -nodes -sha256 -keyout ca.key -x509 -days 365 -out ca.crt
- 生成服务器证书：openssl req -newkey rsa:4096 -nodes -sha256 -keyout harbor.key -out harbor.csr
- 签发证书：openssl x509 -req -days 365 -in harbor.csr -CA ca.crt -CAkey ca.key -set_serial 01 -out harbor.crt

Harbor配置修改：

# /etc/harbor/harbor.yml
hostname: registry.example.com
https:
  certificate: /path/to/harbor.crt
  private_key: /path/to/harbor.key

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

2.2 KubeSphere端准备

信任链配置：
- 将CA证书上传至KubeSphere控制节点：/etc/docker/certs.d/registry.example.com/ca.crt
- 重启docker服务：systemctl restart docker
网络策略检查：
- 确认KubeSphere集群节点可访问Harbor的443端口
- 测试连通性：curl -vk https://registry.example.com/v2/_catalog

三、KubeSphere集成步骤

3.1 创建镜像仓库凭证

进入KubeSphere控制台 → 平台管理 → 配置中心 → 密钥
点击创建，选择镜像仓库密钥类型：
- 密钥名称：harbor-https-secret
- 仓库地址：https://registry.example.com
- 用户名/密码：Harbor管理员账号

3.2 配置镜像仓库连接

进入集群管理 → 系统项目 → 选择目标集群
在配置中心 → 镜像仓库中点击添加：
- 名称：harbor-https
- 地址：https://registry.example.com
- 认证方式：选择上一步创建的密钥
- 跳过TLS验证：不勾选（确保严格安全）

3.3 验证集成效果

创建测试Deployment：

apiVersion: apps/v1
kind: Deployment
metadata:
  name: nginx-test
spec:
  replicas: 1
  selector:
    matchLabels:
      app: nginx
  template:
    metadata:
      labels:
        app: nginx
    spec:
      containers:
      - name: nginx
        image: registry.example.com/library/nginx:latest
        imagePullPolicy: IfNotPresent

观察Pod状态，确认镜像成功拉取

四、高级配置与最佳实践

4.1 项目级镜像仓库隔离

在项目设置中创建专用密钥，限制访问特定Harbor项目
结合KubeSphere的网络策略，实现项目间镜像访问隔离

4.2 自动化镜像推送

配置Jenkins流水线：

pipeline {
  agent any
  stages {
    stage('Build & Push') {
      steps {
        script {
          docker.withRegistry('https://registry.example.com', 'harbor-https-secret') {
            def image = docker.build("registry.example.com/${env.PROJECT_NAME}/${env.APP_NAME}:${env.BUILD_ID}")
            image.push()
          }
        }
      }
    }
  }
}

4.3 性能优化建议

镜像缓存：在每个节点部署registry-mirror缓存常用镜像
负载均衡：对Harbor部署Nginx反向代理，配置Keepalived实现高可用
存储优化：使用对象存储（如MinIO）作为Harbor的后端存储

五、常见问题排查

5.1 证书错误处理

现象：x509: certificate signed by unknown authority
解决方案：
1. 检查/etc/docker/certs.d/目录结构是否正确
2. 确认证书文件权限为644
3. 执行update-ca-certificates（如使用自签证书）

5.2 权限拒绝问题

现象：Error response from daemon: pull access denied for registry.example.com/library/nginx
排查步骤：
1. 确认Harbor项目已启用公开访问（或用户有拉取权限）
2. 检查KubeSphere密钥中的用户名/密码是否正确
3. 验证Harbor的审计日志确认请求是否到达

5.3 网络超时问题

优化方案：
- 调整Docker的--max-concurrent-downloads参数
- 在Harbor前端配置TCP keepalive
- 检查集群CNI插件（如Calico）的网络策略

六、总结与展望

通过HTTPS协议集成Harbor镜像仓库，KubeSphere用户可构建从开发到生产的全链路加密镜像管理体系。建议后续结合KubeSphere的DevOps工程实现镜像构建-扫描-推送的自动化流水线，并定期进行Harbor的存储清理和漏洞扫描。对于超大规模集群，可考虑使用Harbor的分布式部署模式提升并发处理能力。

本指南提供的配置方法已在KubeSphere v3.3.0+和Harbor v2.4.0+环境中验证通过，建议读者在实际部署前在测试环境完成完整验证流程。

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