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 中的 Task 名称
      - name: version
        value: "0.9"      # Task 版本
    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: >-
    Hub 文档中的 Pipeline 描述
  params:
  - name: git-url
    description: Git 仓库 URL
  - name: image-name
    description: 容器镜像名称
    default: "myapp:latest"
  workspaces:
  - name: source-code
    description: 源代码工作区
  - name: registry-creds
    description: 分发注册表凭据
    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 目录中的 Task
      - 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 目录中的 Task
      - name: version
        value: "0.4"
    runAfter: [fetch-source]
    params:
    - name: image
      value: $(params.image-name)
    workspaces:
    - name: source
      workspace: source-code
    - name: dockerconfig
      workspace: registry-creds

  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 的 Task 组合

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

    Hub 工作区管理

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

    Hub Pipeline 可复用性

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

    Hub 测试要求

    必需的 Pipeline 测试文件

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

    Hub Pipeline 验证清单

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

    Hub Pipelines 安全性

    Hub 安全要求

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

    文档要求

    Hub Pipeline 文档标准

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

    Hub 发布清单

    ✅ Hub 合规性

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

    ✅ 质量标准

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