Hub Resolver 无法解析资源

问题描述错误表现根因分析故障排查 1. 验证 TektonConfig 2. 验证 reconciled 后的 resolver ConfigMap 3. 检查 resolver Pod 环境 4. 验证 shim Service 和 repository 健康状态 5. 验证 resolver 请求的确切 package 6. 检查 version 格式 7. 检查 resolver 日志相关内容

问题描述

TaskRun 或 PipelineRun 引用了一个远程资源，并使用 resolver: hub，但 Tekton 无法从 artifacthub-shim 解析出 Task、Pipeline 或 StepAction。

错误表现

常见症状包括：

运行一直处于解析失败状态。
没有创建工作负载 Pod。
运行状态或 resolver 日志中提到缺少 package 或 version。
resolver 仍然尝试使用默认的上游 Artifact Hub 端点。

Hub 引用示例：

taskRef:
  resolver: hub
  params:
    - name: type
      value: artifact
    - name: catalog
      value: catalog
    - name: kind
      value: task
    - name: name
      value: run-script
    - name: version
      value: "0.1.0"

根因分析

通常由以下原因导致：

未启用 Hub resolver。
TektonConfig 未将 hub resolver 类型设置为 artifact。
经过 reconciled 的 artifact-hub-api 未指向 artifacthub-shim。
resolver Pod 尚未读取更新后的 ConfigMap。
catalog、kind、name 或 version 参数与 shim package 不匹配。
目标 repository source 无效、降级且没有 last-good shard，或者已禁用。

故障排查

TIP

下面的命令会根据 TektonConfig.spec.targetNamespace 推导 Tekton resolver 命名空间，并假设 artifacthub-shim 运行在 artifacthub-shim-system 中。如果你的安装使用不同的值，请替换 shim 命名空间。

1. 验证 TektonConfig

检查 TektonConfig 中的 hub resolver 设置：

kubectl get tektonconfig config -o yaml

spec.pipeline 部分应包含：

spec:
  pipeline:
    enable-hub-resolver: true
    hub-resolver-config:
      artifact-hub-api: http://artifacthub-shim-api.artifacthub-shim-system.svc.cluster.local
      default-artifact-hub-task-catalog: catalog
      default-artifact-hub-pipeline-catalog: catalog-pipelines
      default-kind: task
      default-tekton-hub-catalog: catalog
      default-type: artifact

如果 default-type 不是 artifact，请在每个 hub 引用中添加 type: artifact，或者更新默认值。

2. 验证 reconciled 后的 resolver ConfigMap

operator 会将 TektonConfig.spec.pipeline.hub-resolver-config reconciled 到 hubresolver-config ConfigMap 中。

RESOLVER_NAMESPACE="$(kubectl get tektonconfig config \
  -o jsonpath='{.spec.targetNamespace}')"

kubectl get configmap hubresolver-config \
  -n "${RESOLVER_NAMESPACE}" \
  -o yaml

期望值：

data:
  artifact-hub-api: http://artifacthub-shim-api.artifacthub-shim-system.svc.cluster.local
  default-tekton-hub-catalog: catalog
  default-type: artifact

同时检查 resolver 功能开关：

kubectl get configmap resolvers-feature-flags \
  -n "${RESOLVER_NAMESPACE}" \
  -o jsonpath='{.data.enable-hub-resolver}{"\n"}'

期望输出：

true

3. 检查 resolver Pod 环境

查找远程 resolver Pod：

kubectl get pods -n "${RESOLVER_NAMESPACE}"

检查 resolver Deployment 是否使用了 hubresolver-config：

kubectl get deployment -n "${RESOLVER_NAMESPACE}" \
  -o yaml | grep -A5 -B5 ARTIFACT_HUB_API

如果 ConfigMap 正确，但 resolver 仍然使用旧值，请重启 resolver Pod，使其重新读取更新后的环境变量：

kubectl delete pod -n "${RESOLVER_NAMESPACE}" \
  -l app.kubernetes.io/component=resolvers

如果你的安装使用不同的 resolver 标签，请删除 kubectl get pods 返回的特定远程 resolver Pod。

4. 验证 shim Service 和 repository 健康状态

检查 shim Deployment 和 Service 是否可用：

kubectl get deployment,service,endpoints \
  -n artifacthub-shim-system \
  -l app.kubernetes.io/name=artifacthub-shim

然后检查 hub 引用所使用的 catalog 对应的 repository ConfigMap Events：

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

RepositorySourceReady 表示 resolver 客户端可以看到该 catalog。 RepositorySourceInvalid 或 RepositorySourceDegraded 表示即使 shim API pod 本身是健康的，resolver 也可能失败。

5. 验证 resolver 请求的确切 package

将 hub resolver 参数与 repository source 以及 catalog 内容进行对比：

catalog 必须与 repository.yaml.gitRepositories[].repositories[].name 匹配。
kind 必须与 repository source kind 匹配。
name 必须与配置的 path 下的 package 目录名匹配。
version 必须与某个 version 目录或受支持的、兼容 semver 的选择器匹配。

对于内置 catalog 资源，Tasks 使用 catalog，Pipelines 使用 catalog-pipelines。历史遗留的 Pipeline 引用如果仍然使用 catalog，可以通过 shim catalog alias 支持，但新的引用应使用 catalog-pipelines。

对于迁移后的自定义 Tekton Hub catalogs，operator 可能会创建诸如 team-a、team-a-pipelines 和 team-a-stepactions 之类的 repositories，并使用类似 team-a 的旧别名将其指向 Pipeline repository 以供 Pipeline 查找。API 响应和 UI 标签仍会返回规范化的 repository 名称。如果 resolver 在迁移后失败，请检查 repository ConfigMap 中的 legacyCatalogAliases，并验证请求的 kind 是否与别名作用域匹配。

如果 source 处于 Ready 状态但仍然找不到 package，请检查 repository ConfigMap 和 chart values 中的已禁用 package 规则。

6. 检查 version 格式

在 YAML 中将看起来像数字的 version 用引号括起来：

- name: version
  value: "0.1.0"

artifacthub-shim 支持归一化后的 semver 查找。例如，名为 0.1 的 catalog 目录可能会作为 0.1.0 返回，以兼容 resolver。如果 resolver 使用 version constraint，请验证 catalog 是否包含匹配的非预发布 version 目录。

7. 检查 resolver 日志

kubectl logs -n "${RESOLVER_NAMESPACE}" \
  deployment/tekton-pipelines-remote-resolvers \
  --tail=200

如果你的 resolver Deployment 名称不同，请使用：

kubectl get deployment -n "${RESOLVER_NAMESPACE}"

然后查询匹配的 resolver Deployment 或 Pod 的日志。

#Hub Resolver 无法解析资源

#目录

#问题描述

#错误表现

#根因分析

#故障排查

#1. 验证 TektonConfig

#2. 验证 reconciled 后的 resolver ConfigMap

#3. 检查 resolver Pod 环境

#4. 验证 shim Service 和 repository 健康状态

#5. 验证 resolver 请求的确切 package

#6. 检查 version 格式

#7. 检查 resolver 日志

#相关内容