Alauda DevOps Pipelines Docs
  • 简体中文

    • 为 Tekton Hub 编写 Tasks

    目录

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

    概述

    本指南涵盖了创建适用于 Tekton Hub 目录的 Tasks 的具体要求和最佳实践。重点介绍了 Hub 特定的元数据、验证和标准。

    Tekton Hub 要求

    Task 与 ClusterTask

    ⚠️ 重要提示：ClusterTask 在 Tekton Pipelines v1.0+ 中已弃用并移除。请勿使用 ClusterTask。

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

    从 ClusterTask 迁移

    # 旧版 - ClusterTask（不再支持）
apiVersion: tekton.dev/v1beta1
kind: ClusterTask
metadata:
  name: buildah

# 新版 - Task（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"  # 必须与目录版本匹配

    Hub 必需的注解

    metadata:
  annotations:
    tekton.dev/pipelines.minVersion: "0.17.0"  # 最低 Tekton 版本
    tekton.dev/categories: "Build Tools"       # Hub 分类
    tekton.dev/tags: "build,podman,image"     # Hub 搜索标签
    tekton.dev/displayName: "Build Podman Image"  # Hub 显示名称
    tekton.dev/platforms: "linux/amd64,linux/arm64"  # 支持的平台

    Hub 参数标准

    参数类型

    Tekton Hub 支持三种参数类型：

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

    Hub 特定参数要求

    • 清晰的描述：所有参数必须有明确的描述以供 Hub UI 使用
    • 合理的默认值：尽可能提供默认值以提升用户体验
    • 类型安全：使用合适的类型以避免运行时错误

    Hub 最佳实践

    容器镜像要求

    • 使用官方且可信的容器镜像
    • 固定具体版本，避免使用 latest 标签
    • 确保镜像支持的平台（linux/amd64、linux/arm64）
    • 定期更新基础镜像以保证安全性

    Hub 的结果和工作空间

    • 结果：必须有清晰的描述以供 Hub 文档使用
    • 工作空间：可选工作空间需标记为 optional: true
    • 描述：所有工作空间和结果都必须有描述

    Hub 分类和标签

    标准分类

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

    有效标签

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

    Hub 验证要求

    错误处理标准

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

    Hub Tasks 的安全性

    Hub 安全要求

    • 不得在 Task 定义中硬编码密钥
    • 使用可信的官方容器镜像
    • 固定具体镜像版本（禁止使用 latest 标签）
    • 遵循最小权限原则
    • 记录任何特殊的安全需求

    Hub 测试要求

    必需的测试文件

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

    Hub 验证清单

    • 存在必需的 Hub 元数据
    • 示例 TaskRun 正常工作
    • 所有参数均有描述
    • 结果和工作空间描述完整
    • 遵循安全最佳实践
    • 验证平台兼容性

    Hub Task 模板

    apiVersion: tekton.dev/v1
kind: Task
metadata:
  name: my-hub-task
  labels:
    app.kubernetes.io/version: "0.1"  # 与目录版本匹配
  annotations:
    tekton.dev/pipelines.minVersion: "0.17.0"
    tekton.dev/categories: "Build Tools"  # Hub 分类
    tekton.dev/tags: "build,example"      # Hub 搜索标签
    tekton.dev/displayName: "My Hub Task" # Hub 显示名称
    tekton.dev/platforms: "linux/amd64,linux/arm64"  # 支持平台
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  # 固定版本
    script: |
      #!/bin/sh
      set -e
      echo "Hub task executed successfully"
      echo "result" > $(results.output.path)

    文档要求

    Hub 文档标准

    • 在任务目录中包含完整的 README.md
    • 记录所有参数、工作空间和结果
    • 提供使用示例和常见用例
    • 包含故障排除信息

    Hub 发布清单

    ✅ Hub 合规性

    • 存在必需的 Hub 元数据（标签和注解）
    • 任务使用 Task 资源类型（非 ClusterTask）
    • 版本标签与目录结构匹配
    • 所有参数和结果均有描述
    • 容器镜像使用固定版本
    • 指定了平台兼容性
    • 提供可用的示例 TaskRun
    • 完整的 README，含使用示例
    • 通过 Hub 验证要求

    ✅ 质量标准

    • 任务幂等且可重用
    • 错误处理使用正确退出码
    • 无硬编码密钥或凭据
    • 遵循安全最佳实践
    • 跨平台兼容性验证
    • 文档完整且准确