编写 Catalog 资源
artifacthub-shim 会从已配置的文件系统和
Git Catalog 源中索引 Tekton 资源。Catalog 可以包含 Task、Pipeline 和 StepAction
资源。每个资源按目录进行版本管理,并通过
DevOps Hub UI、兼容 Artifact Hub 的 API,以及 Tekton hub resolver 暴露。
如果 Catalog 存储在 Git 中,请先配置源,然后再测试
资源。有关所需的 repository.yaml 结构、Catalog 路径、仓库名称、
可见性、凭据和 extraResources 设置,请参阅配置自定义 Git 仓库。
目录
Catalog 目录布局资源元数据完整 Task 示例完整 Pipeline 示例支持 ConfigMap初始化 Catalog 并为其添加版本更改已发布的版本使用 Hub Resolver 使用资源推荐设置验证检查清单Catalog 目录布局
Catalog 仓库使用以下布局。建议维护者提供根目录下的 README.md 和
OWNERS 文件;shim 会索引
task/、pipeline/ 和 stepaction/ 目录下的资源。
遵循以下规则:
- 使用小写资源 kind 作为顶级目录:
task、pipeline或stepaction。 - 每个软件包版本使用
<kind>/<name>/<version>/。版本目录 名称应兼容语义化版本,例如0.1、0.2或1.0.0。 - 将清单存储为
<name>.yaml或<name>.yml。shim 优先使用此 文件名。如果该文件不存在,则可以在版本目录中发现唯一的 YAML 文件,前提是其 Kuberneteskind与配置的源 kind 匹配。 - 清单的
metadata.name必须等于软件包目录名称,并且 清单的kind必须与顶级源目录匹配。 - 对于同一个软件包,不要同时发布规范化后语义版本相同的版本,
例如
0.1和0.1.0。这会导致 resolver 查找结果不明确。 - 将特定版本的
README.md放在清单旁边。索引时可选,但 它会显示在资源详情页中,并应记录参数、工作区、结果、示例和兼容性。 samples/和OWNERS为可选项。它们不会作为清单编入索引,但 有助于审查和用户文档。- 将普通仓库文件放在资源版本目录之外。
artifacthub-shim不要求提供artifacthub-repo.yml文件。
config/ 目录用于存放支持 ConfigMap,例如工具镜像
选项和概览模板。这些文件不是 Catalog 软件包。只有在配置的源使用 extraResources
且 ConfigMap 具有配置自定义 Git
仓库中所述的导入标签时,才会导入这些文件。
资源元数据
shim 要求有效的 YAML 清单包含 kind 和 metadata.name,并且当这些值与配置的源和软件包目录不匹配时拒绝该资源。以下元数据构成 Catalog 发布契约:
artifacthub-shim 会在其 API 响应中保留所有清单标签和注解。当前解析器只会拒绝格式错误的 YAML、缺少 kind、缺少 name,或 kind/name 不匹配的清单;不会仅因缺少可选注解而拒绝其他方面有效的清单。不过,仍应在每个已发布版本上保留上述发布元数据,以便资源具有完整的 UI、搜索、兼容性和 Artifact Hub 元数据。
保留任何现有的 style.tekton.dev/descriptors 注解不变。它们用于驱动动态表单,shim 不会重写或生成这些注解。对于必须同步到集群中的 ConfigMap,请使用单独的 artifacthub-shim.alauda.io/import: "true" 标签;不要将该标签添加到 Task、Pipeline 或 StepAction 清单中。
完整 Task 示例
以下清单应位于
task/echo-hello/0.1/echo-hello.yaml:
完整 Pipeline 示例
以下清单应位于
pipeline/hello-pipeline/0.1/hello-pipeline.yaml:
使用当前目标平台支持的 Tekton API 版本对应的 Task、Pipeline 和 StepAction 资源。不要添加新的 ClusterTask 资源;Tekton Pipelines v1 使用命名空间范围的 Task 资源。
支持 ConfigMap
当 catalog release 必须安装支持性的 ConfigMap 时,请将 config/ 与包含 Git extraResources 条目的内容结合使用。只有带有 import 标签的 apiVersion: v1、kind: ConfigMap 文档才会同步。目标命名空间必须被 config.extraResourceSync.allowedNamespaces 允许(默认值为 kube-public)。
未带标签的 ConfigMap、非 ConfigMap 资源以及无关文件都会被跳过。如果同步的 ConfigMap 从 Git 中移除后仍必须保留,请将 artifacthub-shim.alauda.io/resource-policy: keep 添加到集群内资源中。有关这些 UI 功能所需的标签,请参阅向 Selector 添加自定义 Task 镜像和使用模板自定义 Task 概览。
初始化 Catalog 并为其添加版本
使用以下内容创建初始仓库结构:
将多个版本置于不同目录中。当资源契约或行为发生变化时,请使用新版本,并在版本 README.md 中记录破坏性变更。发布新版本前,请确认其目录名称、版本标签、清单名称和 README 都描述同一个 release。
根目录中的 OWNERS 文件是供维护者使用的仓库元数据,例如:
更改已发布的版本
已发布的版本目录并非固定不变。当源中的现有 <kind>/<name>/<version>/ 目录的清单或 README.md 发生变化时,shim 会在下一次刷新后提供新内容。对于一个版本,shim 仅提供这两个文件;目录中的其他文件(例如 samples/ 和 OWNERS)不会作为版本内容提供。刷新每隔 config.refreshInterval 运行一次(默认值为 10m,通过 ARTIFACTHUB_SHIM_REFRESH_INTERVAL 环境变量设置;请参阅Chart 配置)。仓库 ConfigMap 或 Secret 事件会在事件去抖窗口(config.repositoryEventDebounce,默认值为 2s)之后启动一次刷新;Kubernetes catalog source 事件则会直接请求刷新,不经过该窗口。每次刷新都会重新获取 Git 源,重建整个索引,并以原子方式替换所提供的快照。shim 不会将版本与之前的快照进行比较,因此既不会拒绝也不会报告原地变更。版本报告的 digest 是其清单的 SHA-256 值:清单发生变化时该值会变化,而仅 README 发生变化时该值保持不变。针对该 name 和 version 的 Resolver 请求会在刷新后收到新内容。每个 Replica 都会独立刷新。当某个源因临时错误而加载失败时,只有在该 Replica 之前成功加载过该源且源配置自那以后未发生变化的情况下,它才会继续提供该源上一次成功加载的内容;否则,该源会被报告为无效。
请将已发布的版本视为最终版本。要修复或更改已发布的资源,请发布新的版本目录并更新对它的引用。要冻结 Git 源的文件,请将其 revision 设置为 commit,而不是分支。这只会冻结该源的文件:shim 提供哪些版本仍取决于 catalog 配置,例如通过仓库 ConfigMap 或 Kubernetes catalog source 添加或移除的仓库,以及 config.disabledPackages 规则(请参阅Chart 配置)。固定到某个 commit 的 Git 源只会提供该 commit 中包含的内容,因此发布新的版本目录后,还必须将源的 revision 移动到包含该目录的 commit;否则不会提供新版本。
使用 Hub Resolver 使用资源
对于 artifacthub-shim,将 resolver 类型设置为 artifact。catalog
值是内置或已配置的仓库名称,而不是 Git 仓库 URL
或本地目录名称。
内置仓库名称如下:
只有当打包的 catalog 包含 stepaction/ 目录时,才会注册 StepAction 仓库。自定义 Git 仓库使用 repository.yaml 中嵌套的 repositories[].name 值作为其 catalog 参数。
例如,如果仓库名为 team-a-tasks,请使用:
主要 resolver 参数如下:
如需完整的 resolver 配置和故障排查指南,请参阅 使用 Hub Resolver 使用资源。
推荐设置
启用时机:当多个项目需要相同的构建、扫描或交付步骤时,请使用共享 catalog。
推荐值:按照配置自定义 Git 仓库中的说明,将 catalog 注册为一个 Git 仓库条目,并为每种 kind 使用一个稳定的仓库名称:添加一个嵌套的 repositories 条目,其中包含 kind: task,再添加另一个包含 kind: pipeline 的条目,因为每个嵌套条目只声明一个 kind,其 name 会成为 resolver 引用所使用的 catalog 参数。保留 Catalog 目录布局中的 task/<name>/<version>/<name>.yaml 和 pipeline/<name>/<version>/<name>.yaml 路径。每当资源契约或行为发生变化时,都应按照初始化并版本化 Catalog 的说明发布新的版本目录。确保每个资源都可在隔离网络环境中独立运行:通过 hub resolver 从此 catalog 解析 Tasks 和 Pipelines,并从为该环境提供服务的私有 registry 中引用步骤镜像(请参阅内置工具镜像选择指南),或通过 digest 固定镜像。发布前必须经过审核:在根目录的 OWNERS 文件中列出 approvers 和 reviewers,并对每个版本通过下方的验证检查清单。在 resolver 引用中设置 type: artifact、为资源 kind 配置的 catalog 名称,以及明确的 version,因为 hub resolver 会拒绝不包含 version 的引用(missing required hub resolver params: version)。
前提条件:已安装 artifacthub-shim,并将 config.enableConfigMapSources 设置为 true,以便注册 Git 源。已启用 Tekton hub resolver 并将其指向 shim,具体请参阅使用 Hub Resolver 使用资源。承载 catalog 的 Git 服务器可从集群访问,并且 catalog 引用的每个步骤镜像都可在环境的 registry 中使用。
验证检查清单
发布 catalog 前,请检查每个资源版本:
- 路径遵循
<kind>/<name>/<version>/<name>.yaml。 - 清单的 kind 和
metadata.name与源 kind 和包目录匹配。 -
app.kubernetes.io/version与版本目录匹配。 - 存在有用的
spec.description。 -
tekton.dev/pipelines.minVersion声明了兼容的上游 Tekton 版本下限。 - 在适用时提供
tekton.dev/displayName、tekton.dev/categories、tekton.dev/tags和tekton.dev/platforms。 - 存在
artifacthub.io/license和artifacthub.io/category;已弃用的版本包含artifacthub.io/deprecated: "true"。 - 参数、workspaces、results 和示例在适用时包含说明。
- 每个版本都有包含可运行示例的 README。
- 示例和 resolver 引用使用
type: artifact。 - 用于同步的 ConfigMap 包含
artifacthub-shim.alauda.io/import: "true",并且使用允许的命名空间。 - 没有软件包包含规范化版本重复项,例如
0.1和0.1.0。
有用的本地检查包括:
推送仓库后,配置其 Git 源,并验证仓库 ConfigMap 报告了 RepositoryConfigAccepted,且其源报告了 RepositorySourceReady 事件。Git 源、仓库名称、凭据、可见性和 extraResources 规则记录在配置自定义 Git 仓库中。