Harbor Instance Deployment

本文档介绍 Harbor Operator 的订阅，以及基于 Harbor 实例部署提供的功能。

Pod Security Admission Level Restrictions

Harbor 部署所需的 Pod Security Admission（PSA）级别取决于所使用的存储方式：

HostPath 存储：PSA 级别必须配置为 Privileged，因为在 Restricted 策略下不允许使用 hostPath 卷。
PVC 或 StorageClass 存储：Harbor 可以在 Restricted PSA 级别下部署。

各部署模板支持的 PSA 级别如下：

Deployment Template	Supported PSA Levels
Harbor Quick Start Template	Privileged
Harbor High Availability Template	Privileged, Baseline, Restricted
Harbor Object Storage Template	Privileged, Baseline, Restricted

前提条件

本文档适用于平台提供的 Harbor 2.14 及更高版本。它基于 Operator 等技术与平台解耦。
请确保 Harbor Operator 已在目标集群中完成部署（订阅），即 Harbor Operator 已准备好创建实例。

部署规划

Harbor 支持多种资源配置，以适应不同的客户场景。在不同场景下，所需的资源和配置可能存在较大差异。因此，本节介绍部署 Harbor 实例前进行部署规划时需要考虑的方面，以及各决策点带来的影响，帮助用户基于这些信息完成后续具体的实例部署。

基本信息

平台提供的 Harbor Operator 基于社区官方 Harbor Operator，并进行了 ARM 支持、安全漏洞修复等企业级能力增强。在功能方面与社区版本完全兼容；在使用体验方面，通过可选且可自定义的模板提升了 Harbor 部署的便利性。
一个 Harbor 实例包含多个组件，例如负责管理镜像文件的 Registry component、为应用元数据和用户信息提供存储的 PostgreSQL，以及用于缓存的 Redis 等。平台提供专业的 PostgreSQL Operator 和 Redis Operator，因此部署 Harbor 实例时不再直接部署 Redis 和 PostgreSQL 资源，而是通过为现有实例配置特定的访问凭据来访问它们。

部署前资源规划

部署前资源规划是指需要在部署前做出、并在部署期间生效的决策，主要包括以下内容：

高可用性

Harbor 支持高可用部署，主要影响和限制如下：
- 每个组件都将使用多个副本。
- 网络访问不再支持 NodePort，而是需要通过 Ingress 配置的域名访问。
- 存储方式不再支持 node storage，而是需要通过 StorageClass 或 PVC 访问。

资源

根据社区建议和实践，非高可用 Harbor 实例最低可使用 2 核和 4Gi 资源运行；在高可用模式下，需要至少 8 核和 16Gi 资源才能稳定运行。

存储

存储选择指南

组件	支持的存储类型	说明
Registry	对象存储（例如 MinIO）文件存储（例如 Ceph FS）	对于拉取镜像并发量较高的场景，建议使用对象存储并启用重定向功能。存储磁盘的顺序读写吞吐量（块大小为 1 MB）不应低于 100 MiB/s。
JobService	文件存储（例如 Ceph FS）	作业日志也可以存储在数据库中，此时无需为作业服务配置存储。
Trivy	文件存储（例如 Ceph FS）	用于存储漏洞数据库和缓存；持久化是可选的。未启用持久化时，将回退到 `emptyDir`，因此重启后会重新下载数据库，并暂时停止扫描。

平台提供的常见存储方式都可用于 Harbor，例如存储类、持久卷声明、节点存储等。
如需有意跳过 Trivy 持久化，请不要设置 spec.helmValues.persistence.persistentVolumeClaim.trivy.storageClass。此时漏洞数据库将存放在 emptyDir 卷中，因此每次 Trivy Pod 重启都会触发完整的数据库下载，并在下载完成前阻塞漏洞扫描。
节点存储不适用于 high availability 模式，因为它会将文件存储在主机节点上指定的路径中。
此外，Harbor 支持对象存储。配置说明请参见使用对象存储作为 Registry 存储后端。

不要使用 NFS 作为存储后端

在 生产环境或高负载场景（例如大规模镜像推送/拉取操作或高并发镜像负载）中，不建议使用 NFS 作为 Harbor 的存储后端。由于协议本身的特性，NFS 无法完全满足 Harbor Registry 对元数据密集型操作的要求。在高负载下，这通常会导致制品上传失败，并可能出现以下错误：

digest invalid: provided digest did not match uploaded content
blob upload unknown
blob upload invalid

如果仍希望在测试环境中使用 NFS 作为 Harbor 的存储后端，可以在 NFS 服务器上启用 sync 和 no_wdelay（有关配置详情，请咨询存储提供商），并将 Registry 组件的副本数设置为 1，以帮助缓解上述问题。

网络

平台提供以下网络访问方式：
- NodePort 需要指定 HTTP 端口和 SSH 端口，并确保端口可用。NodePort 不适用于 high availability 模式。
- Ingress 需要指定域名，并确保域名解析正常。
- Envoy Gateway（Gateway API）需要域名、现有的 Envoy Gateway 部署，以及一个根据 Envoy Gateway GatewayClass 创建的 Gateway 资源。它同时支持标准部署和高可用部署。详情请参见 Envoy Gateway 访问（YAML 片段）和使用 Envoy Gateway 暴露 Harbor。
平台支持 HTTPS 协议，需要在实例部署后进行配置。详情请参见配置 HTTPS。

Redis

Redis 组件存储选择指南

建议使用块存储（例如 TopoLVM），以获得更高的 IOPS 和更低的延迟。

Harbor 当前依赖的 Redis 组件版本为 v6。建议使用平台提供的 Redis Operator 部署 Redis 实例，然后通过配置访问凭据完成 Redis 集成。
- Redis 访问通过配置包含特定格式内容的 secret 资源实现。详情请参见配置 Redis、PostgreSQL 和账户访问凭据。
- Harbor 支持连接启用 TLS 的外部 Redis。配置示例请参见TLS Redis 示例。
已知问题：修改 Harbor 项目权限时提示内部服务器错误

PostgreSQL

PostgreSQL 组件存储选择指南

建议使用块存储（例如 TopoLVM），以获得更高的 IOPS 和更低的延迟。

支持的 PostgreSQL 版本请参见版本兼容性矩阵。建议使用平台提供的 PostgreSQL Operator 部署 PostgreSQL 实例，然后通过配置相应的访问凭据集成 PostgreSQL。
- PostgreSQL 访问通过配置包含特定格式内容的 secret 资源实现。详情请参见配置 Redis、PostgreSQL 和账户访问凭据。

账户凭据

初始化 Harbor 实例时，需要配置管理员账户及其密码。此操作通过配置 secret 资源完成。详情请参见配置 Redis、PostgreSQL 和账户访问凭据。

部署后配置规划

部署后配置规划是指无需在部署前决策、但可以在部署后通过标准化操作按需更改的规划，主要包括单点登录（SSO）、HTTPS 配置、外部负载均衡器配置等。详情请参见后续操作。

实例部署

平台提供的 Harbor Operator 主要提供两种部署方式：从模板部署和从 YAML 部署。

平台为常见场景提供了内置模板：Harbor Quick Start 模板、Harbor High Availability 模板、Harbor Object Storage 模板和 Harbor High Availability (Envoy Gateway) 模板，同时支持自定义模板以满足特定客户场景。

内置模板和 YAML 部署的信息如下：

从 `Harbor Quick Start` 模板部署

此模板用于快速创建轻量级 Harbor 实例，适用于开发和测试场景，不建议用于生产环境。

计算资源：CPU 2 核，内存 4Gi
存储方式：使用本地节点存储，需要配置存储节点 IP 和路径
网络访问：使用 NodePort 方式，与存储共享节点 IP，需要指定端口
依赖服务：需要配置现有 Redis 和 PostgreSQL 的访问凭据
其他设置：需要配置账户凭据，SSO 功能默认禁用

根据模板提示填写相关信息即可完成部署。

从 `Harbor High Availability` 模板部署

部署高可用 Harbor 实例需要更高的资源配置，并提供更高的可用性标准。

计算资源：CPU 16 核，内存 16 Gi
存储方式：使用存储类资源存储镜像文件、后台任务日志和镜像扫描漏洞数据库
网络访问：使用 Ingress 方式，需要指定域名
依赖服务：需要配置现有 Redis 和 PostgreSQL 的访问凭据
其他设置：需要配置账户凭据，SSO 功能默认禁用

要实现 Harbor 高可用，外部依赖必须满足以下条件：

Redis 和 PostgreSQL 实例必须具备高可用性
网络负载均衡器必须具备高可用性；使用 ALB 时，必须配置 VIP
集群节点数必须超过 2 个

根据模板提示填写相关信息即可完成部署。

对于通过 Envoy Gateway（Gateway API）暴露外部流量的环境，平台还提供 Harbor High Availability (Envoy Gateway) 模板。该模板部署相同的高可用拓扑，并通过附加到用户创建的 Gateway 的 HTTPRoute 暴露实例。配置说明请参见使用 Envoy Gateway 暴露 Harbor。

从 `Harbor Object Storage` 模板部署

基于对象存储部署 Harbor 实例。

计算资源：CPU 8 核，内存 16 Gi
存储：镜像文件使用对象存储，后台任务日志使用数据库存储
网络访问：使用 Ingress 访问服务，并指定域名
依赖服务：配置现有 Redis 和 PostgreSQL 的访问凭据
其他设置：配置账户凭据，SSO 功能默认禁用

此模板中的 Trivy 扫描器不持久化数据，而是挂载 emptyDir，因此每次 Pod 重启都会重新下载漏洞数据库，并在同步完成前暂时阻塞新的扫描。

请确认提供的对象存储凭据满足所需的 S3 API 权限，详见对象存储凭据。

根据模板提示填写相关信息即可完成部署。

从 YAML 部署

YAML 部署是最基础且功能最强大的部署能力。本节针对 Deployment Planning 部分的各个维度提供相应的 YAML 片段，并提供两个完整场景的 YAML 示例，帮助用户了解 YAML 配置方式并按需进行配置变更。

高可用（YAML 片段）

在高可用模式下，Harbor 组件副本数至少应为 2。YAML 配置片段如下：

spec:
  helmValues:
    core:
      replicas: 2
    portal:
      replicas: 2
    jobservice:
      replicas: 2
    registry:
      replicas: 2

存储（YAML 片段）

Harbor 数据存储主要包括以下三个部分：

Registry：管理和存储容器镜像及制品，处理镜像上传、下载和存储操作。
Jobservice：执行 Registry 之间的镜像复制、垃圾回收以及其他定时或按需执行的后台任务。
Trivy：对容器镜像执行漏洞扫描，以识别安全问题并确保符合安全策略。

目前支持三种存储配置方式：存储类、PVC 和本地节点存储。使用存储类或 PVC 时，存储必须支持多节点读写（ReadWriteMany）。

对于 Registry，还可以使用对象存储（S3）作为存储后端。

Jobservice 支持将作业日志存储在多个位置（文件、数据库、stdout）。如果未选择将 Jobservice 日志输出到文件，则无需为 Jobservice 配置存储后端。详情请参见配置作业日志存储。

存储类配置片段：

spec:
  helmValues:
    persistence:
      enabled: true
      persistentVolumeClaim:
        registry:
          storageClass: ceph
          accessMode: ReadWriteMany
          size: 10Gi
        jobservice:
          jobLog:
            storageClass: ceph
            accessMode: ReadWriteMany
            size: 1Gi
        trivy:
          storageClass: ceph
          accessMode: ReadWriteMany
          size: 5Gi

PVC 配置片段（需要提前创建 PVC）：

spec:
  helmValues:
    harbor:
      persistence:
        enabled: true
        persistentVolumeClaim:
          registry:
            existingClaim: <registry component pvc>
          jobservice:
            jobLog:
              existingClaim: <jobservice component pvc>
          trivy:
            existingClaim: <trivy component pvc>

本地节点存储配置片段：

spec:
  helmValues:
    persistence:
      enabled: true
      hostPath:
        registry:
          path: <registry component node storage path>
        jobservice:
          path: <jobservice component node storage path>
        trivy:
          path: <trivy component node storage path>
    registry:
      nodeSelector:
        kubernetes.io/hostname: <node name>
    jobservice:
      nodeSelector:
        kubernetes.io/hostname: <node name>
    trivy:
      nodeSelector:
        kubernetes.io/hostname: <node name>

将对象存储（S3）配置为 Registry 存储后端：

使用 Amazon S3 或 S3 兼容服务作为对象存储，例如 MinIO、Ceph。
必须提前创建对象存储存储桶。

必须提前创建 <object-storage-secret> Secret。

spec:
  helmValues:
    harbor:
      persistence:
        enabled: true
        imageChartStorage:
          disableredirect: true
          s3:
            existingSecret: <object-storage-secret>
            bucket: <bucket>
            region: <region>
            regionendpoint: <regionendpoint>
            v4auth: true
          type: s3
        persistentVolumeClaim:
          jobservice:
            jobLog:
              existingClaim: <jobservice component pvc>
          trivy:
            existingClaim: <trivy component pvc>

字段	说明	示例值
object-storage-secret	包含 S3 访问密钥和密钥的 Secret，详情请参见对象存储凭据	`object-storage-secret`
bucket	对象存储存储桶名称，必须提前创建	`harbor-registry`
regionendpoint	对象存储服务的端点 URL（如有需要，请包含端口）	`http://192.168.133.37:32227`
region	对象存储的区域（对于 MinIO，通常为 `us-east-1`）	`us-east-1`
disableredirect	设置为 false 可启用重定向并提升拉取性能。Harbor 将为层返回临时 S3 URL，因此客户端必须能够访问 S3 端点，否则层下载会失败	`true`

更多详情请参见 S3 storage driver

如果要在平台中使用 Ceph，请参见 Ceph Distributed Storage。

INFO

Harbor 目前仅支持将 Registry 组件配置为使用 S3 存储。其他组件将继续使用 PVC 或 StorageClass 进行持久化存储。

网络访问（YAML 片段）

网络访问主要包括两种方式：域名访问和 NodePort 访问。

域名访问配置片段：

spec:
  helmValues:
    expose:
      type: ingress
      tls:
        enabled: false
      ingress:
        hosts:
          core: <domain name>

    externalURL: http://<domain name>

NodePort 访问配置片段：

spec:
  helmValues:
    expose:
      type: nodePort
      nodePort:
        name: harbor
        ports:
          http:
            port: 80
            nodePort: <port number>

    externalURL: http://<node IP>:<port number>

Envoy Gateway（Gateway API）访问配置

Envoy Gateway 通过 HTTPRoute（Gateway API）暴露 Harbor 实例。当 expose.type 设置为 route 时，Harbor Helm Chart 会原生生成 HTTPRoute。Gateway 由用户创建，Envoy Gateway 或 Harbor 都不会创建，且必须在部署 Harbor 之前存在。

步骤 1：在创建 Gateway 的命名空间中创建 TLS 证书 Secret（Secret 和 Gateway 必须位于同一命名空间）：

apiVersion: v1
kind: Secret
metadata:
  name: harbor-gateway-tls
  namespace: <gateway namespace>
type: kubernetes.io/tls
data:
  tls.crt: <base64 encoded cert>
  tls.key: <base64 encoded key>

步骤 2：创建 Gateway（通过 Web 控制台或 YAML）。选择由平台 Envoy Gateway Operator 生成的 GatewayClass（例如 envoy-gateway-operator-cpaas-default；在 Alauda Container Platform 4.3 及更高版本中，请通过平台的 Envoy Gateway Operator 安装 Envoy Gateway，该 Operator 会自动生成 GatewayClass）：

apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: harbor-gateway
  namespace: <gateway namespace>
spec:
  gatewayClassName: envoy-gateway-operator-cpaas-default
  listeners:
    - name: https
      protocol: HTTPS
      port: 443
      tls:
        mode: Terminate
        certificateRefs:
          - kind: Secret
            name: harbor-gateway-tls
      allowedRoutes:
        namespaces:
          from: Same # or All / Selector for cross-namespace routes

步骤 3：使用 Envoy Gateway 访问片段配置 Harbor：

spec:
  helmValues:
    expose:
      type: route
      tls:
        enabled: false
      route:
        parentRefs:
          - name: <gateway name>
            namespace: <gateway namespace>
            sectionName: https
            group: gateway.networking.k8s.io
            kind: Gateway
        hosts:
          - <domain name>

    externalURL: https://<domain name>

注意：

上述示例中的 Gateway 与 Harbor 实例位于同一命名空间，因此无需 ReferenceGrant。对于跨命名空间 Gateway，监听器必须允许 Harbor 命名空间，并且必须在 Gateway 所在的命名空间中创建 ReferenceGrant；完整指南请参见使用 Envoy Gateway 暴露 Harbor。
对于 route 暴露类型，TLS 在 Gateway 监听器处终止，而不是由 Harbor 终止。请在 Gateway 所在的命名空间中创建 TLS 证书 Secret，并在 Gateway 监听器中引用该证书。请参见下文的使用 Envoy Gateway 配置 HTTPS。
Gateway 必须在部署 Harbor 实例之前存在；Harbor 的 HTTPRoute 通过 parentRefs 附加到该资源。如果 Gateway 不存在，HTTPRoute 将不会被接受，Harbor 实例也将无法访问。

Redis 访问凭据配置

这是在配置 Redis 凭据 secret 资源后，Harbor 实例中用于配置这些凭据的片段：

独立实例示例：

spec:
  helmValues:
    database:
    redis:
      external:
        addr: "<redis access address>:<redis port>"
        existingSecret: <secret storing redis password>
        existingSecretKey: password
      type: external

Sentinel 示例：

spec:
  helmValues:
    database:
    redis:
      external:
        addr: "<sentinel1 access address>:<sentinel1 port>,<sentinel2 access address>:<sentinel2 port>,<sentinel3 access address>:<sentinel3 port>"
        sentinelMasterSet: mymaster
        existingSecret: <secret storing redis password>
        existingSecretKey: password
      type: external

TLS Redis 示例

apiVersion: v1
kind: Secret
metadata:
  name: redis-ca-bundle
type: Opaque
stringData:
  ca.crt: |
    -----BEGIN CERTIFICATE-----
    <redis server root ca>
    -----END CERTIFICATE-----
---
spec:
  helmValues:
    caBundleSecretName: redis-ca-bundle
    redis:
      external:
        addr: "<redis access address>:<redis tls port>"
        existingSecret: <secret storing redis password>
        existingSecretKey: password
        tlsOptions:
          enable: true
      type: external

TLS Redis 注意事项：

caBundleSecretName 是全局 Harbor Helm 值。引用的 Secret 必须包含名为 ca.crt 的键。
对于启用 TLS 的 Redis Sentinel，继续使用 redis.external.addr 中的 Sentinel 地址，设置 redis.external.sentinelMasterSet，并启用 redis.external.tlsOptions.enable: true。
Harbor 仅支持 Redis TLS 的服务器证书验证，不支持客户端证书。
当前不支持通过 TLS 将 Harbor 连接到 Alauda Cache Service for Redis OSS。

PostgreSQL 访问凭据配置

这是在配置 PostgreSQL 凭据 secret 资源后，Harbor 实例中用于配置这些凭据的片段：

spec:
  helmValues:
    database:
      external:
        host: <postgresql access address>
        port: <postgresql port>
        sslmode: <whether to enable ssl>
        username: <postgresql username>
        coreDatabase: <database name>
        existingSecret: <secret storing postgresql password>
      type: external

管理员账户配置

这是在配置账户凭据 secret 资源后，Harbor 实例中用于配置这些凭据的片段：

spec:
  helmValues:
    existingSecretAdminPassword: <secret storing harbor admin password>
    existingSecretAdminPasswordKey: password

完整 YAML 示例：单实例、节点存储、NodePort 网络访问


spec:
  helmValues:
    existingSecretAdminPassword: harbor-password # Secret storing harbor admin account password
    existingSecretAdminPasswordKey: password # Secret key storing harbor admin account password
    externalURL: http://192.168.142.11:32001 # Harbor access address
    expose:
      nodePort:
        name: harbor
        ports:
          http:
            nodePort: 32001 # Harbor node port number
            port: 80
      type: nodePort
    persistence:
      enabled: true
      hostPath:
        jobservice:
          path: /data/harbor/jobservice # Jobservice component node storage path
        registry:
          path: /data/harbor/registry # Registry component node storage path
        trivy:
          path: /data/harbor/trivy # Trivy component node storage path
    portal:
      resources:
        request:
          cpu: 100m
          memory: 128Mi
        limit:
          cpu: 200m
          memory: 256Mi
    nginx:
      resources:
        request:
          cpu: 100m
          memory: 128Mi
        limit:
          cpu: 200m
          memory: 256Mi
    core:
      resources:
        request:
          cpu: 200m
          memory: 256Mi
        limit:
          cpu: 400m
          memory: 512Mi
    registry:
      nodeSelector:
        kubernetes.io/hostname: 192.168.142.11 # Registry component node selector
      resources:
        request:
          cpu: 200m
          memory: 512Mi
        limit:
          cpu: 400m
          memory: 1Gi
    jobservice:
      nodeSelector:
        kubernetes.io/hostname: 192.168.142.11 # Jobservice component node selector
      resources:
        request:
          cpu: 200m
          memory: 256Mi
        limit:
          cpu: 400m
          memory: 512Mi
    trivy:
      skipUpdate: true
      offlineScan: true
      nodeSelector:
        kubernetes.io/hostname: 192.168.142.11 # Trivy component node selector
      resources:
        request:
          cpu: 200m
          memory: 512Mi
        limit:
          cpu: 400m
          memory: 1Gi
    database:
      external:
        host: harbor-database # Database access address
        port: 5432 # Database port number
        sslmode: require # Whether to enable SSL
        username: harbor # Database username
        coreDatabase: registry # Database name
        existingSecret: harbor-database # Secret storing database password
        existingSecretKey: password # Secret key storing database password
      type: external
    redis:
      external:
        addr: harbor-redis:6379 # Redis access address and port number
        existingSecret: harbor-redis # Secret storing Redis password
        existingSecretKey: password # Secret key storing Redis password
      type: external

完整 YAML 示例：高可用、存储类、Ingress 网络访问

spec:
  helmValues:
    existingSecretAdminPassword: harbor-password # Secret storing harbor admin account password
    existingSecretAdminPasswordKey: password # Secret key storing harbor admin account password
    externalURL: http://harbor.example.com # Harbor access address
    expose:
      type: ingress
      tls:
        enabled: false
      ingress:
        hosts:
          core: harbor.example.com # Harbor domain name
    persistence:
      enabled: true
      persistentVolumeClaim:
        registry:
          storageClass: ceph # Registry component storage class
          accessMode: ReadWriteMany
          size: 10Gi # Registry component storage size
        jobservice:
          jobLog:
            storageClass: ceph # Jobservice component storage class
            accessMode: ReadWriteMany
            size: 1Gi # Jobservice component storage size
        trivy:
          storageClass: ceph # Trivy component storage class
          accessMode: ReadWriteMany
          size: 5Gi # Trivy component storage size
    portal:
      replicas: 2 # Portal component replicas
      resources:
        request:
          cpu: 200m
          memory: 256Mi
        limit:
          cpu: 400m
          memory: 512Mi
    core:
      replicas: 2 # Core component replicas
      resources:
        request:
          cpu: 200m
          memory: 256Mi
        limit:
          cpu: 400m
          memory: 512Mi
    registry:
      replicas: 2 # Registry component replicas
      resources:
        request:
          cpu: 400m
          memory: 1Gi
        limit:
          cpu: 800m
          memory: 2Gi
    jobservice:
      replicas: 2 # Jobservice component replicas
      resources:
        request:
          cpu: 200m
          memory: 256Mi
        limit:
          cpu: 400m
          memory: 512Mi
    trivy:
      skipUpdate: true
      offlineScan: true
      resources:
        request:
          cpu: 400m
          memory: 1Gi
        limit:
          cpu: 800m
          memory: 2Gi
    database:
      external:
        host: harbor-database # Database access address
        port: 5432 # Database port number
        sslmode: require # Whether to enable SSL
        username: harbor # Database username
        coreDatabase: registry # Database name
        existingSecret: harbor-database # Secret storing database password
        existingSecretKey: password # Secret key storing database password
      type: external
    redis:
      external:
        addr: harbor-redis:6379 # Redis access address and port number
        existingSecret: harbor-redis # Secret storing Redis password
        existingSecretKey: password # Secret key storing Redis password
      type: external

后续操作

配置单点登录（SSO）

WARNING

仅当数据库中尚未添加本地用户时，才能将认证模式从数据库更改为 OIDC。如果 Harbor 数据库中至少存在一个 admin 以外的用户，则无法更改认证模式。

详情请参见：配置 OIDC Provider 认证

配置 SSO 包括以下步骤：

在 global 集群中注册 SSO 认证客户端
准备 SSO 认证配置
配置 Harbor 实例使用 SSO 认证

在 global 集群中创建以下 OAuth2Client 资源，以注册 SSO 认证客户端：

apiVersion: dex.coreos.com/v1
kind: OAuth2Client
name: OIDC
metadata:
  name: nbqxeytpoiwwizlyzpzjzzeeeirsk # This value is calculated based on the hash of the id field, online calculator: https://go.dev/play/p/QsoqUohsKok
  namespace: cpaas-system
alignPasswordDB: true
id: harbor-dex # Client id
public: false
redirectURIs:
  - <harbor access address>/c/oidc/callback
secret: Z2l0bGFiLW9mZmljaWFsLTAK # Client secret
spec: {}

Field	Description	Example
name	The display name of the resource.	OIDC
id	The client ID used for SSO authentication. Can be set to any value. `id` can not set as `alauda-dex`, this is a reserved value that may cause conflicts.	harbor-dex
secret	The client secret used for SSO authentication. Can be set to any value.	Z2l0bGFiLW9mZmljaWFsLTAK
metadata.name	The resource name, which must be calculated based on the hash of the `id` field. You can use online hash calculators such as https://go.dev/play/p/QsoqUohsKok to generate it.	nbqxeytpoiwwizlyzpzjzzeeeirsk
redirectURIs	The third-party product URL. Harbor requires the format: `<harbor access address>/c/oidc/callback`	https://harbor.com/c/oidc/callback
metadata.namespace	The platform system namespace. Defaults to `cpaas-system`.	cpaas-system

编辑 Harbor 实例，添加以下配置：

spec:
  helmValues:
    oidc:
      enable: true
      clientID: "harbor-dex"
      clientSecret: "Z2l0bGFiLW9mZmljaWFsLTAK"
      issuer: "<platform access address>/dex"

配置 HTTPS

部署 Harbor 实例后，可以根据需要配置 HTTPS。

首先，在实例所在的命名空间中创建 TLS 证书 Secret：

apiVersion: v1
kind: Secret
metadata:
  name: harbor-tls-cert
  namespace: harbor
type: kubernetes.io/tls
data:
  tls.crt: <base64 encoded cert>
  tls.key: <base64 encoded key>

然后编辑 Harbor 实例的 YAML 配置，以启用 HTTPS 访问：

expose:
  type: ingress
  tls:
    enabled: true
    certSource: secret
    secret:
      secretName: harbor-tls-cert
  ingress:
    hosts:
      core: <domain name>

externalURL: https://<domain name>

使用 Envoy Gateway 配置 HTTPS

当 Harbor 实例通过 Envoy Gateway（expose.type: route）暴露时，TLS 在 Gateway 监听器处终止，而不是在 Harbor 处终止。请按以下步骤配置 TLS：

在 Gateway 所在的命名空间中创建 TLS 证书 Secret（必须与 Gateway 位于同一命名空间）：

apiVersion: v1
kind: Secret
metadata:
  name: <gateway-tls-cert>
  namespace: <gateway namespace>
type: kubernetes.io/tls
data:
  tls.crt: <base64 encoded cert>
  tls.key: <base64 encoded key>

在 Gateway 的 HTTPS 监听器中引用该证书：

apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: <gateway name>
  namespace: <gateway namespace>
spec:
  gatewayClassName: <envoy gateway gatewayclass name>
  listeners:
    - name: https
      protocol: HTTPS
      port: 443
      tls:
        mode: Terminate
        certificateRefs:
          - kind: Secret
            name: <gateway-tls-cert>
      allowedRoutes:
        namespaces:
          from: Same # or All / Selector for cross-namespace routes

Harbor 实例本身使用 externalURL: https://<domain name>；在 Harbor 层保持 expose.tls.enabled 为 false，因为在此模式下 Harbor 的 Nginx 不会终止 TLS：

spec:
  helmValues:
    expose:
      type: route
      tls:
        enabled: false
      route:
        parentRefs:
          - name: <gateway name>
            namespace: <gateway namespace>
            sectionName: https
            group: gateway.networking.k8s.io
            kind: Gateway
        hosts:
          - <domain name>

    externalURL: https://<domain name>

证书续期后，请更新所引用的 Secret；Gateway 监听器会获取新证书，无需重新部署 Harbor。

配置镜像扫描漏洞数据库策略

Harbor 的镜像扫描功能由 Trivy 组件实现。考虑到用户的网络环境，该组件默认使用内置的离线漏洞数据库策略。由于漏洞数据库不会更新，因此无法及时检测新漏洞。

如果希望保持漏洞数据库最新，可以编辑 Harbor 实例的 YAML 配置以启用在线更新策略（此策略需要能够访问 GitHub）：

trivy:
  skipUpdate: false
  offlineScan: false

启用在线更新策略后，Trivy 会根据上次更新时间，在扫描前判断是否需要更新漏洞数据库。由于下载漏洞数据库需要一定时间，如果不需要 Java 漏洞扫描，也可以编辑 Harbor 实例的 YAML 配置，禁用 Java 漏洞数据库更新：

trivy:
  skipJavaDBUpdate: true

如果继续使用离线数据库流程，并且 init-offline-db 初始化容器在解压数据库时发生 OOM，可以单独增加仅供初始化容器使用的资源，而不改变 Trivy 主运行时容器的资源：

trivy:
  offlineScan: true
  offlineDBInitResources:
    requests:
      cpu: 200m
      memory: 512Mi
    limits:
      cpu: 1
      memory: 2Gi

此设置仅影响 Pod 初始化期间的初始化容器，不会增加 Trivy 主容器稳定运行时的资源限制。

其他信息

在 IPv6 环境中部署 Harbor

Harbor 支持在 IPv6 环境中部署，但需要确保客户端工具的版本支持 IPv6。如果遇到 invalid reference format 错误，请检查客户端工具版本是否支持 IPv6。

Harbor Instance Deployment#

#目录

#前提条件

#部署规划

#基本信息

#部署前资源规划

#部署后配置规划

#实例部署

#从 Harbor Quick Start 模板部署

#从 Harbor High Availability 模板部署

#从 Harbor Object Storage 模板部署

#从 YAML 部署

#高可用（YAML 片段）

#存储（YAML 片段）

#网络访问（YAML 片段）

#Envoy Gateway（Gateway API）访问配置

#Redis 访问凭据配置

#TLS Redis 示例

#PostgreSQL 访问凭据配置

#管理员账户配置

#完整 YAML 示例：单实例、节点存储、NodePort 网络访问

#完整 YAML 示例：高可用、存储类、Ingress 网络访问

#后续操作

#配置单点登录（SSO）

#配置 HTTPS

#使用 Envoy Gateway 配置 HTTPS

#配置镜像扫描漏洞数据库策略

#其他信息

#在 IPv6 环境中部署 Harbor

Harbor Instance Deployment

目录

前提条件

部署规划

基本信息

部署前资源规划

部署后配置规划

实例部署

从 `Harbor Quick Start` 模板部署

从 `Harbor High Availability` 模板部署

从 `Harbor Object Storage` 模板部署

从 YAML 部署

高可用（YAML 片段）

存储（YAML 片段）

网络访问（YAML 片段）

Envoy Gateway（Gateway API）访问配置

Redis 访问凭据配置

TLS Redis 示例

PostgreSQL 访问凭据配置

管理员账户配置

完整 YAML 示例：单实例、节点存储、NodePort 网络访问

完整 YAML 示例：高可用、存储类、Ingress 网络访问

后续操作

配置单点登录（SSO）

配置 HTTPS

使用 Envoy Gateway 配置 HTTPS

配置镜像扫描漏洞数据库策略

其他信息

在 IPv6 环境中部署 Harbor