Alauda DevOps Pipelines Docs
简体中文

为 Tekton Hub 编写 Pipelines

目录

概述

本指南涵盖了创建与 Tekton Hub 目录兼容的 Pipelines 的具体要求和最佳实践。重点介绍了 Hub 特定的元数据、验证和组合标准。

Hub 特定元数据

Hub 必需的标签

metadata:
  name: my-custom-pipeline
  labels:
    app.kubernetes.io/version: "0.1"  # 必须与目录版本文件夹匹配

Hub 必需的注解

metadata:
  annotations:
    tekton.dev/pipelines.minVersion: "0.17.0"    # 最低 Tekton 版本
    tekton.dev/categories: "Integration & Delivery"  # Hub 分类
    tekton.dev/tags: "ci,build,test,deploy"     # Hub 搜索标签
    tekton.dev/displayName: "CI/CD Pipeline"    # Hub 显示名称
    tekton.dev/platforms: "linux/amd64,linux/arm64"  # 支持的平台

Hub Task 引用

Hub 目录 Task 引用示例

spec:
  tasks:
  - name: git-clone
    taskRef:
      resolver: hub
      params:
      - name: catalog
        value: "catalog"  # Hub 目录名称
      - name: type
        value: tekton
      - name: kind
        value: task
      - name: name
        value: git-clone  # 来自 Hub 的任务名称
      - name: version
        value: "0.9"      # 任务版本
    params:
    - name: url
      value: $(params.repo-url)
    workspaces:
    - name: output
      workspace: source-code

Hub 分类和标签

标准 Pipeline 分类

  • Integration & Delivery
  • Continuous Integration
  • Continuous Deployment
  • Testing
  • Security
  • Build & Package

有效的 Pipeline 标签使用

  • 使用工作流相关标签（ci、cd、cicd）
  • 包含技术栈标签（nodejs、java、python、golang）
  • 添加部署目标标签（kubernetes、cloud、containers）

Hub 参数标准

Hub 特定参数要求

spec:
  params:
  - name: repo-url
    description: "Git 仓库 URL，用于源代码"  # Hub UI 的清晰描述
    type: string
  - name: target-environment
    description: "部署目标环境"
    type: string
    default: "development"  # 合理的默认值
  - name: build-args
    description: "额外的构建参数"
    type: array
    default: []  # 数组的安全默认值

Hub Pipeline 模板

apiVersion: tekton.dev/v1
kind: Pipeline
metadata:
  name: my-hub-pipeline
  labels:
    app.kubernetes.io/version: "0.1"  # 与目录版本匹配
  annotations:
    tekton.dev/pipelines.minVersion: "0.17.0"
    tekton.dev/categories: "Integration & Delivery"  # Hub 分类
    tekton.dev/tags: "ci,build,deploy"               # Hub 搜索标签
    tekton.dev/displayName: "My CI/CD Pipeline"      # Hub 显示名称
    tekton.dev/platforms: "linux/amd64,linux/arm64"  # 支持平台
spec:
  description: >-
    Pipeline 描述，用于 Hub 文档
  params:
  - name: git-url
    description: Git 仓库 URL
  - name: image-name
    description: 容器镜像名称
    default: "myapp:latest"
  workspaces:
  - name: source-code
    description: 源代码工作区
  - name: docker-config
    description: Docker 注册表凭据
    optional: true

  tasks:
  - name: fetch-source
    taskRef:
      resolver: hub
      params:
      - name: catalog
        value: "catalog"
      - name: type
        value: tekton
      - name: kind
        value: task
      - name: name
        value: git-clone  # 引用 Hub 目录任务
      - name: version
        value: "0.9"
    params:
    - name: url
      value: $(params.git-url)
    workspaces:
    - name: output
      workspace: source-code

  - name: build-image
    taskRef:
      resolver: hub
      params:
      - name: catalog
        value: "catalog"
      - name: type
        value: tekton
      - name: kind
        value: task
      - name: name
        value: buildah    # 引用 Hub 目录任务
      - name: version
        value: "0.4"
    runAfter: [fetch-source]
    params:
    - name: image
      value: $(params.image-name)
    workspaces:
    - name: source
      workspace: source-code
    - name: dockerconfig
      workspace: docker-config

  finally:
  - name: cleanup
    taskRef:
      resolver: hub
      params:
      - name: catalog
        value: "catalog"
      - name: type
        value: tekton
      - name: kind
        value: task
      - name: name
        value: cleanup-workspace
      - name: version
        value: "0.1"
    workspaces:
    - name: source
      workspace: source-code

Hub 最佳实践

Hub 任务组合

  • 尽可能使用同一 Hub 目录中的 Tasks
  • 引用具体任务版本以保证稳定性
  • 提供清晰的参数映射
  • 记录任务依赖关系

Hub 工作区管理

  • 使用描述性工作区名称和说明
  • 将可选工作区标记为 optional: true
  • 记录任务间的工作区数据流
  • 尽量减少工作区需求

Hub Pipeline 可复用性

  • 针对常见用例设计
  • 提供灵活的参数
  • 包含合理的默认值
  • 支持多种部署场景

Hub 测试要求

必需的 Pipeline 测试文件

  • 提供可用的 samples/ 目录，包含 PipelineRun 示例
  • 包含展示典型用法的 run.yaml
  • 使用多种参数组合进行测试
  • 验证工作区配置
  • 测试错误处理场景

Hub Pipeline 验证清单

  • 存在必需的 Hub 元数据
  • 示例 PipelineRun 正常运行
  • 所有参数均有描述文档
  • 工作区描述完整
  • Task 引用使用 Hub 目录任务
  • 验证平台兼容性
  • 包含用于清理的 finally 任务

Hub Pipelines 安全性

Hub 安全要求

  • Pipeline 定义中不得硬编码密钥
  • 使用安全的任务引用
  • 记录所需的服务账户权限
  • 遵循最小权限原则
  • 验证输入参数

文档要求

Hub Pipeline 文档标准

  • 在 pipeline 目录中包含完整的 README.md
  • 记录完整的工作流和用途
  • 提供清晰的参数说明
  • 包含使用示例和常见配置
  • 说明前置条件和依赖关系
  • 解释工作区需求
  • 包含故障排除指南

Hub 发布清单

✅ Hub 合规性

  • 存在必需的 Hub 元数据（标签和注解）
  • 版本标签与目录结构匹配
  • 所有参数均有清晰描述
  • 工作区文档完整
  • 使用 Hub 目录任务引用
  • 指定平台兼容性
  • 提供可用的示例 PipelineRun
  • 完整的 README，含使用示例
  • 通过 Hub 验证要求

✅ 质量标准

  • Pipeline 可跨环境复用
  • 实现错误处理和清理
  • 无硬编码值或密钥
  • 遵循安全最佳实践
  • 验证跨平台兼容性
  • 文档完整且准确
  • 通过并行执行优化性能