#Chart 配置

本文档描述了 artifacthub-shim 的通用 Helm values。该 Chart 的默认配置针对轻量级、离线友好的安装进行了优化，内置 Tekton catalog，且不使用持久化运行时存储。

完整的 value schema 以 charts/artifacthub-shim/values.yaml 为准。下面各节重点介绍运维人员最常覆盖的 values。

#基础设置

#内置 catalog

当 catalog.enabled=true 且 config.sources 为空时，进程会在 catalog root 下为 task 和 pipeline 创建默认 sources。只有当打包的 catalog 包含 stepaction/ 目录时，才会创建可选的 catalog-stepactions source。仅提供自定义静态 sources 或仅提供基于 ConfigMap 的 Git repository sources 时，请设置 catalog.enabled=false。

#Extension webhook

artifacthub-shim-extension 是与 API server 分离的独立 Deployment。它不提供 Artifact Hub APIs；它托管 catalog 集成所使用的 admission webhook 能力。第一个启用的能力是为携带已配置 template-render 参数的 TaskRun 提供模板渲染。

ResolutionRequest policy 不会读取 hubresolver-config，也不会发现 resolver Deployment。它会跳过显式使用 Tekton Hub 的请求，并在本地 shim index 上审查显式 Artifact Hub 请求，以及省略 type 的请求。没有显式 catalog、kind、name 或 version 参数的请求会 fail open，因为 webhook 无法安全地重建 resolver 默认值。

当 extension.webhook.certManager.enabled=true 时，目标集群必须已安装 cert-manager。如果证书管理由外部提供，请将 extension.webhook.certManager.enabled=false，并通过 extension.webhook.certManager.secretName 提供已配置的 webhook 证书 Secret 名称。API 和 extension 的 Deployment 都使用根级别的 nodeSelector、tolerations、affinity 和 priorityClassName 调度值。

#运行时刷新与 repository 发现

#日志

该 Chart 默认以 info 级别写入 JSON 日志。高级 zap 文件配置请参见 Logging。

#UI API RBAC

该 Chart 授予 API ServiceAccount 读取 kube-public/global-info 以及创建 TokenReview 和 SubjectAccessReview 对象的权限。进程通过共享的 requestauth 流程保护与 UI 兼容的 endpoints：

• /api/v1alpha1/{tasks,pipelines,stepactions} 下的 GET 和 POST collection endpoints 需要 list hub.tekton.dev/resources。当提供 namespace 时，SubjectAccessReview 会针对该 Namespace，且作用域过滤会在分页或 batch 聚合之前进行。
• /api/v1alpha1/{catalog}/{kind}/{name}[/version] 下的 detail endpoints，以及 /v1/resource/{catalog}/{kind}/{name}/{version}/yaml 下的原始 manifest URL，需要 get hub.tekton.dev/resources。隐藏的 catalog 会返回 404，并且生成的链接会保留 namespace 查询参数。
• 当启用 platform authentication 且 platformURL 和 clusterName 直接配置或从 kube-public/global-info 发现时，会首先尝试 platform authentication。它会将请求 bearer token 发送到 {platformURL}/kubernetes/{clusterName}，并使用 platform SelfSubjectReview 和 SelfSubjectAccessReview。
• 只有当 config.authentication.oidc.enabled=true 时，才会进行显式 OIDC 验证。通过 OIDC 认证的用户会使用当前集群的 SubjectAccessReview 进行授权。
• 当 config.authentication.kubernetesFallback=true 时，会最后尝试当前集群的 Kubernetes TokenReview 回退，返回的用户会使用当前集群的 SubjectAccessReview 进行授权。
• 该进程不会仅通过解码未签名的 Dex/JWT payload 来接受 token；token 必须被已配置的共享 backend 之一接受。
• /api/v1/packages/... 下与 resolver 兼容的 Artifact Hub endpoints 仍然不需要认证，因此 Tekton hub resolver 可以继续在没有最终用户 token 的情况下调用它们。

平台认证不需要注入 Erebus 或 KUBERNETES_SERVICE_HOST 环境变量。如果 Hub UI Ingress 必须使用 global-cluster IngressClass，请将 config.globalCluster.enabled=true，或者显式设置 hubIngress.className。

#运行时存储

sourceWorkDir 用于存储已 materialize 的 repository sources 和 provider cache。对于当前基于 ConfigMap 的 Git sources，这里会在刷新之间保留 checkout。持久化它可以通过避免完整重新 clone 来降低 pod 重建成本。在启动后的第一次刷新期间，基于 PVC 的 workdir 可以在无需等待网络 fetch 的情况下提供有效的持久化 checkout；后续刷新仍会执行 fetch、checkout 请求的 revision、扫描 source 文件，并重建内存中的 metadata index。

基于 PVC 的 sourceWorkDir 存储仅支持单 Replica 部署。对于多个 Replica，请使用 emptyDir，以便每个 pod 都拥有独立的 checkout 目录。

ContentStore 是可选存储，用于保存不可变的 Tekton manifest 和 README payload。它按 digest 存储 payload 字节。它不是 metadata index：package index、version 查找映射、search token 和 source 状态仍然为每个 pod 在内存中构建。

默认值为 storage.contentStore.enabled=false，此时 manifest 和 README payload 会保留在内存快照中。这是最简单的模式，适用于内置 catalog 和较小的自定义 catalog 集合。

对于多 Replica 部署，除非存在经过测量的内存问题，否则请保持 ContentStore 关闭。如果必须在多个 Replica 下启用它，请优先使用 emptyDir，以便每个 pod 都拥有独立的本地 payload 存储。基于 PVC 的运行时存储仅支持单 Replica。

当 sourceWorkDir 或已启用的 ContentStore 使用基于 PVC 的存储时，Chart 会将 Deployment 渲染为 strategy.type: Recreate，以避免升级期间旧 pod 和新 pod 同时写入同一运行时存储。

#Cache 和 payload 限制

#网络暴露

#资源与调度

#扩展点

#示例：最小化离线安装

这会保持内置 catalog 启用，并将 manifest/README payload 保留在内存快照中。

global:
  registry:
    address: registry.example.com/alauda
  images:
    api:
      repository: devops/artifacthub-shim/artifacthub-shim-api
      tag: v0.1.0
    extension:
      repository: devops/artifacthub-shim/artifacthub-shim-extension
      tag: v0.1.0
    catalog:
      repository: devops/tektoncd/hub/catalog
      tag: v0.1.0

catalog:
  enabled: true
  extraResources:
    enabled: true
    path: config

config:
  extraResourceSync:
    enabled: true
    allowedNamespaces:
      - kube-public
    leaderElection:
      enabled: true

storage:
  contentStore:
    enabled: false

service:
  type: ClusterIP

extension:
  enabled: true

#示例：外部访问

当测试客户端或外部集成必须直接访问服务时，请使用以下模式之一。

service:
  type: NodePort
  nodePort: 30080

service:
  type: ClusterIP

ingress:
  enabled: true
  className: nginx
  hosts:
    - host: artifacthub-shim.example.com
      paths:
        - path: /
          pathType: Prefix
  tls:
    - secretName: artifacthub-shim-tls
      hosts:
        - artifacthub-shim.example.com

#示例：持久化 source workdir

当单 Replica 部署使用大型外部 repository sources，且完整重新 clone 占据了明显的 pod 重启时间时，请使用此配置。它会持久化已 materialize 的 source checkout，而不是 metadata index。pod 重建后，第一次刷新可以先从已持久化的 checkout 发布，再执行网络 fetch。

replicaCount: 1

storage:
  sourceWorkDir:
    type: pvc
    pvc:
      size: 10Gi
      accessModes:
        - ReadWriteOnce

#示例：更大的 catalog 与 ContentStore

仅当 repository 数量或 payload 大小带来可测量的内存压力时才使用此配置。index metadata 仍然保留在内存中，但 manifest 和 README payload 字节会存储在 pod 文件系统上，并通过 payload cache 读取。

config:
  refreshInterval: 30m
  initialSyncTimeout: 5m
  sourceLoadTimeout: 15m
  maxConcurrentSources: 2

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

cache:
  payloadCacheSize: 256Mi
  maxManifestBytes: 2Mi
  maxReadmeBytes: 8Mi

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