Alauda DevOps Pipelines Docs
  • 简体中文

    • 为 Tekton Hub 编写 Tasks

    目录

    概述Tekton Hub 要求Task 与 ClusterTask从 ClusterTask 迁移Hub 特定元数据必需标签Hub 必需注解Hub 参数标准参数类型Hub 特定参数要求Hub 最佳实践容器镜像要求Hub 的 Results 和 WorkspacesHub 分类和标签标准分类有效的标签策略Hub 验证要求错误处理标准Hub Tasks 的安全性Hub 安全要求Hub 测试要求必需的测试文件Hub 验证清单Hub Task 模板文档要求Hub 文档标准Hub 发布清单✅ Hub 合规性✅ 质量标准

    概述

    本指南介绍了创建可与 Tekton Hub catalog 配合使用的 Tasks 时的具体要求和最佳实践。内容重点涵盖 Hub 特定的元数据、验证和标准。

    Tekton Hub 要求

    Task 与 ClusterTask

    ⚠️ 关键：在 Tekton Pipelines v1.0+ 中，ClusterTask 已弃用并移除。请勿使用 ClusterTask。

    • Task：Hub catalog 唯一支持的资源类型
    • ClusterTask：在 Tekton v1.0+ 中已 ❌ 移除 - 将无法使用

    从 ClusterTask 迁移

    # OLD - ClusterTask (NO LONGER WORKS)
apiVersion: tekton.dev/v1beta1
kind: ClusterTask
metadata:
  name: buildah

# NEW - Task (Required for Hub)
apiVersion: tekton.dev/v1
kind: Task
metadata:
  name: buildah
  namespace: tekton-pipelines

    Hub 特定元数据

    必需标签

    metadata:
  name: my-custom-task
  labels:
    app.kubernetes.io/version: "0.1"  # Must match catalog version directory

    Hub 必需注解

    metadata:
  annotations:
    tekton.dev/pipelines.minVersion: "0.17.0"  # Minimum Tekton version
    tekton.dev/categories: "Build Tools"       # Hub category
    tekton.dev/tags: "build,podman,image"     # Hub search tags
    tekton.dev/displayName: "Build Podman Image"  # Hub display name
    tekton.dev/platforms: "linux/amd64,linux/arm64"  # Supported platforms

    Hub 参数标准

    参数类型

    Tekton Hub 支持三种参数类型：

    • string：单个文本值（默认）
    • array：字符串值列表
    • object：包含键值对的 JSON 对象

    Hub 特定参数要求

    • 清晰的描述：所有参数都必须具有有意义的描述，以便 Hub UI 使用
    • 合理的默认值：尽可能提供默认值，以改善用户体验
    • 类型安全：使用合适的类型，防止运行时错误

    Hub 最佳实践

    容器镜像要求

    • 使用官方、可信的容器镜像
    • 固定特定版本，而不是使用 latest 标签
    • 确保镜像可在受支持的平台（linux/amd64、linux/arm64）上运行
    • 定期更新基础镜像以提升安全性

    Hub 的 Results 和 Workspaces

    • Results：必须包含清晰的描述，以用于 Hub 文档
    • Workspaces：将可选 workspaces 标记为 optional: true
    • 描述：所有 workspaces 和 results 都必须提供描述

    Hub 分类和标签

    标准分类

    • Build Tools
    • Testing
    • Deployment
    • Security
    • Integration & Delivery
    • Developer Tools
    • Code Quality

    有效的标签策略

    • 使用具体且可搜索的标签
    • 包含技术名称（podman、kubernetes、npm 等）
    • 添加使用场景标签（ci、cd、build、test、deploy）

    Hub 验证要求

    错误处理标准

    • 使用正确的退出码（成功返回 0，失败返回非零值）
    • 为 Hub 用户提供清晰的错误消息
    • 包含结构化日志，以便更好地调试

    Hub Tasks 的安全性

    Hub 安全要求

    • Task 定义中不得硬编码 secrets
    • 使用可信的官方容器镜像
    • 固定具体的镜像版本（不要使用 latest 标签）
    • 遵循最小权限原则
    • 为任何特殊安全要求提供文档说明

    Hub 测试要求

    必需的测试文件

    • 提供可用的 samples/ 目录，其中包含 TaskRun 示例
    • 包含展示典型用法的 run.yaml
    • 测试所有参数组合
    • 验证错误处理场景

    Hub 验证清单

    • 已提供必需的 Hub 元数据
    • 示例 TaskRun 可正常工作
    • 所有参数都已添加描述
    • Results 和 workspaces 已正确描述
    • 遵循安全最佳实践
    • 已验证平台兼容性

    Hub Task 模板

    apiVersion: tekton.dev/v1
kind: Task
metadata:
  name: my-hub-task
  labels:
    app.kubernetes.io/version: "0.1"  # Match catalog version
  annotations:
    tekton.dev/pipelines.minVersion: "0.17.0"
    tekton.dev/categories: "Build Tools"  # Hub category
    tekton.dev/tags: "build,example"      # Hub search tags
    tekton.dev/displayName: "My Hub Task" # Hub display name
    tekton.dev/platforms: "linux/amd64,linux/arm64"  # Platforms
spec:
  description: >-
    Task description for Hub documentation
  params:
  - name: required-param
    description: Required parameter description
  - name: optional-param
    description: Optional parameter description
    default: "default-value"
  workspaces:
  - name: source
    description: Source workspace description
  results:
  - name: output
    description: Result description
  steps:
  - name: main
    image: alpine:3.18  # Pinned version
    script: |
      #!/bin/sh
      set -e
      echo "Hub task executed successfully"
      echo "result" > $(results.output.path)

    文档要求

    Hub 文档标准

    • 在 task 目录中包含完整的 README.md
    • 为所有参数、workspaces 和 results 编写文档
    • 提供使用示例和常见用例
    • 包含故障排查信息

    Hub 发布清单

    ✅ Hub 合规性

    • 已提供必需的 Hub 元数据（labels 和 annotations）
    • Task 使用 Task 资源类型（而不是 ClusterTask）
    • 版本标签与目录结构一致
    • 所有参数和 results 都有描述
    • 容器镜像使用固定版本
    • 已指定平台兼容性
    • 已提供可正常工作的示例 TaskRun
    • 提供完整的 README 和使用示例
    • 满足 Hub 验证要求

    ✅ 质量标准

    • Task 具有幂等性且可复用
    • 使用正确的退出码进行错误处理
    • 未硬编码 secrets 或凭据
    • 遵循安全最佳实践
    • 已验证跨平台兼容性
    • 文档完整且准确