Alauda DevOps Pipelines Docs
简体中文

StepActions

StepAction 是 Tekton Pipelines 中由 Step 执行的可重用且可脚本化的工作单元。StepActions 允许您定义容器化操作，这些操作可以在不同的 Tasks 之间被引用和复用。

目录

为什么需要 StepActions

传统 Task 的挑战

在 StepActions 出现之前，Tasks 面临以下限制：

  • 可重用性：Task 中定义的 Steps 无法轻松提取和复用
  • 可维护性：公共步骤逻辑必须在不同 Tasks 中重复编写
  • 版本控制：难以单独对步骤进行版本管理，而不影响整个 Task
  • 一致性：难以确保公共操作的一致实现

Tekton 的解决方案

StepActions 通过以下方式解决这些挑战：

  • 步骤级别的可重用性：将公共操作封装为可复用组件
  • 声明式定义：将 StepActions 定义为 Kubernetes 自定义资源
  • 参数化：接受参数以定制行为
  • 结果输出：生成可被其他步骤消费的结果
  • 资源控制：资源需求与 Tasks 分开定义

优势

  • 模块化：将复杂操作拆分为可复用组件
  • 一致性：确保公共操作在 Tasks 中实现一致
  • 可维护性：更新 StepAction 即可惠及所有引用的 Tasks
  • 清晰性：将“做什么”（StepAction）与“何时做”（Step）分离
  • 版本控制：StepActions 可独立于 Tasks 进行版本管理

适用场景

StepActions 适用于多种场景，包括：

  • 常见操作：Git 克隆、镜像构建、安全扫描
  • 标准化工具：代码检查器、格式化工具、测试运行器
  • 组织特定逻辑：自定义部署流程、审批工作流
  • 共享工具：版本生成、配置校验
  • 集成组件：服务交互、API 操作

约束与限制

  • StepActions 只能在 Steps 中使用
  • 不能在 Steps 之间传递 Step Results
  • 参数不能直接在脚本中使用（必须通过环境变量）
  • StepActions 不能独立运行（不同于 TaskRuns 或 PipelineRuns）
  • 需要将 enable-step-actions 功能标志设置为 "true"

原则

StepAction 执行模型

当 Step 引用 StepAction 时：

  1. Step 提供必要的上下文和参数
  2. StepAction 定义容器镜像和执行逻辑
  3. Step 可覆盖资源和超时等部分配置
  4. 被引用的 StepAction 执行其定义的命令或脚本
  5. StepAction 的结果可被后续步骤消费

引用模型

StepActions 不是 Steps 的组成部分。相反：

  • Step 是可执行组件，可以引用 StepAction
  • Step 负责编排和上下文
  • StepAction 提供可复用逻辑
  • Step 可以引用本地或远程的 StepActions

配置示例

基础 StepAction 示例

apiVersion: tekton.dev/v1beta1
kind: StepAction
metadata:
  name: git-clone
spec:
  params:
    - name: url
      type: string
    - name: revision
      type: string
      default: "main"
    - name: depth
      type: string
      default: "1"
  results:
    - name: commit
      description: The commit SHA that was checked out
  image: alpine/git
  script: |
    git clone --depth $(params.depth) --branch $(params.revision) $(params.url) /workspace
    cd /workspace
    echo -n $(git rev-parse HEAD) > $(results.commit.path)

在 Task 中引用 StepAction

apiVersion: tekton.dev/v1
kind: Task
metadata:
  name: build-with-git
spec:
  workspaces:
    - name: source
  params:
    - name: repo-url
      type: string
  steps:
    - name: clone
      ref:
        name: git-clone
      params:
        - name: url
          value: $(params.repo-url)
        - name: revision
          value: main
      workingDir: $(workspaces.source.path)
    - name: build
      image: golang
      workingDir: $(workspaces.source.path)
      script: |
        go build -o app .

重要参数

参数

参数允许在 Step 引用 StepActions 时进行定制。

使用场景

  • 配置连接详情
  • 指定目标或目的地
  • 设置操作标志
  • 定义版本信息
  • 控制行为

原则

StepActions 中的参数：

  • 在 StepAction 规范中声明
  • 可以有默认值
  • 由引用的 Step 传入
  • 支持字符串、数组和对象类型
  • 不能直接在脚本中使用（应通过环境变量使用）

配置示例

apiVersion: tekton.dev/v1beta1
kind: StepAction
metadata:
  name: image-builder
spec:
  params:
    - name: image
      type: object
      properties:
        name:
          type: string
        tag:
          type: string
    - name: context
      type: string
      default: "."
  image: docker
  env:
    - name: IMAGE_NAME
      value: $(params.image.name)
    - name: IMAGE_TAG
      value: $(params.image.tag)
  script: |
    docker build -t $IMAGE_NAME:$IMAGE_TAG $(params.context)

结果

结果允许 StepActions 输出值，供其他 Steps 或 Tasks 使用。

使用场景

  • 共享构建信息
  • 传递生成的标识符
  • 传达状态信息
  • 提供工件位置

原则

结果：

  • 在 StepAction 规范中声明
  • 由 StepAction 写入特定文件路径
  • 可供后续 Steps 或 Tasks 使用

配置示例

apiVersion: tekton.dev/v1beta1
kind: StepAction
metadata:
  name: version-generator
spec:
  results:
    - name: version
      description: The generated semantic version
    - name: build-id
      description: The unique build identifier
  image: alpine
  script: |
    VERSION="1.0.$(date +%s)"
    echo -n $VERSION > $(results.version.path)
    echo -n "build-$RANDOM-$RANDOM" > $(results.build-id.path)

WorkingDir

WorkingDir 允许指定 StepAction 的工作目录。

使用场景

  • 设置操作的正确上下文
  • 确保命令在正确位置运行
  • 保证 StepAction 使用的一致性

配置示例

apiVersion: tekton.dev/v1beta1
kind: StepAction
metadata:
  name: file-processor
spec:
  workingDir: /workspace
  image: ubuntu
  script: |
    ls -la
    find . -name "*.txt" -exec cat {} \;

SecurityContext

SecurityContext 允许配置 StepAction 的安全设置。

使用场景

  • 设置容器权限
  • 配置用户和组 ID
  • 管理安全约束

配置示例

apiVersion: tekton.dev/v1beta1
kind: StepAction
metadata:
  name: secure-operation
spec:
  securityContext:
    runAsNonRoot: true
    runAsUser: 1000
    allowPrivilegeEscalation: false
  image: ubuntu
  script: |
    echo "Running as $(id -u)"

VolumeMounts

VolumeMounts 允许 StepActions 访问外部存储。

使用场景

  • 访问配置文件
  • 存储持久数据
  • 在步骤间共享信息

配置示例

apiVersion: tekton.dev/v1beta1
kind: StepAction
metadata:
  name: config-reader
spec:
  volumeMounts:
    - name: config-volume
      mountPath: /etc/config
  image: ubuntu
  script: |
    cat /etc/config/settings.json

When Expressions

When Expressions 允许控制引用 StepAction 的 Step 是否执行。

使用场景

  • 基于参数的条件执行
  • 根据工作空间可用性跳过步骤
  • 根据前一步骤结果控制工作流

配置示例

apiVersion: tekton.dev/v1
kind: Task
metadata:
  name: conditional-task
spec:
  params:
    - name: run-tests
      type: string
      default: "true"
  steps:
    - name: test-runner
      ref:
        name: run-tests
      when:
        - input: "$(params.run-tests)"
          operator: in
          values: ["true"]

远程 StepActions

StepActions 可以从远程位置（如 git 仓库）引用。

使用场景

  • 集中管理 StepActions
  • 对 StepActions 进行版本控制
  • 跨组织共享 StepActions

配置示例

apiVersion: tekton.dev/v1
kind: TaskRun
metadata:
  name: remote-stepaction-run
spec:
  taskSpec:
    steps:
      - name: remote-action
        ref:
          resolver: git
          params:
            - name: url
              value: https://github.com/organization/stepactions.git
            - name: revision
              value: main
            - name: pathInRepo
              value: actions/my-action.yaml

参考资料