You need to enable JavaScript to run this app.
导航
开发自定义步骤
最近更新时间:2023.09.27 14:25:33首次发布时间:2022.04.15 00:17:29

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

背景信息

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

Dockerfile    # 用于构建步骤镜像
entrypoint.sh # 步骤执行脚本
step.yaml     # 用于描述步骤,包括名称、分类、描述、参数(及参数描述)
  • Dockerfile、entrypoint.sh 用于制作自定义步骤的镜像。
  • step.yaml 用于描述步骤,定义步骤的参数,以及参数对应前端组件的描述。

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

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

使用限制

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

    说明

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

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

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

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

步骤一:下载模板文件

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

步骤二:编写自定义步骤

根据实际业务需求,在本地编写 Dockerfile 、 entrypoint.shstep.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

说明

目前自定义步骤使用的镜像要求必须可公开访问,为保证信息安全,编写 Dockerfile 时请遵循以下建议。

  • Dockerfile 中请勿存在敏感信息。
  • 请选用来源安全的基础镜像。

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 文件,具体参数说明参见下表。

参数是否必填说明

name

填写自定义步骤的名称。不允许重名,不允许以CP_开头,不允许与系统预置环境变量重名。
支持中英文大小写、数字和中划线(-),长度 2~50 个字符。

sign

填写自定义步骤的的唯一标识,不允许重复。
支持英文小写、数字和中划线(-),长度 2~50 个字符。中划线(-)必须在中间,不允许为开头或结尾 。

category

填写自定义步骤的分类。用于前端分类展示自定义步骤。
目前支持的分类如下。

  • Test(测试)
  • Build(构建)
  • Deploy(部署)
  • Registry(镜像仓库)
  • Artifact(制品库)
  • Tool(工具)
  • Service(服务集成)
  • Other(其他)

version

填写自定义步骤的版本号。
格式为x.y.z,其中,x、y、z 均为 [0,100] 的整数。

description

填写自定义步骤的描述,可以为空。
支持中英文大小写及特殊字符,200 个字符以内。

image

填写自定义步骤运行时所需的镜像地址。
要求构建集群可正常拉取该镜像,无需二次密码验证。建议将所需镜像上传至火山引擎镜像仓库内,并设置为公开。

items

定义一个参数组件,以供前端展示对应参数。支持多种前端组件,非必填。组件的标准属性请参考 步骤 YAML 描述语言
items 中的每个参数,在运行时以环境变量形式注入到对应步骤。

注意

  • 请按照参数说明的要求编写 step.yaml 文件,不符合规则将导致自定义步骤上传失败。
  • step.yaml 中填写的 image 地址需要与步骤三中推送的镜像地址一致。

本示例使用的 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 制作自定义步骤运行时所需的镜像。建议将构建好的镜像上传至火山引擎镜像仓库内,并将该仓库设置为公开。

注意

此处推送的镜像地址需要与 step.yaml 中填写的 image 地址保持一致。

步骤四:上传自定义步骤

说明

  • 仅支持上传 Zip 文件,一次可上传 1 个文件,文件大小不超过 1 M。
  • 如需上传超过限制的 Zip 文件,请 提交工单 申请。
  1. 将编写好的 Dockerfile 、entrypoint.shstep.yaml 打包为 Zip 文件。

  2. 登录 持续交付控制台

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

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

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

    alt

步骤五:使用自定义步骤

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

说明

流水线执行自定义步骤时:

  • 先执行系统脚本,进行初始化,比如准备环境变量(代码源、上游镜像产物)。
  • 后执行用户的自定义步骤脚本( entrypoint.sh )。
  1. 在左侧导航栏选择 工作区,进入 工作区 页面。

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

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

  4. 单击➕,新增阶段。

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

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

    alt

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

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

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

    说明

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