创建自定义目录

目录

概述

本教程将指导您如何创建包含 Tekton 资源(Tasks、Pipelines)的目录仓库。您将了解目录结构、元数据标准以及验证要求,确保您的资源能正确地与 Tekton Hub 配合使用。

有关在 Tekton Hub 中配置现有目录的信息,请参见添加自定义目录。

目录结构

所有 Tekton 目录必须遵循**Tekton Catalog Organization Standard**。该标准确保目录与 Tekton Hub 的一致性和兼容性。

必需的仓库结构

catalog-repo/
├── README.md              # 根目录目录文档
├── OWNERS                 # 目录维护者
├── task/                  # 所有 Task 资源
│   ├── task-name/         # Task 名称目录
│   │   ├── 0.1/           # 版本目录
│   │   │   ├── 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/

关键结构规则

  1. 资源类型:仅支持 task/ 和 pipeline/ 目录
  2. 版本管理:每个资源使用语义版本控制(如 0.1、0.2、1.0)
  3. 多版本共存:不同版本以独立目录共存
  4. 必需文件:每个版本必须包含 YAML 定义文件。README 和 OWNERS 为可选但推荐
  5. 可选示例:samples/ 目录用于存放使用示例

Tekton Hub 验证要求

Tekton Hub 具有严格的验证规则,决定您的资源是否会被展示。未通过验证的资源将被完全忽略。

关键要求(缺失则资源被忽略)

以下字段为绝对必需,缺少任意一项都会导致资源被完全忽略:

1. 必需标签

metadata:
  labels:
    app.kubernetes.io/version: "0.1"  # 必须与目录版本完全匹配

2. 必需注解

metadata:
  annotations:
    # 必需:最低 Tekton Pipelines 版本
    tekton.dev/pipelines.minVersion: "0.17.0"

3. 必需的 Spec 字段

spec:
  description: "这里填写资源描述"  # 必需,不能为空

4. 文件命名规则

  • YAML 文件名必须与资源名称一致
  • 例如:名为 build-image 的 Task → 文件必须为 build-image.yaml
  • 强制匹配模式:task/<name>/<version>/<name>.yaml 或 pipeline/<name>/<version>/<name>.yaml

推荐注解(提升可发现性)

metadata:
  annotations:
    # Tekton Hub 分类(从标准列表中选择)
    tekton.dev/categories: "Build Tools"

    # 可搜索标签(逗号分隔,逗号后无空格)
    tekton.dev/tags: "build,podman,container"

    # 人类可读的显示名称
    tekton.dev/displayName: "Podman Build Task"

    # 支持的平台(可选)
    tekton.dev/platforms: "linux/amd64,linux/arm64"

标准分类

请选择以下标准 Tekton Hub 分类:

  • 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 实例中配置的分类,即使使用了有效的分类名称,也不会被显示。 有关向您的 Hub 实例添加自定义分类的说明,请参见分类配置。

完整的 Task 示例

以下是包含所有必需和推荐字段的完整 Task 示例:

apiVersion: tekton.dev/v1
kind: Task
metadata:
  name: echo-hello
  # 关键:必需标签 - 必须与目录版本匹配
  labels:
    app.kubernetes.io/version: "0.1"
  annotations:
    # 关键:必需的最低 pipelines 版本
    tekton.dev/pipelines.minVersion: "0.17.0"
    # 推荐:提升可发现性
    tekton.dev/categories: "CLI"
    tekton.dev/tags: "echo,cli,demo"
    tekton.dev/displayName: "Echo Hello"
    tekton.dev/platforms: "linux/amd64,linux/arm64"
spec:
  # 关键:必需的描述字段
  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
  # 关键:必需标签 - 必须与目录版本匹配
  labels:
    app.kubernetes.io/version: "0.1"
  annotations:
    # 关键:必需的最低 pipelines 版本
    tekton.dev/pipelines.minVersion: "0.17.0"
    # 推荐:提升可发现性
    tekton.dev/categories: "Integration & Delivery"
    tekton.dev/tags: "demo,pipeline,workflow"
    tekton.dev/displayName: "Hello Pipeline"
    tekton.dev/platforms: "linux/amd64,linux/arm64"
spec:
  # 关键:必需的描述字段
  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 名称匹配)。

设置您的仓库

初始化仓库结构

mkdir my-tekton-catalog
cd my-tekton-catalog
git init

# 创建基础结构
mkdir -p task pipeline
touch README.md OWNERS

# 示例:创建一个 task
mkdir -p task/echo-hello/0.1/samples

根目录 OWNERS 文件

定义目录维护者:

approvers:
  - your-github-username
reviewers:
  - team-member-username

版本管理

语义版本规则

  • 0.1 → 0.2:修复缺陷,改进
  • 0.x → 1.0:新增功能,稳定发布
  • 1.x → 2.0:破坏性变更

版本管理

  • 每个版本拥有独立目录
  • 多版本共存
  • 在 README 中记录破坏性变更

使用目录中的资源

目录配置到 Tekton Hub 后,用户可以通过**Hub resolver**引用您的资源。不同目录有不同的 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"  # 您在 Hub 配置中的目录名称
    - name: type
      value: tekton
    - name: kind
      value: task
    - name: name
      value: echo-hello  # Task 名称
    - name: version
      value: "0.1"       # Task 版本
  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"  # 您在 Hub 配置中的目录名称
    - name: type
      value: tekton
    - name: kind
      value: pipeline
    - name: name
      value: hello-pipeline  # Pipeline 名称
    - name: version
      value: "0.1"           # Pipeline 版本
  params:
  - name: greeting
    value: "Welcome to Tekton!"
  workspaces:
  - name: shared-data
    emptyDir: {}

Hub Resolver 参数

Hub resolver 支持以下参数:

参数是否必需描述默认值示例值
name是从 Hub 获取的 task 或 pipeline 名称-echo-hello、build-image
catalog否拉取资源的目录tekton-catalog-tasks(tasks)
tekton-catalog-pipelines(pipelines)
tekton、my-catalog
type否拉取资源的 Hub 类型artifactartifact、tekton
kind否资源类型tasktask、pipeline
version否拉取资源的版本或约束最新"0.1"、">=0.5.0"

注意:对于自定义目录,通常需要显式指定 catalog 和 type: tekton 参数。

有关 Hub resolver 的配置和设置,请参见Hub Resolver 配置。

示例:不同目录

# 使用官方 Tekton 目录
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"
# 使用自定义组织目录
taskRef:
  resolver: hub
  params:
  - name: catalog
    value: my-catalog     # 自定义目录名称
  - name: type
    value: tekton
  - name: kind
    value: task
  - name: name
    value: custom-build
  - name: version
    value: "0.2"

在 Pipeline 中使用 Hub Resolver

您可以在同一个 Pipeline 中混合使用来自不同目录的任务:

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:
  # 来自官方 Tekton 目录的任务
  - 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

  # 来自您的自定义目录的任务
  - 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

当您的目录仓库准备好后,需要在 Tekton Hub 中进行配置,用户才能通过 resolver 访问它。

有关以下内容的完整说明:

  • 将目录添加到 Tekton Hub 配置
  • 私有仓库的 SSH 认证
  • 目录集成的测试与故障排查

请参见**添加自定义目录**。

验证清单

发布目录前,请确认每个资源满足所有 Tekton Hub 要求:

关键验证(必须通过)

  • 文件命名:严格遵循 task/<name>/<version>/<name>.yaml 模式
  • 版本标签:app.kubernetes.io/version: "0.1" 与目录版本匹配
  • MinVersion 注解:存在 tekton.dev/pipelines.minVersion: "0.17.0"
  • 描述字段:spec.description: "..." 非空
  • YAML 语法:资源通过 kubectl apply --dry-run 验证

推荐验证

  • 显示名称:提供 tekton.dev/displayName 以提升用户体验
  • 分类:使用标准列表中的有效分类
  • 标签:描述性、逗号分隔的标签(逗号后无空格)
  • 文档:为每个资源提供完整的 README.md
  • 示例:samples/run.yaml 中包含可用示例

测试您的目录

# 检查必需的目录结构
$ find . -name "*.yaml" -path "*/task/*" -o -path "*/pipeline/*"

# 验证 YAML 语法
$ 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>

# 测试关键字段存在
$ grep -r "app.kubernetes.io/version" task/ pipeline/
$ grep -r "tekton.dev/pipelines.minVersion" task/ pipeline/
$ grep -r "description:" task/ pipeline/

发布您的目录

  1. 推送到 Git 仓库(GitHub、GitLab 等)
  2. 本地测试 - 验证结构和 YAML 语法
  3. 添加到 Tekton Hub - 参见添加自定义目录
  4. 与团队共享 - 您的资源现已可通过 Hub resolver 发现

下一步

既然您已了解目录结构和标准,可以深入学习资源开发: