向 Tekton Hub 添加自定义 Catalog
目录
概述前提条件添加自定义 Catalog第 1 步:准备你的 Catalog 仓库第 2 步:配置 API ConfigMap第 3 步:应用配置第 4 步:应用变更自定义 Catalog 的前提条件管理多个 Catalog私有仓库身份验证SSH 密钥身份验证前提条件创建 SSH Secret生成 known_hosts 条目在 Catalog 配置中使用 SSH URL验证与测试验证 Catalog 配置测试资源解析故障排除Catalog 未显示资源未加载SSH 身份验证失败资源解析失败常见问题Q: 我按照文档进行了配置,但仍然看不到新 catalog概述
本指南说明如何配置一个 Tekton Hub 实例,以便从现有 Git 仓库中包含自定义 catalog。如果你需要先创建一个新的 catalog 仓库,请参阅 创建自定义 Catalog。
前提条件:从
v4.12.0开始,内置的Tekton Hub不再默认部署。本指南假定你已先启用它;请参阅 启用内置 Tekton Hub。
自定义 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:由社区维护的 catalog(最常见的选择)enterprise:企业/公司专属 catalogprivate:私有 catalog(内部使用)
provider:指定 Git 平台,以便正确集成 API 和进行身份验证:github:GitHub 和 GitHub Enterprisegitlab:GitLab 和自托管 GitLab
URL 配置优先级:
-
sshurl的优先级高于url——当两者都提供时,git 操作将使用sshurl -
对于公共仓库:仅使用 HTTPS 格式的
url -
对于私有仓库:必须同时提供
url和sshurl——url用于数据库存储,sshurl用于实际的 git 操作
重要:由于数据库约束,即使是使用 sshurl 访问私有仓库,也始终需要 url。
第 3 步:应用配置
将更新后的 ConfigMap 应用到你的集群:
第 4 步:应用变更
更新 ConfigMap 后,应用这些变更:
选项 1:重启 API Pod
选项 2:等待自动刷新
catalog 将根据配置的 CATALOG_REFRESH_INTERVAL 自动刷新。
自定义 Catalog 的前提条件
在向 Tekton Hub 添加自定义 catalog 之前,你的仓库必须满足以下要求:
- 仓库结构:遵循 Tekton Catalog Organization 标准
- 资源验证:所有 Tasks/Pipelines 都必须包含必需的元数据
- 文档:每个资源都必须具有正确的 README 和示例
有关创建合规 catalog 仓库的详细说明,请参阅 创建自定义 Catalog。
管理多个 Catalog
你可以在同一个 Tekton Hub 实例中配置多个 catalog:
最佳实践:
- 使用描述性强且唯一的 catalog 名称
- 在不同环境中保持 catalog 名称一致
- 使用合适的 Git revision(main/master 用于稳定版本,develop 用于测试)
私有仓库身份验证
SSH 密钥身份验证
要访问私有 Git 仓库或来自私有 Git 实例的仓库,你需要将 SSH 凭据创建为 Kubernetes secret。
前提条件
~/.ssh目录中应存在 SSH 密钥- SSH 公钥应添加到 Git 仓库的 deploy key 或你的用户账户中
创建 SSH Secret
创建一个名为 tekton-hub-api-ssh-crds 的 Kubernetes secret,并包含你的 SSH 凭据:
重要说明:
- secret 必须严格命名为
tekton-hub-api-ssh-crds - secret 必须创建在与你的 Tekton Hub 安装相同的命名空间中
- 包含全部三个文件:私钥、公钥和 known_hosts
生成 known_hosts 条目
重要:你必须通过实际连接到 Git 服务器来生成 known_hosts 文件,以捕获其 SSH 指纹。简单复制示例条目可能无法工作,因为服务器密钥会变化,或者 Git provider 不同。
推荐方法:
-
在本地测试 SSH 连接,以捕获服务器指纹:
-
替代方案:使用 ssh-keyscan 生成 known_hosts 条目:
-
通过同时使用两个 URL 在本地克隆仓库进行验证:
known_hosts 条目示例(在成功建立 SSH 连接后生成):
在 Catalog 配置中使用 SSH URL
在配置需要 SSH 身份验证的 catalog 时,请同时提供 url 和 sshurl 字段:
注意:私有仓库需要同时提供 url(HTTPS)和 sshurl(SSH)。实际的 git 操作将使用 sshurl。
验证与测试
验证 Catalog 配置
添加自定义 catalog 后,请验证其是否已正确配置:
提示:默认的 Tekton Hub API 端点是
tekton-hub-api.tekton-pipelines:8000,它仅能在集群内部访问。对于下面命令中的
<your-tekton-hub-api>占位符:
- 在
tekton-hub-apipod 内:使用localhost:8000- 从集群中的其他 pod:使用
tekton-hub-api.tekton-pipelines:8000- 从集群外部:创建一个
主机端口Service 或Ingress(本指南不涵盖)为了测试,你可以在
tekton-hub-apipod 内使用wget运行这些命令。
测试资源解析
测试资源是否可以通过 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 服务器 - 从 pod 中手动测试 SSH 连接
资源解析失败
问题:Hub resolver 找不到资源
常见原因:
- ConfigMap 与 resolver 参数中的 catalog 名称不匹配
- 资源名称/版本与目录结构不匹配
- catalog 解析期间资源验证失败
调试步骤:
常见问题
Q: 我按照文档进行了配置,但仍然看不到新 catalog
A:首先,检查 tekton-hub-api 日志中是否存在与身份验证相关的错误,例如 “Host key verification failed”:
常见原因:
- SSH key 对该仓库没有足够的权限
known_hosts文件缺少 Git 服务器指纹- SSH key 未正确添加到仓库的 deploy key 中
解决方案:
-
先在本地测试:确保你可以使用相同的 SSH 凭据在本地成功克隆仓库:
-
仅在本地克隆成功后,再更新你的 Kubernetes 环境:
- 请参阅 生成 known_hosts 条目 章节,以正确生成
known_hosts文件 - 使用可用的凭据重新创建
tekton-hub-api-ssh-crdssecret - 重启
tekton-hub-apipod 并检查日志:
- 请参阅 生成 known_hosts 条目 章节,以正确生成