Alauda DevOps Pipelines Docs
简体中文

创建自定义目录

目录

Overview

本教程将指导您如何创建包含 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,docker,container"

    # 人类可读的显示名称
    tekton.dev/displayName: "Docker 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 发现

下一步

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