高可用性

artifacthub-shim 可以在一个 Kubernetes Service 后运行多个 API 副本。 使用此模式可以提高读取可用性,并将 resolver/UI 流量分散到各个 pod。

HA 的含义

每个副本都是独立的读取服务器:

  • 它监视相同的仓库配置。
  • 它将目录源刷新到自己的源工作目录中。
  • 它构建并以原子方式发布自己的读取快照。已发布的快照不会就地修改;每次刷新都会用新构建的快照替换它,因此某个版本的内容可能会在刷新之间发生变化。
  • 只有在其首个快照就绪后,它才会处理请求。

此模型提供读取冗余和读取流量分配。它不提供 leader election、共享的运行时元数据索引或单个协调的源刷新器。在每个 pod 完成自己的刷新周期时,仓库更改可能会在不同副本上以略有不同的时间变得可见。

基线 HA 值

将此配置用于常规离线目录部署以及小型到中型自定义目录集:

replicaCount: 3

config:
  refreshInterval: 30m
  initialSyncTimeout: 5m
  repositoryEventDebounce: 5s
  maxConcurrentSources: 2
  enableConfigMapSources: true
  uiRBACCacheTTL: 60s
  kubeClientQPS: 50
  kubeClientBurst: 100

storage:
  contentStore:
    enabled: false

resources:
  requests:
    cpu: 200m
    memory: 512Mi
  limits:
    cpu: "1"
    memory: 1Gi

service:
  type: ClusterIP

该基线配置可简化 HA 部署:

  • 三个副本为集群内客户端提供冗余。
  • 更长的刷新间隔可减少各 pod 上重复的 Git 和索引负载。
  • maxConcurrentSources: 2 将每个 pod 的并发源加载数限制为两个。
  • UI RBAC 缓存和 Kubernetes 客户端限制可减少 UI 流量造成的重复 TokenReview 和 SubjectAccessReview 压力。
  • ContentStore 保持禁用状态,因此不需要共享运行时存储。
  • 资源基线为典型的离线目录部署中的刷新期间内存重叠留出了空间。
  • ClusterIP 使 Tekton resolver 和 DevOps UI 路径的流量保持在内部。

容量规划和负载模型

config.maxConcurrentSources 是每个 pod 的限制。在 HA 模式下,集群范围的 源刷新并发数约为:

replicaCount * config.maxConcurrentSources

对于基线值,在刷新周期期间,集群可能会同时加载约 3 * 2 = 6 个源。仅当刷新延迟确实成为问题,并且 Git 服务器、API 服务器、CPU、内存和磁盘 I/O 预算能够承受额外负载时,才应增加此值。

对于由 ConfigMap 支持的 Git 源,一个源表示 repository.yaml 中的一个嵌套 gitRepositories[].repositories[] 条目,而不是一个 ConfigMap 对象。单个 ConfigMap 可以声明多个对外可见的仓库,并且在刷新期间,每个条目都会作为独立源加载和建立索引。估算 HA 负载时,应统计所有带标签 ConfigMap 中的仓库条目总数。

请合理设置资源请求。基线 512Mi 内存请求和 1Gi 内存限制只是起始值,并不保证容量。每个副本都会构建自己的快照;在 ContentStore 禁用时,还会将清单和 README 有效负载保存在内存中。刷新期间,当前正在提供服务的快照和下一个快照可能会暂时同时保留在内存中。

对于包含许多由 ConfigMap 支持的 Git 源、大型 README 有效负载或禁用 ContentStore 的大型目录集,请使用更大的配置:

resources:
  requests:
    cpu: 500m
    memory: 1Gi
  limits:
    cpu: "2"
    memory: 2Gi

HA 中的仓库 ConfigMap

对于在运维上需要一起管理的条目,请使用多仓库 ConfigMap,例如来自同一 Git 仓库和团队的 task、pipeline 和 stepaction 路径。

避免将无关团队或高风险仓库放入同一个 ConfigMap。如果 ConfigMap 中的任何 gitRepositories[] 项或嵌套的 repositories[] 项无效,artifacthub-shim 会拒绝整个 ConfigMap 有效负载。将相互独立的仓库拆分到不同的 ConfigMap 中,可以限制错误 URL、无效路径、重复名称或凭证引用造成的影响范围。

选择存储模式

sourceWorkDir 存储已物化的源代码检出内容和 provider 缓存。将其设为持久化可以降低大型外部仓库源的 pod 重建成本,但它不会存储可直接提供服务的元数据索引。每个 pod 仍会获取或验证请求的修订版本、扫描源文件,并在就绪前重建自己的快照。在 HA 模式下,sourceWorkDir 必须保持 pod 本地,因为 Git 检出内容属于可变的运行时状态。

模式使用场景HA 行为
storage.sourceWorkDir.type=emptyDir默认 HA 部署。源重新加载成本可以接受。每个 pod 都有独立的本地工作目录。pod 重启时从空工作目录开始。
type=pvc单副本部署需要持久化的源工作目录。HA 不支持此模式。使用多个副本时,chart 会拒绝此模式。
type=existingPVC单副本部署提供预先创建的持久化源工作目录。HA 不支持此模式。使用多个副本时,chart 会拒绝此模式。

ContentStore 存储清单和 README 有效负载字节;它不会存储元数据索引,也不会协调副本。每个 pod 仍会构建并保留自己的元数据索引、软件包映射、搜索令牌、源状态和热有效负载缓存。

模式使用场景HA 行为
storage.contentStore.enabled=false默认 HA 部署。目录有效负载适合存放在内存中。每个 pod 都会将有效负载字节保留在自己的内存快照中,并可在重启后从源重新构建。
type=emptyDir有效负载字节造成可测量的内存压力,并且可以接受使用 pod 本地存储。每个 pod 都有独立的本地内容存储。pod 重启会丢失该本地有效负载缓存,然后在刷新时重新构建。
type=pvc需要由 chart 创建 PVC 的单副本部署。HA 不支持此模式。使用多个副本时,chart 会拒绝此模式。
type=existingPVC单副本部署提供预先创建的内容存储 PVC。HA 不支持此模式。使用多个副本时,chart 会拒绝此模式。

仅当以下条件全部满足时,才启用 ContentStore:

  • 配置了许多仓库,或清单/README 有效负载非常大。
  • 可以观察到 pod 内存压力,并且确认其由有效负载存储造成。
  • 可以接受额外存储配置带来的运维成本。

如果必须在多个副本的情况下启用 ContentStore,优先使用 pod 本地的 emptyDir:

replicaCount: 3

storage:
  contentStore:
    enabled: true
    type: emptyDir
    emptyDir:
      sizeLimit: 5Gi

避免在 HA 模式下使用由 PVC 支持的运行时存储。当 ContentStore 使用 pvc 或 existingPVC 时,chart 会拒绝 replicaCount>1。对于这些存储模式,请保留 replicaCount: 1:

replicaCount: 1

storage:
  contentStore:
    enabled: true
    type: pvc
    pvc:
      accessModes:
        - ReadWriteOnce

对于 existingPVC,请设置软限制,因为 chart 无法推断 claim 容量:

replicaCount: 1

storage:
  contentStore:
    enabled: true
    type: existingPVC
    maxBytes: 20Gi
    pvc:
      existingClaim: artifacthub-shim-content

运行检查清单

与 UI 兼容的端点使用共享的请求身份验证链。在 HA 模式下,授权缓存按 pod 分别维护,因此落到不同从节点的重复请求仍可能分别执行平台、OIDC 或 Kubernetes 审核。

启用或验证 HA 时,请使用以下检查清单:

  • 确认每个从节点都已达到 /readyz,然后再将 Service 视为已就绪,可 接收 resolver 或 UI 流量。
  • 通过 Kubernetes Service 进行负载测试,而不是连接到单个 pod。
  • 在初始同步和后台刷新期间,监控 Git server 负载、Kubernetes API 限流、CPU、内存和磁盘 I/O。
  • 对正常的 UI 流量保持 config.uiRBACCacheTTL 启用。仅当指标或日志显示 UI 列表/详情请求 存在客户端限流时,才增加 config.kubeClientQPS 和 config.kubeClientBurst。
  • 根据集群策略添加调度规则,使从节点分散到不同节点或可用区。

例如,使用 pod 反亲和性将从节点分散到不同节点:

affinity:
  podAntiAffinity:
    preferredDuringSchedulingIgnoredDuringExecution:
      - weight: 100
        podAffinityTerm:
          labelSelector:
            matchLabels:
              app.kubernetes.io/name: artifacthub-shim
          topologyKey: kubernetes.io/hostname

探针和初始同步

API server 会在初始源刷新完成之前启动。/healthz 报告进程存活状态,而 /readyz 仅在发布第一个 快照后返回成功。这使 Kubernetes 能够在大规模初始同步期间保持进程运行,同时让 Service 端点保持未就绪状态。首次刷新中的源级别 故障会作为快照中的源状态发布,而不是让 pod 一直处于未就绪状态。

chart 还提供可配置的 startupProbe、livenessProbe 和 readinessProbe 值。默认的 startupProbe 处于禁用状态,因为 server 会在初始刷新之前监听。以下情况可以启用它:环境中的镜像启动速度较慢、catalog init 容器启动较慢,或存储路径可能在进程开始监听之前造成延迟:

probes:
  startup:
    enabled: true
    failureThreshold: 30
    periodSeconds: 10