Alauda DevOps Pipelines Docs
  • 简体中文

    • 为 Tekton Hub 编写 Pipelines

    目录

    概述Hub 特定元数据Hub 所需标签Hub 所需注解Hub Task 引用Hub 的目录 Task 引用Hub 类别和标签标准 Pipeline 类别有效的 Pipeline 标签策略Hub 参数标准Hub 特定参数要求Hub Pipeline 模板Hub 最佳实践Hub 的 Task 组合Hub 的 Workspace 管理Hub 的 Pipeline 可复用性Hub 测试要求必需的 Pipeline 测试文件Hub Pipeline 验证清单Hub Pipelines 的安全性Hub 安全要求文档要求Hub Pipeline 文档标准Hub 发布清单✅ Hub 合规性✅ 质量标准

    概述

    本指南介绍了创建可与 Tekton Hub 目录配合使用的 Pipelines 时的具体要求和最佳实践。重点关注 Hub 特定的元数据、验证和组合标准。

    Hub 特定元数据

    Hub 所需标签

    metadata:
  name: my-custom-pipeline
  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: "Integration & Delivery"  # Hub category
    tekton.dev/tags: "ci,build,test,deploy"     # Hub search tags
    tekton.dev/displayName: "CI/CD Pipeline"    # Hub display name
    tekton.dev/platforms: "linux/amd64,linux/arm64"  # Supported platforms

    Hub Task 引用

    Hub 的目录 Task 引用

    spec:
  tasks:
  - name: git-clone
    taskRef:
      resolver: hub
      params:
      - name: catalog
        value: "catalog"  # Hub catalog name
      - name: type
        value: tekton
      - name: kind
        value: task
      - name: name
        value: git-clone  # Task name from Hub
      - name: version
        value: "0.9"      # Task version
    params:
    - name: url
      value: $(params.repo-url)
    workspaces:
    - name: output
      workspace: source-code

    Hub 类别和标签

    标准 Pipeline 类别

    • 集成与交付
    • 持续集成
    • 持续交付
    • 测试
    • 安全
    • 构建与打包

    有效的 Pipeline 标签策略

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

    Hub 参数标准

    Hub 特定参数要求

    spec:
  params:
  - name: repo-url
    description: "Git repository URL for source code"  # Clear description for Hub UI
    type: string
  - name: target-environment
    description: "Deployment target environment"
    type: string
    default: "development"  # Sensible default
  - name: build-args
    description: "Additional build arguments"
    type: array
    default: []  # Safe default for arrays

    Hub Pipeline 模板

    apiVersion: tekton.dev/v1
kind: Pipeline
metadata:
  name: my-hub-pipeline
  labels:
    app.kubernetes.io/version: "0.1"  # Match catalog version
  annotations:
    tekton.dev/pipelines.minVersion: "0.17.0"
    tekton.dev/categories: "Integration & Delivery"  # Hub category
    tekton.dev/tags: "ci,build,deploy"               # Hub search tags
    tekton.dev/displayName: "My CI/CD Pipeline"      # Hub display name
    tekton.dev/platforms: "linux/amd64,linux/arm64"  # Platforms
spec:
  description: >-
    Pipeline description for Hub documentation
  params:
  - name: git-url
    description: Git repository URL
  - name: image-name
    description: Container image name
    default: "myapp:latest"
  workspaces:
  - name: source-code
    description: Source code workspace
  - name: registry-creds
    description: Distribution registry credentials
    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  # Reference Hub catalog 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    # Reference Hub catalog task
      - name: version
        value: "0.4"
    runAfter: [fetch-source]
    params:
    - name: image
      value: $(params.image-name)
    workspaces:
    - name: source
      workspace: source-code
    - name: registryconfig
      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 catalog 中的 Tasks
    • 引用特定的 Task 版本以保证稳定性
    • 提供清晰的参数映射
    • 文档化 Task 依赖关系

    Hub 的 Workspace 管理

    • 使用具有描述性的 workspace 名称和说明
    • 将可选 workspace 标记为 optional: true
    • 文档化 Task 之间的 workspace 数据流
    • 尽可能减少 workspace 要求

    Hub 的 Pipeline 可复用性

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

    Hub 测试要求

    必需的 Pipeline 测试文件

    • 提供可正常运行的 samples/ 目录以及 PipelineRun 示例
    • 包含演示典型用法的 run.yaml
    • 使用不同的参数组合进行测试
    • 验证 workspace 配置
    • 测试错误处理场景

    Hub Pipeline 验证清单

    • 必需的 Hub 元数据已存在
    • 示例 PipelineRun 可正常工作
    • 所有参数都已用描述进行文档化
    • workspaces 已正确说明
    • Task 引用使用 Hub catalog tasks
    • 已验证平台兼容性
    • 包含用于清理的 finally tasks

    Hub Pipelines 的安全性

    Hub 安全要求

    • 在 Pipeline 定义中不要硬编码 secrets
    • 使用安全的 task references
    • 文档化所需的 service account 权限
    • 遵循最小权限原则
    • 验证输入参数

    文档要求

    Hub Pipeline 文档标准

    • 在 pipeline 目录中包含完整的 README.md
    • 文档化完整工作流和用途
    • 提供清晰的参数说明
    • 包含用法示例和常见配置
    • 文档化先决条件和依赖项
    • 说明 workspace 要求
    • 包含故障排查指南

    Hub 发布清单

    ✅ Hub 合规性

    • 必需的 Hub 元数据（labels 和 annotations）已存在
    • 版本标签与目录结构匹配
    • 所有参数都有清晰的说明
    • workspaces 已正确文档化
    • 使用了 Hub catalog task references
    • 已指定平台兼容性
    • 提供可运行的 sample PipelineRun
    • 包含完整的 README 和用法示例
    • 满足 Hub 验证要求

    ✅ 质量标准

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