向 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 Catalog 结构的自定义 Tekton 资源的 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: |
    # 默认本地 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 密钥)有效的 SSH Git URLgit@github.com:org/repo.git
revision是用于资源同步的分支或标签任意有效的 Git refmain, master, v1.0

字段使用说明:

  • 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 - 当两者都提供时,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 将根据配置的 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 revision(稳定版本使用 main/master,测试使用 develop)

私有仓库身份验证

SSH 密钥身份验证

要访问私有 Git 仓库或来自私有 Git 实例的仓库,你需要创建一个 Kubernetes Secret 作为 SSH 凭据。

前提条件

  • SSH 密钥应存在于你的 ~/.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 安装相同的命名空间中
  • 包含全部三个文件:私钥、公钥和 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. 通过在本地克隆你的仓库进行验证,同时使用两种 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)。实际的 git 操作将使用 sshurl。

验证和测试

验证 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 运行这些命令。

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

# 检查 Catalog 是否出现在 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>"}]}

# 检查 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":{}}}

测试资源解析

测试资源是否可以通过 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 解析期间资源校验失败

调试步骤:

# 检查可用的 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 密钥对该仓库没有足够的权限
  • 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>