#Repository 源不可见

#问题描述

在为 artifacthub-shim 创建 repository ConfigMap 后，预期的 Task、Pipeline 或 StepAction 并未出现在 shim API、DevOps Hub UI 或 Tekton hub resolver 结果中。

#错误表现

常见症状包括：

• package 详情 API 返回 404。
• package 缺失于 /api/v1/packages/search。
• UI 列表未显示该资源。
• repository ConfigMap 出现 RepositorySourceInvalid 或 RepositorySourceDegraded 事件。
• 使用 resolver: hub 的 TaskRun 或 PipelineRun 无法解析 引用的资源。

#根因分析

常见原因如下：

1. ConfigMap 未被 artifacthub-shim 监听。
2. 缺少或无效的 repository.yaml。
3. 其他 source 使用了相同的 repository name。
4. 请求使用了因冲突而被禁用的 legacy catalog alias。
5. 引用的 Secret 缺失，或包含不受支持的凭证键。
6. Git clone 或 fetch 失败。
7. catalog 目录布局无效。
8. package 或 version 被禁用。

artifacthub-shim 会对跨 ConfigMap 的 source 失败进行隔离。如果某个 ConfigMap 中的一条条目无效，该 ConfigMap 中的所有 repository 条目都会被拒绝， 但其他 ConfigMap 声明的 repository 仍保持隔离。对于瞬时 Git 失败，如果存在先前的最后一个可用 source shard，则仍可能继续提供该结果。

#故障排查

#1. 检查 shim 就绪状态

kubectl get deployment artifacthub-shim -n artifacthub-shim-system

如果 Deployment 不可用或正在重启，请先检查 pod 日志，再排查单个 repository。

#2. 检查 repository ConfigMap 标签和数据键

ConfigMap 必须包含 repository 标签和 repository.yaml 数据键。

kubectl get configmap <configmap-name> \
  -n artifacthub-shim-system \
  -o yaml

所需结构：

metadata:
  labels:
    artifacthub-shim.alauda.io/repository: "true"
data:
  repository.yaml: |
    gitRepositories:
      - url: https://git.example.com/team-a/tekton-catalog.git
        revision: main
        repositories:
          - name: team-a-tasks
            kind: task
            path: task

如果缺少该标签，或者其值不是 "true"，该 ConfigMap 将被忽略。

对于位于主监听 namespace 之外的 repository ConfigMap，还需要验证：

• 对于 namespace、project 或显式 Namespace allowlist 范围， config.scopedConfigMapSources.enabled 为 true。
• 对于 repository-visibility: "global"， config.globalConfigMapSources.enabled 为 true，并且当该列表非空时， source Namespace 已包含在 config.globalConfigMapSources.allowedNamespaces 中。
• project 范围的 owner Namespace 具有非空的 cpaas.io/project 标签。
• 至少存在一个由 artifacthub-shim.alauda.io/repository-visible-namespaces 列出的有效 Namespace。 缺失的条目会被忽略，直到该 Namespace 被创建。
• artifacthub-shim ServiceAccount 具有 chart 渲染后的集群范围只读 RBAC， 可访问 repository ConfigMap、Namespaces、引用的 Secrets 和 Events。

#3. 检查 repository ConfigMap Events

查看 repository ConfigMap 上最近的 Events：

kubectl describe configmap <configmap-name> \
  -n artifacthub-shim-system

你也可以直接列出 Events：

kubectl get events -n artifacthub-shim-system \
  --field-selector involvedObject.kind=ConfigMap,involvedObject.name=<configmap-name>

对于持续存在的 Warning 状态，artifacthub-shim 会在每次刷新或资源同步尝试时再次记录该 Warning。 Kubernetes 通常会将其保留为一个 Event，并增加计数和更新最近一次时间戳。 如果 event TTL 清理删除了之前的 Event，那么下一次尝试可以再次创建它。

Events 仍然属于历史记录。即使配置已修复，之前的 RepositoryConfigInvalid 或 RepositorySourceInvalid 条目也可能在 Kubernetes event TTL 清理之前继续可见。 请结合最新的 RepositoryConfigAccepted 或 RepositorySourceReady Event 以及 /api/v1/snapshot source 状态来判断当前状态。

常见 Event reason：

常见 reason message 模式：

#4. 验证 repository name 的唯一性

Repository name 是全局 catalog 标识符。当多个 source 声明相同的 repository.yaml.gitRepositories[].repositories[].name 时，冲突按 source 优先级解决（从高到低）：

1. 随 artifacthub-shim 一起发布的内置默认 catalog。
2. 在安装 namespace 中注册的 ConfigMap sources （默认是 artifacthub-shim-system）。
3. 在其他任何 Namespace 中注册的 ConfigMap sources。

最高优先级的 source 胜出并保持建立索引；较低优先级的重复项会被标记为 Invalid。 当多个 source 具有相同优先级时，胜出者是按字典序最靠前的 namespace/configmap/kind/repository 标识。这可确保 takeover 的确定性， 并允许在胜出者被删除后，下一个有效 source 接管。

查找所有 repository ConfigMap：

kubectl get configmap --all-namespaces \
  -l artifacthub-shim.alauda.io/repository=true \
  -o yaml

如果同一优先级下有两个条目使用相同的 name，请将其中一个重命名， 并更新任何使用旧 catalog name 的 hub resolver 引用。

#5. 验证可选路径和 legacy alias

如果迁移后的 source 设置了 optional: true，那么缺失或为空的 path 不会导致失败。该 source 会以 packages=0 和 versions=0 的状态报告为 Ready。 这对于生成的条目是预期行为，例如某个 legacy catalog 中只包含 Tasks， 但创建了 Pipeline source 的场景。

如果省略 optional 或将其设为 false，缺失的 path 仍然无效。 仅在有意保持迁移兼容时使用 optional: true，不要用它来掩盖意外的布局错误。

仅当你需要保持旧的 resolver catalog 值可用时，才检查 legacyCatalogAliases。 alias 按 kind 进行作用域划分。冲突的 alias 会被省略出查询结果， 并作为非致命警告上报；在冲突被移除之前，请使用 canonical repository name。

#6. 检查 Secret 键

如果某个 repository.yaml.gitRepositories[] 条目使用了 credentialRef， 请验证该 Secret 是否存在于与 repository ConfigMap 相同的 namespace 中：

kubectl get secret <secret-name> -n artifacthub-shim-system

支持的键包括：

• username
• password
• token
• sshPrivateKey
• ssh-privatekey
• known_hosts
• ca.crt

不要将凭证放在 ConfigMap 中。

#7. 检查 API pod 日志

kubectl logs -n artifacthub-shim-system \
  deployment/artifacthub-shim \
  --tail=200

请查找 Git clone 错误、YAML 解析错误、manifest 标识错误或内容大小限制错误。

#8. 检查已禁用的 package 规则

如果 source 已经是 Ready，但某个特定 package 缺失，请检查 repository ConfigMap 中的 disabledPackages 以及 chart values 中的 config.disabledPackages。

repository 本地示例：

disabledPackages:
  - name: run-script
    versions:
      - "0.1"

被禁用的 package 或 version 会有意地从列表、搜索、详情和 resolver 响应中移除。

#相关内容

• 配置自定义 Git Repositories
• 禁用 Catalog Packages
• Hub Resolver 无法解析资源