#向 Tekton Hub 添加自定义目录

#Overview

本指南说明如何配置 Tekton Hub 实例以包含来自现有 Git 仓库的自定义目录。如果您需要先创建新的目录仓库，请参见创建自定义目录。

自定义目录允许组织通过 Tekton Hub 共享其 Tekton 资源，使其可通过 Hub 解析器和 Web 界面被发现。

重要：如果您是通过 TektonConfig 部署的 Tekton Hub，请在 TektonConfig 资源中修改目录配置，而不是直接编辑 ConfigMap。直接修改 ConfigMap 会被 Tekton Operator 控制器覆盖。

命名空间说明：本指南中 <tekton-pipelines> 用作您的 Tekton Hub 命名空间的占位符，请替换为实际的命名空间名称。默认安装使用 tekton-pipelines 命名空间。

#前提条件

开始之前，请确保您具备：

• 已安装 Tekton Pipelines 的 Kubernetes 集群
• 正在运行的 Tekton Hub 实例
• 集群管理员权限
• 包含符合 Tekton Catalog 结构的自定义 Tekton 资源的 Git 仓库

#添加自定义目录

#第 1 步：准备目录仓库

确保您的目录仓库遵循 Tekton Catalog Organization TEP 结构（详见教程部分）。

#第 2 步：配置 API ConfigMap

在 tekton-hub-api ConfigMap 的 CATALOGS 部分添加您的自定义目录：

apiVersion: v1
kind: ConfigMap
metadata:
  name: tekton-hub-api
  namespace: <tekton-pipelines>
data:
  CATALOGS: |
    # 默认本地目录
    - name: catalog
      org: tektoncd
      type: community
      provider: github
      url: file:////mnt/git/catalog.git
      revision: master

    # 官方 Tekton 目录（公共仓库）
    - name: catalog-official
      org: tektoncd
      type: community
      provider: github
      url: https://github.com/tektoncd/catalog
      revision: main

    # 自定义公共仓库
    - name: my-public-catalog
      org: myorganization
      type: community
      provider: github
      url: https://github.com/myorganization/my-public-catalog
      revision: main

    # 自定义私有仓库（需要 SSH 认证）
    - name: my-private-catalog
      org: myorganization
      type: community
      provider: github
      url: https://github.com/myorganization/my-private-catalog
      sshurl: git@github.com:myorganization/my-private-catalog.git
      revision: main

目录配置字段说明：

字段使用详情：

• org：用于在 Hub UI 中组织和分组目录，可以是代表目录所有者的任意有意义字符串。
• type：决定目录在 Hub 界面的分类和显示方式：
  • official：官方 Tekton 目录（通常由 Tekton 团队维护）
  • community：社区维护目录（最常用）
  • enterprise：企业/公司专用目录
  • private：私有目录（内部使用）
• provider：指定 Git 平台以便正确的 API 集成和认证：
  • github：GitHub 和 GitHub Enterprise
  • gitlab：GitLab 和自托管 GitLab

URL 配置优先级：

• sshurl 优先于 url — 当两者都提供时，git 操作将使用 sshurl

• 公共仓库：仅使用 HTTPS 格式的 url

  url: https://github.com/org/public-repo

• 私有仓库：必须同时提供 url 和 sshurl — url 用于数据库存储，sshurl 用于实际 git 操作

  url: https://github.com/org/private-repo        # 必填字段（数据库约束）
  sshurl: git@github.com:org/private-repo.git     # 用于 git 操作（优先）

重要：由于数据库约束，url 始终是必填字段，即使私有仓库使用 sshurl。

#第 3 步：应用配置

将更新后的 ConfigMap 应用到集群：

$ kubectl apply -f tekton-hub-api-configmap.yaml

#第 4 步：应用变更

更新 ConfigMap 后，应用变更：

选项 1：重启 API Pod

$ kubectl delete pod app=tekton-hub-api -n <tekton-pipelines>

选项 2：等待自动刷新

目录将根据配置的 CATALOG_REFRESH_INTERVAL 自动刷新。

#自定义目录的前提条件

在向 Tekton Hub 添加自定义目录之前，您的仓库必须满足以下要求：

• 仓库结构：遵循 Tekton Catalog Organization 标准
• 资源验证：所有 Tasks/Pipelines 必须包含必需的元数据
• 文档：每个资源必须有适当的 README 和示例

有关创建合规目录仓库的详细说明，请参见**创建自定义目录**。

#管理多个目录

您可以在同一个 Tekton Hub 实例中配置多个目录：

data:
  CATALOGS: |
    - name: tekton
      org: tektoncd
      type: community
      provider: github
      url: https://github.com/tektoncd/catalog
      revision: main
    - name: company-catalog
      org: mycompany
      type: community
      provider: github
      url: https://github.com/mycompany/tekton-catalog
      revision: main
    - name: team-catalog
      org: mycompany
      type: community
      provider: github
      url: https://github.com/mycompany/team-tekton-catalog
      revision: develop

最佳实践：

• 使用描述性且唯一的目录名称
• 保持目录名称在不同环境中一致
• 使用合适的 Git 版本（稳定使用 main/master，测试使用 develop）

#私有仓库认证

#SSH 密钥认证

访问私有 Git 仓库或私有 Git 实例的仓库时，需要创建 Kubernetes Secret 存储 SSH 凭据。

#前提条件

• SSH 密钥应存在于您的 ~/.ssh 目录
• SSH 公钥应添加到 Git 仓库的 deploy keys 或您的用户账户

#创建 SSH Secret

使用您的 SSH 凭据创建名为 tekton-hub-api-ssh-crds 的 Kubernetes Secret：

$ kubectl create secret generic tekton-hub-api-ssh-crds \
  --from-file=id_rsa="/path/to/id_rsa" \
  --from-file=id_rsa.pub="/path/to/id_rsa.pub" \
  --from-file=known_hosts="/path/to/known_hosts" \
  --namespace=<tekton-pipelines>

重要说明：

• Secret 名称必须严格为 tekton-hub-api-ssh-crds
• Secret 必须创建在与 Tekton Hub 安装相同的命名空间
• 必须包含私钥、公钥和 known_hosts 三个文件

#生成 known_hosts 条目

重要：您必须通过实际连接 Git 服务器生成 known_hosts 文件以捕获其 SSH 指纹。仅复制示例条目可能因服务器密钥变更或不同 Git 提供商而无效。

推荐方法：

1. 本地测试 SSH 连接，捕获服务器指纹：

   # 这会将服务器指纹添加到本地 known_hosts
   $ ssh -T git@github.com
   $ ssh -T git@your-git-server.com

2. 替代：使用 ssh-keyscan 生成 known_hosts 条目：

   # 针对 GitHub
   $ ssh-keyscan github.com >> ~/.ssh/known_hosts
   
   # 针对自定义 Git 服务器
   $ ssh-keyscan your-git-server.com >> ~/.ssh/known_hosts

3. 通过本地克隆仓库验证：

   # 测试 Tekton Hub 将使用的 SSH URL
   $ git clone ssh://git@github.com:org/private-repo.git
   
   # 也测试 HTTPS URL 以作验证
   $ git clone https://github.com/org/private-repo.git

示例 known_hosts 条目（成功 SSH 连接后生成）：

github.com ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABgQCj7ndN...

#在目录配置中使用 SSH URL

配置需要 SSH 认证的目录时，需同时提供 url 和 sshurl 字段：

data:
  CATALOGS: |
    - name: private-catalog
      org: myorg
      type: community
      provider: github
      url: https://github.com/myorg/private-catalog        # 数据库必需
      sshurl: git@github.com:myorg/private-catalog.git     # 用于 git 操作
      revision: main

注意：私有仓库必须同时提供 url（HTTPS）和 sshurl（SSH），实际 git 操作使用 sshurl。

#验证与测试

#验证目录配置

添加自定义目录后，验证其配置是否正确：

提示：默认 Tekton Hub API 端点为 tekton-hub-api.tekton-pipelines:8000，仅集群内可访问。

对于以下命令中的 <your-tekton-hub-api> 占位符：

• 在 tekton-hub-api Pod 内部：使用 localhost:8000
• 集群内其他 Pod：使用 tekton-hub-api.tekton-pipelines:8000
• 集群外部：需创建 NodePort 服务或 Ingress（本指南不涵盖）

测试时可在 tekton-hub-api Pod 内使用 wget 执行命令。

# 在 tekton-hub-api Pod 内执行测试
$ kubectl exec -it deployment/tekton-hub-api -n <tekton-pipelines> -- /bin/sh

# 检查目录是否出现在 API 中
$ wget -qO- http://<your-tekton-hub-api>/v1/catalogs

{"data":[{"id":1,"name":"catalog","type":"community","url":"file:////mnt/git/catalog.git","provider":"github"},{"id":2,"name":"<new-catalog>","type":"private","url":"<url>","provider":"<provider>"}]}

# 检查目录资源
$ wget -qO- "http://<your-tekton-hub-api>/v1/query?catalogs=<my-custom-catalog>"

{"data":[{"id":1,"name":"<name>","catalog":{"id":1,"name":"<my-custom-catalog>","type":"community"},"categories":[{"id":9,"name":"<name>"}],"kind":"Task","hubURLPath":"","hubRawURLPath":""}]}

# 验证特定资源
$ wget -qO- http://<your-tekton-hub-api>/v1/resource/<my-custom-catalog>/task/<my-task>

{"data":{"id":4,"name":"<my-task>","catalog":{}}}

#测试资源解析

测试资源是否能通过 Hub 解析器解析：

apiVersion: tekton.dev/v1
kind: TaskRun
metadata:
  name: test-catalog-resolution
spec:
  taskRef:
    resolver: hub
    params:
    - name: catalog
      value: my-custom-catalog
    - name: type
      value: tekton
    - name: kind
      value: task
    - name: name
      value: test-task
    - name: version
      value: "0.1"

#故障排除

#目录未显示

问题：目录已配置但未在 API 中显示

解决方案：

1. 检查 ConfigMap 是否已应用：kubectl get cm tekton-hub-api -o yaml
2. 重启 API Pod：kubectl delete pod app=tekton-hub-api -n <tekton-pipelines>
3. 查看 API 日志：kubectl logs deployment/tekton-hub-api -n <tekton-pipelines>

#资源未加载

问题：目录显示但资源缺失

可能原因：

• 仓库结构不符合标准
• 缺少必需元数据（参见创建自定义目录）
• Git 仓库认证问题

解决方案：

1. 检查 API 日志中的解析错误
2. 使用 kubectl apply --dry-run 验证资源 YAML 语法

#SSH 认证失败

问题：访问私有仓库被拒绝

解决方案：

1. 确认 Secret 存在：kubectl get secret tekton-hub-api-ssh-crds
2. 确认 known_hosts 包含您的 Git 服务器
3. 从 Pod 手动测试 SSH 连接

#资源解析失败

问题：Hub 解析器无法找到资源

常见原因：

• ConfigMap 和解析器参数中的目录名称不匹配
• 资源名称/版本与目录结构不符
• 资源在目录解析时验证失败

调试步骤：

# 查看可用目录
$ wget -qO- http://<your-tekton-hub-api>/v1/catalogs

# 验证资源是否存在
$ wget -qO- http://<your-tekton-hub-api>/v1/resource/<my-custom-catalog>/task/<my-task>/<version>

# 查看目录同步状态
$ kubectl logs deployment/tekton-hub-api -n <tekton-pipelines>

#常见问题

#问：我按照文档配置了，但仍看不到新目录

答：首先检查 tekton-hub-api 日志中是否有类似“Host key verification failed”的认证错误：

$ kubectl logs deployment/tekton-hub-api -n <tekton-pipelines>

常见原因：

• SSH 密钥对仓库权限不足
• known_hosts 文件缺少 Git 服务器指纹
• SSH 密钥未正确添加到仓库 deploy keys

解决方案：

1. 先本地测试：确保使用相同的 SSH 凭据能成功克隆仓库：

   # 使用完全相同的 SSH 密钥和 known_hosts 测试
   $ git clone ssh://git@github.com:org/private-repo.git

2. 本地克隆成功后，更新 Kubernetes 环境：

   • 参考生成 known_hosts 条目部分正确生成 known_hosts 文件
   • 重新创建 tekton-hub-api-ssh-crds Secret，使用有效凭据
   • 重启 tekton-hub-api Pod 并检查日志：

     $ kubectl delete pod -l app=tekton-hub-api -n <tekton-pipelines>
     $ kubectl logs deployment/tekton-hub-api -n <tekton-pipelines>