Alauda DevOps Pipelines Docs
简体中文

为 Tekton Hub 编写 Tasks

目录

概述

本指南涵盖了创建适用于 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,docker,image"     # Hub 搜索标签
    tekton.dev/displayName: "Build Docker 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

有效标签

  • 使用具体且可搜索的标签
  • 包含技术名称（如 docker、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: >-
    Hub 文档中的任务描述
  params:
  - name: required-param
    description: 必填参数描述
  - name: optional-param
    description: 可选参数描述
    default: "default-value"
  workspaces:
  - name: source
    description: 源代码工作空间描述
  results:
  - name: output
    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 验证要求

✅ 质量标准

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