开发自定义步骤

本文使用自定义步骤模板文件来做一个简单的演示，为您介绍如何创建并在流水线中运行自定义步骤。

背景信息

为方便用户开发自定义步骤，持续交付提供了以下模板文件。

Dockerfile    # 用于构建步骤镜像
entrypoint.sh # 步骤执行脚本
step.yaml     # 用于描述步骤，包括名称、分类、描述、参数(及参数描述)

• Dockerfile、entrypoint.sh 用于制作自定义步骤的镜像。
• step.yaml 用于描述步骤，定义步骤的参数，以及参数对应前端组件的描述。

因此，开发自定义步骤需要以下几步。

1. 下载自定义步骤模板。
2. 根据实际业务需求，在本地编写自定义步骤模板文件。
3. 将编写完成的 Dockerfile、entrypoint.sh 文件构建成镜像并推送至镜像仓库，确保镜像可以公网无认证访问。
4. 将编写完成的 Dockerfile、entrypoint.sh、step.yaml 文件打包成 Zip 文件上传至持续交付。
5. 在流水线使用自定义步骤并运行，检验自定义步骤的效果。

使用限制

• 拥有 CPAdminAccess 权限的账号可以创建自定义步骤。子用户可联系对应火山引擎账号授予该权限，具体操作请参考 配置权限。
• 上传自定义步骤时，仅支持上传 Zip 文件，一次可上传 1 个文件，文件大小不超过 1 M。如需上传超过限制的 Zip 文件，请 提交工单 申请。
• 持续交付当前版本不支持下载已上传自定义步骤的历史文件。建议您上传自定义步骤后，不要删除本地的历史文件，后续更新自定义步骤时需要使用。
• 自定义步骤镜像必须可公开访问。

  说明

  如果您不希望自定义镜像被公开访问，推荐您使用下述方案：

  • 将构建的自定义步骤镜像上传至火山引擎私有镜像仓库。具体操作可参考 推送和拉取镜像。

  • 在容器服务安装镜像拉取免密组件，将私有镜像仓库设置为可免密拉取。具体操作可参考 安装免密组件。

  • 使用容器服务集群作为私有资源池, 运行流水线自定义步骤。具体操作可参考 创建私有资源池。

步骤一：下载模板文件

1. 登录 持续交付控制台。
2. 在左侧导航栏选择 模板市场 > 步骤模板， 进入 步骤模板 页面。
3. 单击 创建自定义步骤，弹出说明框。
4. 单击 下载自定义步骤模板，将自定义步骤.zip文件下载到本地。

步骤二：编写自定义步骤

根据实际业务需求，在本地编写 Dockerfile 、 entrypoint.sh 及 step.yaml 模板文件。
本示例直接使用 Dockerfile 模板文件、 entrypoint.sh 模板文件。对于 step.yaml 模板文件，本示例仅修改自定义步骤名称、sign 等必要参数，其余保持默认。
下文介绍这 3 个模板文件的作用、参数说明及编写时的注意事项。

Dockerfile 文件
Dockerfile 文件用于构建自定义步骤的镜像。系统提供的 Dockerfile 文件模板如下。

FROM cr-cn-beijing.volces.com/cp-test/debian:stretch
LABEL maintainer="xxx@bytedance.com"

ENV COMMAND=''

WORKDIR /workspace
ENTRYPOINT ["/entrypoint.sh"]
ADD entrypoint.sh /entrypoint.sh

entrypoint.sh 文件

entrypoint.sh 为自定义步骤执行的命令，entrypoint.sh 在流水线中运行时会以环境变量的方式获取来自流水线上下文的环境变量，以及用户通过 step.yaml 定义的入参。系统提供的 entrypoint.sh 文件模板如下。

#!/bin/bash

echo "hello world" # 输出 “hello world”
bash -c "$COMMAND" # 执行 step.yaml 文件中的 COMMAND

step.yaml 文件

step.yaml 用于描述步骤，系统提供的 step.yaml 文件模板如下。

name: demo # 名称, 用于展示自定义步骤的名称
sign: demo  # 步骤的唯一标识
image: cr-cn-beijing.volces.com/cp-test/custom-step-demo:v1.0.0 # 镜像地址
version: 1.0.0 # 自定义步骤版本, 需遵循 X.Y.Z 规范
description: this is description info # 描述
category: Build # 表示该自定义步骤的分类为“构建”
items: # 入参表单
- name: COMMAND
  label: 命令
  type: Shell
  defaultValue: |
    set -x
    echo "hello world"

请按照要求编写 step.yaml 文件，具体参数说明参见下表。

本示例使用的 step.yaml 文件如下。

name: 自定义步骤-demo
sign: customstep0829
image: cr-cn-beijing.volces.com/cp-test/custom-step-demo:v1.0.0 # 保持和模板相同，不做修改
version: 1.0.0 
description: 执行自定义步骤模板的内容
category: Tool
items: # 保持和模板相同，不做修改
- name: COMMAND
  label: 命令
  type: Shell
  defaultValue: |
    set -x
    echo "hello world"

步骤三：构建自定义步骤镜像并推送至镜像仓库

使用编写完成的 Dockerfile 和 entrypoint.sh 制作自定义步骤运行时所需的镜像。建议将构建好的镜像上传至火山引擎镜像仓库内，并将该仓库设置为公开。

步骤四：上传自定义步骤

1. 将编写好的 Dockerfile 、entrypoint.sh 及 step.yaml 打包为 Zip 文件。

2. 登录 持续交付控制台。

3. 在左侧导航栏选择 模板市场 > 步骤模板， 进入 步骤模板 页面。

4. 单击 创建自定义步骤，弹出说明框。

5. 单击 上传自定义模板，选择本地打包好的 Zip 文件，上传后，单击 保存文件。
   文件上传成功后，可在 步骤模板 > 自定义步骤 页面的对应分类下查看到该自定义步骤。新上传的自定义步骤默认为启用状态。

   

步骤五：使用自定义步骤

流水线运行自定义步骤时，会使用 step.yaml 中指定的镜像，并将 step.yaml 中定义的参数以环境变量的形式注入到执行的步骤中。

1. 在左侧导航栏选择 工作区，进入 工作区 页面。

2. 选择目标工作区名称，进入该工作区。

3. 单击 创建流水线，选择 空白模板，单击 确定，进入 编辑流水线 的 流程配置 页面。

4. 单击➕，新增阶段。

5. 单击 添加任务，选择 空白任务。

6. 单击 添加步骤，选择 自定义步骤，选择上一步创建的自定义步骤。

   

7. 步骤添加完成后，编辑命令框，将命令修改为"hello mystep !"，单击 确定，保存该步骤。
   

8. 单击 保存，保存该流水线。

9. 手动运行该流水线。
   自定义步骤运行成功，打印出“hello mystep !”。
   

   说明

   自定义步骤运行时长超过 2 h 后自动失败。