#向 Tekton Hub 添加自定义 Catalog

#概述

本指南将说明如何配置 Tekton Hub 实例，以包含来自现有 Git 仓库的自定义 catalog。如果你需要先创建一个新的 catalog 仓库，请参阅 创建自定义 Catalog。

自定义 catalog 允许组织通过 Tekton Hub 共享其 Tekton 资源，使其能够通过 Hub resolver 和 web 界面被发现。

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

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

#先决条件

在开始之前，请确保你具备以下条件：

• 已安装 Tekton Pipelines 的 Kubernetes 集群
• 正在运行的 Tekton Hub 实例
• 集群的管理员访问权限
• 一个包含自定义 Tekton 资源并遵循 Tekton Catalog 结构的 Git 仓库

#添加自定义 Catalog

#第 1 步：准备你的 Catalog 仓库

确保你的 catalog 仓库遵循 Tekton Catalog Organization TEP 结构（详情请参阅 tutorials 部分）。

#第 2 步：配置 API ConfigMap

将你的自定义 catalog 添加到 tekton-hub-api ConfigMap 的 CATALOGS 部分：

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

    # Official Tekton catalog (public repository)
    - name: catalog-official
      org: tektoncd
      type: community
      provider: github
      url: https://github.com/tektoncd/catalog
      revision: main

    # Custom public repository
    - name: my-public-catalog
      org: myorganization
      type: community
      provider: github
      url: https://github.com/myorganization/my-public-catalog
      revision: main

    # Custom private repository (requires SSH authentication)
    - 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

Catalog 配置字段：

字段使用详情：

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

URL 配置优先级：

• sshurl 的优先级高于 url - 当二者都提供时，sshurl 将用于 git 操作

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

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

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

  url: https://github.com/org/private-repo        # Required field (database constraint)
  sshurl: git@github.com:org/private-repo.git     # Used for git operations (takes precedence)

重要：由于数据库约束，即使使用 sshurl 访问私有仓库，也始终需要 url。

#第 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 将根据配置的 CATALOG_REFRESH_INTERVAL 自动刷新。

#自定义 Catalog 的先决条件

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

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

有关创建符合规范的 catalog 仓库的详细说明，请参阅 创建自定义 Catalog。

#管理多个 Catalog

你可以在同一个 Tekton Hub 实例中配置多个 catalog：

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

最佳实践：

• 使用具有描述性且唯一的 catalog 名称
• 在不同环境中保持 catalog 名称一致
• 使用合适的 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 连接，以捕获服务器指纹：

   # This will add the server's fingerprint to your local known_hosts
   $ ssh -T git@github.com
   $ ssh -T git@your-git-server.com

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

   # For GitHub
   $ ssh-keyscan github.com >> ~/.ssh/known_hosts
   
   # For custom Git servers
   $ ssh-keyscan your-git-server.com >> ~/.ssh/known_hosts

3. 通过在本地克隆仓库进行验证，同时使用两个 URL：

   # Test the SSH URL that will be used by Tekton Hub
   $ git clone ssh://git@github.com:org/private-repo.git
   
   # Also test the HTTPS URL for verification
   $ git clone https://github.com/org/private-repo.git

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

github.com ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABgQCj7ndN...

#在 Catalog 配置中使用 SSH URL

当配置需要 SSH 认证的 catalog 时，请同时提供 url 和 sshurl 字段：

data:
  CATALOGS: |
    - name: private-catalog
      org: myorg
      type: community
      provider: github
      url: https://github.com/myorg/private-catalog        # Required for database
      sshurl: git@github.com:myorg/private-catalog.git     # Used for git operations
      revision: main

注意：私有仓库需要同时提供 url（HTTPS）和 sshurl（SSH）。sshurl 将用于实际的 git 操作。

#验证和测试

#验证 Catalog 配置

添加自定义 catalog 后，请验证其是否已正确配置：

提示：默认的 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 Service 或 Ingress（本指南不涵盖）

出于测试目的，你可以在 tekton-hub-api Pod 内使用 wget 运行这些命令。

# Execute inside the tekton-hub-api pod for testing
$ kubectl exec -it deployment/tekton-hub-api -n <tekton-pipelines> -- /bin/sh

# Check if the catalog appears in the 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>"}]}

# Check catalog resources
$ 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":""}]}

# Verify specific resource
$ wget -qO- http://<your-tekton-hub-api>/v1/resource/<my-custom-catalog>/task/<my-task>

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

#测试资源解析

测试资源是否能够通过 Hub resolver 进行解析：

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"

#故障排查

#Catalog 未显示

问题：已配置 catalog，但未在 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>

#资源未加载

问题：catalog 已显示，但资源缺失

可能原因：

• 仓库结构不符合标准
• 缺少必需元数据（参见 创建自定义 Catalog）
• 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 resolver 找不到资源

常见原因：

• ConfigMap 与 resolver 参数中的 catalog 名称不匹配
• 资源名称/版本与目录结构不匹配
• catalog 解析期间资源验证失败

调试步骤：

# Check available catalogs
$ wget -qO- http://<your-tekton-hub-api>/v1/catalogs

# Verify resource exists
$ wget -qO- http://<your-tekton-hub-api>/v1/resource/<my-custom-catalog>/task/<my-task>/<version>

# Check catalog sync status
$ kubectl logs deployment/tekton-hub-api -n <tekton-pipelines>

#FAQ

#问：我已经按照文档进行了配置，但仍然看不到新的 catalog

答：首先检查 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 凭据在本地成功克隆仓库：

   # Test with the exact same SSH key and 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>