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,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：修复 bug，改进
    • 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 发现

    下一步

    了解目录结构和标准后，深入学习资源开发：