创建自定义 Catalog
概述
本教程将指导你使用 Tekton 资源(Tasks、Pipelines)创建一个 catalog repository。你将了解结构、metadata 标准以及验证要求,这些要求可确保你的资源能够与 Tekton Hub 正常配合使用。
如需为 Tekton Hub 配置现有 catalog,请参阅 添加自定义 Catalog。
Catalog 目录结构
所有 Tekton catalogs 都必须遵循 Tekton Catalog Organization Standard。该标准可确保与 Tekton Hub 保持一致性和兼容性。
必需的 Repository 结构
catalog-repo/
├── README.md # Root catalog 文档
├── OWNERS # Catalog 维护人员
├── task/ # 所有 Task 资源
│ ├── task-name/ # Task 名称目录
│ │ ├── 0.1/ # Version 目录
│ │ │ ├── README.md # Task 文档
│ │ │ ├── task-name.yaml # Task 定义
│ │ │ ├── OWNERS # Task 维护人员
│ │ │ └── samples/ # 使用示例
│ │ │ └── run.yaml
│ │ └── 0.2/ # 下一个版本
│ └── another-task/
└── pipeline/ # 所有 Pipeline 资源
└── pipeline-name/
└── 0.1/
├── README.md
├── pipeline-name.yaml
├── OWNERS
└── samples/
关键结构规则
- Resource 类型:仅支持
task/ 和 pipeline/ 目录
- Version 管理:每个 resource 使用语义化 Version(
0.1、0.2、1.0)
- 多个版本:不同版本以独立目录共存
- 必需文件:每个版本都必须有
YAML 定义。README 和 OWNERS 为可选项,但建议提供。
- 可选示例:
samples/ 目录用于放置使用示例
Tekton Hub 验证要求
Tekton Hub 具有严格的验证规则,用于决定是否显示你的资源。未通过验证的资源将完全被忽略。
关键要求(缺少时将忽略资源)
以下字段绝对必需——缺少任意一个都会导致资源被完全忽略:
1. 必需的 Label
metadata:
labels:
app.kubernetes.io/version: "0.1" # MUST match directory version exactly
2. 必需的 Annotations
metadata:
annotations:
# MANDATORY: Minimum Tekton Pipelines version
tekton.dev/pipelines.minVersion: "0.17.0"
3. 必需的 Spec 字段
spec:
description: "Your resource description here" # MANDATORY: Cannot be empty
4. 文件命名规则
YAML 文件名必须与 resource 名称一致
- 示例:名为
build-image 的 Task → 文件必须命名为 build-image.yaml
- 强制模式:
task/<name>/<version>/<name>.yaml 或 pipeline/<name>/<version>/<name>.yaml
推荐的 Annotations(提升可发现性)
metadata:
annotations:
# Tekton Hub category (choose from standard list)
tekton.dev/categories: "Build Tools"
# Searchable tags (comma-separated, no spaces after commas)
tekton.dev/tags: "build,podman,container"
# Human-readable display name
tekton.dev/displayName: "Podman Build Task"
# Supported platforms (optional)
tekton.dev/platforms: "linux/amd64,linux/arm64"
标准 Categories
可从以下标准 Tekton Hub categories 中选择:
- Automation, Build Tools, CLI, Cloud
- Code Quality, Continuous Integration
- Deployment, Developer Tools
- Image Build, Integration & Delivery
- Git, Kubernetes, Messaging
- Monitoring, Networking, Publishing
- Security, Storage, Testing
重要:如果你的 Tekton Hub 实例中未配置某个 category,即使使用了有效的 category 名称,也不会显示该 resource。
有关如何向你的 Hub 实例添加自定义 categories 的说明,请参阅 Categories Configuration。
完整的 Task 示例
下面是一个完整的 Task,展示了所有必需和推荐字段:
apiVersion: tekton.dev/v1
kind: Task
metadata:
name: echo-hello
# CRITICAL: Required label - MUST match directory version
labels:
app.kubernetes.io/version: "0.1"
annotations:
# CRITICAL: Required minimum pipelines version
tekton.dev/pipelines.minVersion: "0.17.0"
# RECOMMENDED: For better discoverability
tekton.dev/categories: "CLI"
tekton.dev/tags: "echo,cli,demo"
tekton.dev/displayName: "Echo Hello"
tekton.dev/platforms: "linux/amd64,linux/arm64"
spec:
# CRITICAL: Required description field
description: Simple demonstration Task that echoes a greeting message
params:
- name: message
description: Message to echo
default: "Hello World"
results:
- name: greeting
description: The echoed greeting
steps:
- name: echo-message
image: alpine:3.18
script: |
#!/bin/sh
echo "$(params.message)"
echo -n "$(params.message)" | tee $(results.greeting.path)
重要:此文件必须保存为 task/echo-hello/0.1/echo-hello.yaml(文件名与 task 名称一致)。
完整的 Pipeline 示例
下面是一个完整的 Pipeline,展示了所有必需和推荐字段:
apiVersion: tekton.dev/v1
kind: Pipeline
metadata:
name: hello-pipeline
# CRITICAL: Required label - MUST match directory version
labels:
app.kubernetes.io/version: "0.1"
annotations:
# CRITICAL: Required minimum pipelines version
tekton.dev/pipelines.minVersion: "0.17.0"
# RECOMMENDED: For better discoverability
tekton.dev/categories: "Integration & Delivery"
tekton.dev/tags: "demo,pipeline,workflow"
tekton.dev/displayName: "Hello Pipeline"
tekton.dev/platforms: "linux/amd64,linux/arm64"
spec:
# CRITICAL: Required description field
description: Simple demonstration Pipeline showing task orchestration
params:
- name: greeting
description: Greeting message
default: "Hello from Pipeline"
workspaces:
- name: shared-data
description: Workspace for sharing data between tasks
tasks:
- name: say-hello
taskRef:
name: echo-hello
params:
- name: message
value: "$(params.greeting)"
- name: say-goodbye
taskRef:
name: echo-hello
params:
- name: message
value: "Goodbye from $(tasks.say-hello.results.greeting)"
runAfter:
- say-hello
重要:此文件必须保存为 pipeline/hello-pipeline/0.1/hello-pipeline.yaml(文件名与 pipeline 名称一致)。
设置你的 Repository
初始化 Repository 结构
mkdir my-tekton-catalog
cd my-tekton-catalog
git init
# Create basic structure
mkdir -p task pipeline
touch README.md OWNERS
# Example: Create a task
mkdir -p task/echo-hello/0.1/samples
Root OWNERS 文件
定义 catalog 维护人员:
approvers:
- your-github-username
reviewers:
- team-member-username
Version 管理
语义化 Version 规则
- 0.1 → 0.2:修复缺陷、改进
- 0.x → 1.0:新功能、稳定版发布
- 1.x → 2.0:Breaking changes
Version 管理方式
- 每个版本都有自己的目录
- 多个版本可以共存
- 在
README 中记录 Breaking changes
使用 Catalog 中的 Resources
一旦你的 catalog 在 Tekton Hub 中完成配置,用户就可以通过 Hub resolver 引用你的 resources。不同的 catalogs 可能具有不同的 resolver 配置。
将 Hub Resolver 用于 Tasks
apiVersion: tekton.dev/v1
kind: TaskRun
metadata:
name: test-echo-hello
spec:
taskRef:
resolver: hub
params:
- name: catalog
value: "my-custom-catalog" # Your catalog name in Hub config
- name: type
value: tekton
- name: kind
value: task
- name: name
value: echo-hello # Task name
- name: version
value: "0.1" # Task version
params:
- name: message
value: "Hello from my catalog!"
将 Hub Resolver 用于 Pipelines
apiVersion: tekton.dev/v1
kind: PipelineRun
metadata:
name: test-hello-pipeline
spec:
pipelineRef:
resolver: hub
params:
- name: catalog
value: "my-custom-catalog" # Your catalog name in Hub config
- name: type
value: tekton
- name: kind
value: pipeline
- name: name
value: hello-pipeline # Pipeline name
- name: version
value: "0.1" # Pipeline version
params:
- name: greeting
value: "Welcome to Tekton!"
workspaces:
- name: shared-data
emptyDir: {}
Hub Resolver 参数
Hub resolver 支持以下参数:
注意:对于自定义 catalog,你通常需要显式指定 catalog 和 type: tekton 参数。
有关 Hub resolver 的配置和设置,请参阅 Hub Resolver Configuration。
示例:不同的 Catalog
# Using the official Tekton catalog
taskRef:
resolver: hub
params:
- name: catalog
value: catalog # Official catalog name
- name: type
value: tekton
- name: kind
value: task
- name: name
value: git-clone
- name: version
value: "0.9"
# Using a custom organization catalog
taskRef:
resolver: hub
params:
- name: catalog
value: my-catalog # Custom catalog name
- name: type
value: tekton
- name: kind
value: task
- name: name
value: custom-build
- name: version
value: "0.2"
在 Pipelines 中使用 Hub Resolver
你可以在同一个 Pipeline 中混合来自不同 catalog 的 tasks:
apiVersion: tekton.dev/v1
kind: Pipeline
metadata:
name: multi-catalog-pipeline
spec:
description: Pipeline using tasks from multiple catalogs
workspaces:
- name: source
description: Source code workspace
tasks:
# Task from official Tekton catalog
- name: git-clone
taskRef:
resolver: hub
params:
- name: catalog
value: catalog
- name: type
value: tekton
- name: kind
value: task
- name: name
value: git-clone
- name: version
value: "0.9"
workspaces:
- name: output
workspace: source
# Task from your custom catalog
- name: custom-build
taskRef:
resolver: hub
params:
- name: catalog
value: my-custom-catalog
- name: type
value: tekton
- name: kind
value: task
- name: name
value: echo-hello
- name: version
value: "0.1"
runAfter:
- git-clone
params:
- name: message
value: "Build completed!"
下一步:添加到 Tekton Hub
当你的 catalog repository 准备就绪后,在用户能够通过 resolver 访问之前,仍需要将其配置到 Tekton Hub 中。
如需完整说明,请参阅:
- 将你的 catalog 添加到
Tekton Hub 配置中
- 私有 repository 的
SSH authentication
- 测试与排查 catalog 集成问题
请参阅 添加自定义 Catalog。
验证清单
在发布你的 catalog 之前,请确认每个 resource 都满足所有 Tekton Hub 要求:
关键验证(必须通过)
推荐验证
测试你的 Catalog
# Check required directory structure
$ find . -name "*.yaml" -path "*/task/*" -o -path "*/pipeline/*"
# Validate YAML syntax
$ 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>
# Test critical fields exist
$ grep -r "app.kubernetes.io/version" task/ pipeline/
$ grep -r "tekton.dev/pipelines.minVersion" task/ pipeline/
$ grep -r "description:" task/ pipeline/
发布你的 Catalog
- 推送到
Git repository(GitHub、GitLab 等)
- 本地测试 - 验证结构和
YAML 语法
- 添加到
Tekton Hub - 参阅 添加自定义 Catalog
- 与团队共享 - 你的 resources 现在可以通过
Hub resolver 被发现
下一步
现在你已经了解了 catalog 的结构和标准,可以进一步深入 resource 开发: