将自定义 Catalog 添加到 Tekton Hub

概述

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

自定义 catalog 允许组织通过 Tekton Hub 共享其 Tekton 资源,使其可以通过 Hub resolver 和 Web 界面被发现。

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

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

前提条件

在开始之前,请确保你已经具备:

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

添加自定义 Catalog

步骤 1:准备你的 Catalog 仓库

确保你的 catalog 仓库遵循 Tekton Catalog Organization TEP 结构(详细信息请参阅教程部分)。

步骤 2:配置 API ConfigMap

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

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

    # 官方 Tekton catalog(公共仓库)
    - 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

Catalog 配置字段:

字段必填描述有效值示例
name是在 Hub 中 catalog 的唯一标识符任意字符串my-catalog, tekton-official
org是仓库的组织或所有者任意字符串tektoncd, myorg
type是用于分类和 UI 显示的 catalog 类型official, community, enterprise, privatecommunity
provider是Git 托管平台github, gitlabgithub
url是仓库 URL(公共仓库使用 HTTPS)有效的 Git URLhttps://github.com/org/repo
sshurl否私有仓库的 SSH URL(需要 SSH key)有效的 SSH Git URLgit@github.com:org/repo.git
revision是用于资源同步的分支或 tag任意有效的 Git refmain, master, v1.0

字段使用详情:

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

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        # 数据库约束所需字段
    sshurl: git@github.com:org/private-repo.git     # 用于 git 操作(优先)

重要:由于数据库约束,即使是使用 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 的前提条件

在将自定义 catalog 添加到 Tekton Hub 之前,你的仓库必须满足以下要求:

  • 仓库结构:遵循 Tekton Catalog Organization 标准
  • 资源验证:所有 Tasks/Pipelines 必须包含所需的元数据
  • 文档:每个资源都必须包含正确的 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 revision(稳定环境使用 main/master,测试使用 develop)

私有仓库认证

SSH Key 认证

要访问私有 Git 仓库或来自私有 Git 实例的仓库,你需要将 SSH 凭证创建为 Kubernetes secret。

前提条件

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

创建 SSH Secret

创建一个名为 tekton-hub-api-ssh-crds 的 Kubernetes secret,并包含你的 SSH 凭证:

$ 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 安装相同的命名空间中
  • 包含全部三个文件:private key、public key 和 known_hosts

生成 known_hosts 条目

重要:你必须通过实际连接到 Git server 来生成 known_hosts 文件,以捕获其 SSH fingerprint。简单复制示例条目可能无法工作,因为 server key 可能会变更,或者 Git provider 不同。

推荐方法:

  1. 在本地测试 SSH 连接,以捕获 server 的 fingerprint:

    # 这会将 server 的 fingerprint 添加到你的本地 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 server
    $ ssh-keyscan your-git-server.com >> ~/.ssh/known_hosts
  3. 通过在本地克隆你的仓库进行验证,同时使用两个 URL:

    # 测试 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...

在 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        # 数据库所需
      sshurl: git@github.com:myorg/private-catalog.git     # 用于 git 操作
      revision: main

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

验证与测试

验证 Catalog 配置

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

提示:默认的 Tekton Hub API endpoint 是 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 运行这些命令。

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

# 检查 API 中是否出现该 catalog
$ 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>"}]}

# 检查 catalog 资源
$ 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":{}}}

测试 Resource 解析

测试资源是否可以通过 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 已显示,但资源缺失

可能原因:

解决方案:

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

SSH 认证失败

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

解决方案:

  1. 验证 secret 是否存在:kubectl get secret tekton-hub-api-ssh-crds
  2. 验证 known_hosts 是否包含你的 Git server
  3. 从 pod 中手动测试 SSH 连接

Resource 解析失败

问题:Hub resolver 无法找到资源

常见原因:

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

调试步骤:

# 检查可用的 catalog
$ 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>

# 检查 catalog 同步状态
$ kubectl logs deployment/tekton-hub-api -n <tekton-pipelines>

常见问题

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

答:首先检查 tekton-hub-api 日志中是否存在认证相关错误,例如 "Host key verification failed":

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

常见原因:

  • SSH key 对仓库没有足够权限
  • known_hosts 文件缺少 Git server 的 fingerprint
  • SSH key 没有正确添加到仓库 deploy keys 中

解决方法:

  1. 先在本地测试:确保你可以使用相同的 SSH 凭证在本地成功克隆仓库:

    # 使用完全相同的 SSH key 和 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>