编写 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 目录布局

Catalog 仓库使用以下布局。建议维护者提供根目录下的 README.md 和 OWNERS 文件;shim 会索引 task/、pipeline/ 和 stepaction/ 目录下的资源。

catalog-repo/
├── README.md
├── OWNERS
├── task/
│   └── echo-hello/
│       └── 0.1/
│           ├── README.md
│           ├── echo-hello.yaml
│           └── samples/
│               └── taskrun.yaml
├── pipeline/
│   └── hello-pipeline/
│       └── 0.1/
│           ├── README.md
│           ├── hello-pipeline.yaml
│           └── samples/
│               └── pipelinerun.yaml
├── stepaction/
│   └── echo-message/
│       └── 0.1/
│           ├── README.md
│           └── echo-message.yaml
└── config/
    ├── images/
    │   └── echo-hello.yaml
    └── templates/
        └── echo-hello-overview.yaml

遵循以下规则:

  • 使用小写资源 kind 作为顶级目录:task、 pipeline 或 stepaction。
  • 每个软件包版本使用 <kind>/<name>/<version>/。版本目录 名称应兼容语义化版本,例如 0.1、0.2 或 1.0.0。
  • 将清单存储为 <name>.yaml 或 <name>.yml。shim 优先使用此 文件名。如果该文件不存在,则可以在版本目录中发现唯一的 YAML 文件,前提是其 Kubernetes kind 与配置的源 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 发布契约:

字段级别要求
metadata.name必需与软件包目录名称匹配。
metadata.labels["app.kubernetes.io/version"]Catalog 发布必需与版本目录完全匹配。
spec.descriptionCatalog 发布必需在 UI 和 API 中显示的简明且有用的描述。
tekton.dev/pipelines.minVersionCatalog 发布必需与该资源兼容的最低上游 Tekton Pipelines 版本。
tekton.dev/displayName推荐UI 使用的人类可读名称。
tekton.dev/categories推荐用于发现资源的类别,例如 Build Tools、CLI、Deployment 或 Testing。
tekton.dev/tags推荐以逗号分隔的搜索标签。
tekton.dev/platforms推荐支持的平台,例如 linux/amd64,linux/arm64。
artifacthub.io/licenseArtifact Hub 元数据必需资源许可证,例如 Apache-2.0。
artifacthub.io/categoryArtifact Hub 元数据必需一个合适的 Artifact Hub 类别,例如 integration-delivery。
artifacthub.io/deprecated条件性发布已弃用版本时设置为 "true"。

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:

apiVersion: tekton.dev/v1
kind: Task
metadata:
  name: echo-hello
  labels:
    app.kubernetes.io/version: "0.1"
  annotations:
    tekton.dev/pipelines.minVersion: "0.56.0"
    tekton.dev/categories: "CLI"
    tekton.dev/tags: "echo,demo"
    tekton.dev/displayName: "Echo Hello"
    tekton.dev/platforms: "linux/amd64,linux/arm64"
    artifacthub.io/license: Apache-2.0
    artifacthub.io/category: integration-delivery
spec:
  description: Echo a greeting and expose it as a Task result.
  params:
    - name: message
      type: string
      description: Message to echo.
      default: "Hello World"
  results:
    - name: greeting
      description: The message written by the Task.
  steps:
    - name: echo-message
      image: alpine:3.21
      script: |
        #!/usr/bin/env sh
        set -eu
        echo "$(params.message)"
        printf '%s' "$(params.message)" > "$(results.greeting.path)"

完整 Pipeline 示例

以下清单应位于 pipeline/hello-pipeline/0.1/hello-pipeline.yaml:

apiVersion: tekton.dev/v1
kind: Pipeline
metadata:
  name: hello-pipeline
  labels:
    app.kubernetes.io/version: "0.1"
  annotations:
    tekton.dev/pipelines.minVersion: "0.56.0"
    tekton.dev/categories: "Integration & Delivery"
    tekton.dev/tags: "demo,pipeline,workflow"
    tekton.dev/displayName: "Hello Pipeline"
    tekton.dev/platforms: "linux/amd64,linux/arm64"
    artifacthub.io/license: Apache-2.0
    artifacthub.io/category: integration-delivery
spec:
  description: Run the echo-hello Task with a configurable greeting.
  params:
    - name: greeting
      type: string
      description: Greeting passed to the Task.
      default: "Hello from Pipeline"
  tasks:
    - name: say-hello
      taskRef:
        name: echo-hello
      params:
        - name: message
          value: "$(params.greeting)"

使用当前目标平台支持的 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)。

apiVersion: v1
kind: ConfigMap
metadata:
  name: echo-hello-tool-image
  namespace: kube-public
  labels:
    artifacthub-shim.alauda.io/import: "true"
    catalog.tekton.dev/tool-image-echo: "true"
data:
  name: Echo image
  image: registry.example.com/team/echo:1.0

未带标签的 ConfigMap、非 ConfigMap 资源以及无关文件都会被跳过。如果同步的 ConfigMap 从 Git 中移除后仍必须保留,请将 artifacthub-shim.alauda.io/resource-policy: keep 添加到集群内资源中。有关这些 UI 功能所需的标签,请参阅向 Selector 添加自定义 Task 镜像和使用模板自定义 Task 概览。

初始化 Catalog 并为其添加版本

使用以下内容创建初始仓库结构:

mkdir my-tekton-catalog
cd my-tekton-catalog
git init
mkdir -p task pipeline stepaction
touch README.md OWNERS
mkdir -p task/echo-hello/0.1/samples

将多个版本置于不同目录中。当资源契约或行为发生变化时,请使用新版本,并在版本 README.md 中记录破坏性变更。发布新版本前,请确认其目录名称、版本标签、清单名称和 README 都描述同一个 release。

根目录中的 OWNERS 文件是供维护者使用的仓库元数据,例如:

approvers:
  - catalog-maintainer
reviewers:
  - devops-reviewer

更改已发布的版本

已发布的版本目录并非固定不变。当源中的现有 <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 或本地目录名称。

apiVersion: tekton.dev/v1
kind: TaskRun
metadata:
  name: run-echo-hello
spec:
  taskRef:
    resolver: hub
    params:
      - name: type
        value: artifact
      - name: catalog
        value: catalog
      - name: kind
        value: task
      - name: name
        value: echo-hello
      - name: version
        value: "0.1"
  params:
    - name: message
      value: "Hello from the catalog"

内置仓库名称如下:

资源类型内置 catalog
taskcatalog
pipelinecatalog-pipelines
stepactioncatalog-stepactions

只有当打包的 catalog 包含 stepaction/ 目录时,才会注册 StepAction 仓库。自定义 Git 仓库使用 repository.yaml 中嵌套的 repositories[].name 值作为其 catalog 参数。 例如,如果仓库名为 team-a-tasks,请使用:

apiVersion: tekton.dev/v1
kind: TaskRun
metadata:
  name: run-team-a-task
spec:
  taskRef:
    resolver: hub
    params:
      - name: type
        value: artifact
      - name: catalog
        value: team-a-tasks
      - name: kind
        value: task
      - name: name
        value: echo-hello
      - name: version
        value: "0.1"

主要 resolver 参数如下:

参数必填描述
type对 shim 引用为是使用 artifact。
catalog对自定义仓库为是已配置的仓库名称。
kindresolver 无法推断时为是task、pipeline 或 stepaction。
name是package 名称。
version是精确版本或受支持的版本约束;hub resolver 会拒绝不包含该参数的引用(missing required hub resolver params: version)。

如需完整的 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。

有用的本地检查包括:

# List catalog manifests
find task pipeline stepaction -type f \( -name '*.yaml' -o -name '*.yml' \) -print

# Validate YAML syntax and Kubernetes object shape
kubectl apply --dry-run=client -f task/echo-hello/0.1/echo-hello.yaml
kubectl apply --dry-run=client -f pipeline/hello-pipeline/0.1/hello-pipeline.yaml

# Check the version label and minimum Tekton version annotations
rg 'app.kubernetes.io/version|tekton.dev/pipelines.minVersion' task pipeline stepaction

推送仓库后,配置其 Git 源,并验证仓库 ConfigMap 报告了 RepositoryConfigAccepted,且其源报告了 RepositorySourceReady 事件。Git 源、仓库名称、凭据、可见性和 extraResources 规则记录在配置自定义 Git 仓库中。