将自定义 Catalog 添加到 Tekton Hub
目录
概述前提条件添加自定义 Catalog步骤 1:准备你的 Catalog 仓库步骤 2:配置 API ConfigMap步骤 3:应用配置步骤 4:应用更改自定义 Catalog 的前提条件管理多个 Catalog私有仓库认证SSH Key 认证前提条件创建 SSH Secret生成 known_hosts 条目在 Catalog 配置中使用 SSH URL验证与测试验证 Catalog 配置测试 Resource 解析故障排查Catalog 未显示资源未加载SSH 认证失败Resource 解析失败常见问题问:我已经按照文档进行了配置,但仍然看不到新的 catalog概述
本指南说明如何配置一个 Tekton Hub 实例,以包含来自现有 Git 仓库的自定义 catalog。如果你需要先创建一个新的 catalog 仓库,请参阅 创建自定义 Catalog。
自定义 catalog 允许组织通过 Tekton Hub 共享其 Tekton 资源,使其可以通过 Hub resolver 和 Web 界面被发现。
重要:如果你是通过
TektonConfig部署的Tekton Hub,请在TektonConfig资源中修改 catalog 配置,而不是直接编辑ConfigMap。直接修改ConfigMap会被Tekton Operatorcontroller 覆盖。
命名空间说明:在本指南中,
<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 部分:
Catalog 配置字段:
字段使用详情:
org:用于在 Hub UI 中组织和分组 catalog。可以是任何能代表 catalog 所有者的有意义字符串。type:决定 catalog 在 Hub 界面中的分类和显示方式:official:官方 Tekton catalog(通常由 Tekton 团队维护)community:由 Community 维护的 catalog(最常见的选择)enterprise:企业/公司专用 catalogprivate:私有 catalog(内部使用)
provider:指定 Git 平台,以便进行正确的 API 集成和认证:github:GitHub 和 GitHub Enterprisegitlab:GitLab 和 GitLab self-hosted
URL 配置优先级:
-
sshurl的优先级高于url- 当两者都提供时,sshurl将用于 git 操作 -
对于公共仓库:仅使用 HTTPS 格式的
url -
对于私有仓库:必须同时提供
url和sshurl-url用于数据库存储,sshurl用于实际的 git 操作
重要:由于数据库约束,即使是使用 sshurl 的私有仓库,url 也始终是必需的。
步骤 3:应用配置
将更新后的 ConfigMap 应用到你的集群:
步骤 4:应用更改
更新 ConfigMap 后,应用这些更改:
选项 1:重启 API Pod
选项 2:等待自动刷新
catalog 将根据配置的 CATALOG_REFRESH_INTERVAL 自动刷新。
自定义 Catalog 的前提条件
在将自定义 catalog 添加到 Tekton Hub 之前,你的仓库必须满足以下要求:
- 仓库结构:遵循 Tekton Catalog Organization 标准
- 资源验证:所有 Tasks/Pipelines 必须包含所需的元数据
- 文档:每个资源都必须包含正确的 README 和示例
有关创建合规 catalog 仓库的详细说明,请参阅 创建自定义 Catalog。
管理多个 Catalog
你可以在同一个 Tekton Hub 实例中配置多个 catalog:
最佳实践:
- 使用描述性强且唯一的 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 凭证:
重要说明:
- 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 不同。
推荐方法:
-
在本地测试 SSH 连接,以捕获 server 的 fingerprint:
-
可选:使用 ssh-keyscan 生成 known_hosts 条目:
-
通过在本地克隆你的仓库进行验证,同时使用两个 URL:
known_hosts 条目示例(在 SSH 连接成功后生成):
在 Catalog 配置中使用 SSH URL
配置需要 SSH 认证的 catalog 时,请同时提供 url 和 sshurl 字段:
注意:私有仓库需要同时提供 url(HTTPS)和 sshurl(SSH)。sshurl 将用于实际的 git 操作。
验证与测试
验证 Catalog 配置
添加自定义 catalog 后,请验证其是否已正确配置:
提示:默认的 Tekton Hub API endpoint 是
tekton-hub-api.tekton-pipelines:8000,它只能在集群内部访问。对于下面命令中的
<your-tekton-hub-api>占位符:
- 在
tekton-hub-apipod 内:使用localhost:8000- 从集群中的其他 pod:使用
tekton-hub-api.tekton-pipelines:8000- 从集群外部:创建一个
NodePortservice 或Ingress(本指南不涵盖)出于测试目的,你可以在
tekton-hub-apipod 内使用wget运行这些命令。
测试 Resource 解析
测试资源是否可以通过 Hub resolver 进行解析:
故障排查
Catalog 未显示
问题:已配置 catalog,但未在 API 中显示
解决方案:
- 检查 ConfigMap 是否已应用:
kubectl get cm tekton-hub-api -o yaml - 重启 API pod:
kubectl delete pod app=tekton-hub-api -n <tekton-pipelines> - 检查 API 日志:
kubectl logs deployment/tekton-hub-api -n <tekton-pipelines>
资源未加载
问题:catalog 已显示,但资源缺失
可能原因:
- 仓库结构不符合标准
- 缺少必需元数据(参见 创建自定义 Catalog)
- Git 仓库认证问题
解决方案:
- 检查 API 日志中的解析错误
- 使用
kubectl apply --dry-run验证资源 YAML 语法
SSH 认证失败
问题:私有仓库访问被拒绝
解决方案:
- 验证 secret 是否存在:
kubectl get secret tekton-hub-api-ssh-crds - 验证 known_hosts 是否包含你的 Git server
- 从 pod 中手动测试 SSH 连接
Resource 解析失败
问题:Hub resolver 无法找到资源
常见原因:
- ConfigMap 与 resolver 参数中的 catalog 名称不匹配
- Resource 名称/version 与目录结构不匹配
- 资源在 catalog 解析期间验证失败
调试步骤:
常见问题
问:我已经按照文档进行了配置,但仍然看不到新的 catalog
答:首先检查 tekton-hub-api 日志中是否存在认证相关错误,例如 "Host key verification failed":
常见原因:
- SSH key 对仓库没有足够权限
known_hosts文件缺少 Git server 的 fingerprint- SSH key 没有正确添加到仓库 deploy keys 中
解决方法:
-
先在本地测试:确保你可以使用相同的 SSH 凭证在本地成功克隆仓库:
-
仅在本地克隆成功后,再更新你的 Kubernetes 环境:
- 参考 生成 known_hosts 条目 章节,正确生成
known_hosts文件 - 使用可用凭证重新创建
tekton-hub-api-ssh-crdssecret - 重启
tekton-hub-apipod 并检查日志:
- 参考 生成 known_hosts 条目 章节,正确生成