Alauda DevOps Pipelines Docs

Writing Pipelines for Tekton Hub

TOC

Overview

This guide covers the specific requirements and best practices for creating Pipelines that work with Tekton Hub catalogs. It focuses on Hub-specific metadata, validation, and composition standards.

Hub-Specific Metadata

Required Labels for Hub

metadata:
  name: my-custom-pipeline
  labels:
    app.kubernetes.io/version: "0.1"  # Must match catalog version directory

Required Annotations for 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 References

Catalog Task Reference for Hub

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 Categories and Tags

Standard Pipeline Categories

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

Effective Pipeline Tagging

  • Use workflow-specific tags (ci, cd, cicd)
  • Include technology stacks (nodejs, java, python, golang)
  • Add deployment targets (kubernetes, cloud, containers)

Hub Parameter Standards

Hub-Specific Parameter Requirements

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 Template

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: docker-config
    description: Docker 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: 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 Best Practices

Task Composition for Hub

  • Use Tasks from the same Hub catalog when possible
  • Reference specific task versions for stability
  • Provide clear parameter mappings
  • Document task dependencies

Workspace Management for Hub

  • Use descriptive workspace names and descriptions
  • Mark optional workspaces as optional: true
  • Document workspace data flow between tasks
  • Minimize workspace requirements where possible

Pipeline Reusability for Hub

  • Design for common use cases
  • Provide flexible parameters
  • Include reasonable defaults
  • Support multiple deployment scenarios

Hub Testing Requirements

Required Pipeline Test Files

  • Provide working samples/ directory with PipelineRun examples
  • Include run.yaml demonstrating typical usage
  • Test with various parameter combinations
  • Validate workspace configurations
  • Test error handling scenarios

Hub Pipeline Validation Checklist

  • Required Hub metadata present
  • Sample PipelineRun works correctly
  • All parameters documented with descriptions
  • Workspaces properly described
  • Task references use Hub catalog tasks
  • Platform compatibility verified
  • Finally tasks included for cleanup

Security for Hub Pipelines

Hub Security Requirements

  • No hardcoded secrets in Pipeline definitions
  • Use secure task references
  • Document required service account permissions
  • Follow principle of least privilege
  • Validate input parameters

Documentation Requirements

Hub Pipeline Documentation Standards

  • Include comprehensive README.md in pipeline directory
  • Document the complete workflow and purpose
  • Provide clear parameter descriptions
  • Include usage examples and common configurations
  • Document prerequisites and dependencies
  • Explain workspace requirements
  • Include troubleshooting guide

Hub Publishing Checklist

✅ Hub Compliance

  • Required Hub metadata (labels and annotations) present
  • Version label matches directory structure
  • All parameters have clear descriptions
  • Workspaces properly documented
  • Uses Hub catalog task references
  • Platform compatibility specified
  • Working sample PipelineRun provided
  • Complete README with usage examples
  • Passes Hub validation requirements

✅ Quality Standards

  • Pipeline is reusable across environments
  • Error handling and cleanup implemented
  • No hardcoded values or secrets
  • Security best practices followed
  • Cross-platform compatibility verified
  • Documentation is complete and accurate
  • Performance optimized with parallel execution where possible