Alauda DevOps Pipelines Docs
  • 简体中文

    • 创建自定义 Catalog

    目录

    概述Catalog 目录结构必需的仓库结构关键结构规则Tekton Hub 验证要求关键要求（缺失即忽略资源）1. 必需标签2. 必需注解3. 必需的 Spec 字段4. 文件命名规则推荐注解（提升可发现性）标准分类完整的 Task 示例完整的 Pipeline 示例设置你的仓库初始化仓库结构根目录 OWNERS 文件版本管理语义化版本规则版本管理方式从 catalog 中使用资源在 Tasks 中使用 Hub Resolver在 Pipelines 中使用 Hub ResolverHub Resolver 参数示例：不同的 Catalog在 Pipeline 中使用 Hub Resolver下一步：添加到 Tekton Hub验证清单关键验证（必须通过）推荐验证测试你的 catalog发布你的 catalog下一步

    概述

    本教程将指导你使用 Tekton 资源（Tasks、Pipelines）创建一个 catalog 仓库。你将了解结构、元数据标准以及验证要求，这些内容可确保你的资源能够与 Tekton Hub 正常协作。

    如需在 Tekton Hub 中配置现有 catalog，请参阅 Adding Custom Catalogs。

    Catalog 目录结构

    所有 Tekton catalog 都必须遵循 Tekton Catalog Organization Standard。该标准可确保与 Tekton Hub 保持一致性和兼容性。

    必需的仓库结构

    catalog-repo/
├── README.md              # 根目录 catalog 文档
├── OWNERS                 # catalog 维护者
├── 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"  # MUST match directory version exactly

    2. 必需注解

    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 文件名必须与资源名称一致
    • 示例：名为 build-image 的 Task → 文件必须是 build-image.yaml
    • 强制模式：task/<name>/<version>/<name>.yaml 或 pipeline/<name>/<version>/<name>.yaml

    推荐注解（提升可发现性）

    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"

    标准分类

    请从以下 标准 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 实例添加自定义分类的说明，请参阅 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 名称一致）。

    设置你的仓库

    初始化仓库结构

    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

    根目录 OWNERS 文件

    定义 catalog 维护者：

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

    版本管理

    语义化版本规则

    • 0.1 → 0.2：错误修复、改进
    • 0.x → 1.0：新功能、稳定版本发布
    • 1.x → 2.0：破坏性变更

    版本管理方式

    • 每个版本都有自己的目录
    • 多个版本可以共存
    • 在 README 中记录破坏性变更

    从 catalog 中使用资源

    一旦你的 catalog 在 Tekton Hub 中完成配置，用户即可通过 Hub resolver 引用你的资源。不同 catalog 可能具有不同的 resolver 配置。

    在 Tasks 中使用 Hub Resolver

    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!"

    在 Pipelines 中使用 Hub Resolver

    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 支持以下参数：

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

    注意：对于自定义 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"

    在 Pipeline 中使用 Hub Resolver

    你可以在同一个 Pipeline 中混合使用来自不同 catalog 的 task：

    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 仓库准备就绪后，必须先在 Tekton Hub 中完成配置，用户才能通过 resolver 访问它。

    如需了解以下内容的完整说明：

    • 将你的 catalog 添加到 Tekton Hub 配置中
    • 私有仓库的 SSH 身份验证
    • catalog 集成的测试与故障排查

    请参阅 Adding Custom Catalogs。

    验证清单

    在发布你的 catalog 之前，请确认每个资源都满足 所有 Tekton Hub 要求：

    关键验证（必须通过）

    • 文件命名：严格遵循 task/<name>/<version>/<name>.yaml 模式
    • 版本标签：app.kubernetes.io/version: "0.1" 与目录版本一致
    • MinVersion 注解：包含 tekton.dev/pipelines.minVersion: "0.17.0"
    • Description 字段：spec.description: "..." 不能为空
    • YAML 语法：资源可通过 kubectl apply --dry-run 验证

    推荐验证

    • 显示名称：提供 tekton.dev/displayName 以提升用户体验
    • 分类：来自标准列表中的有效分类
    • 标签：具有描述性的、逗号分隔的标签（逗号后不要留空格）
    • 文档：每个资源都提供完整的 README.md
    • 示例：在 samples/run.yaml 中提供可运行的示例

    测试你的 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

    1. 推送到 Git 仓库（GitHub、GitLab 等）
    2. 本地测试 - 验证结构和 YAML 语法
    3. 添加到 Tekton Hub - 参阅 Adding Custom Catalogs
    4. 与团队共享 - 你的资源现在可以通过 Hub resolver 被发现

    下一步

    现在你已经了解了 catalog 结构和标准，可以进一步深入资源开发：