开发自定义步骤

为了满足不同企业的个性化需求，充分发挥团队的创造性，持续交付开放了自定义步骤能力，支持团队成员将内部得心应手的工具封装成自定义步骤，提高业务交付效率。本文为您介绍如何开发自定义步骤并上传至持续交付。

背景信息

自定义步骤由一个 YAML 描述文件构成。YAML 文件中包含自定义步骤的基本信息、步骤入参、步骤出参、步骤的执行脚本 script 及步骤的镜像 image。运行自定义步骤时，流水线会基于当前 YAML 起一组 Pod，执行 script 任务。

本文使用的自定义步骤 YAML 文件示例如下，您可基于此模板快速改造适合本团队的自定义步骤。

# 自定义步骤名称，必填项。支持英文大小写、数字、“-”中横线，长度 2~50，不允许重名。
step: v2-custom-step
# 自定义步骤的显示名称，必填项。支持中英文大小写、数字、“-”中横线，长度 2~50。用作步骤名称展示，不允许为空、不允许重名。
displayName: 自定义步骤v2-demo-doc
# 自定义步骤描述，非必填。200个字符以内，支持中英文大小写特殊字符。
description: 自定义步骤v2 demo，介绍自定义步骤的基础用法，包括引用配置项参数、流水线变量等用法
# 分类，非必填。目前仅支持以下分类：【构建】Build 、【测试】Test、 【部署】Deploy、 【镜像仓库】Registry、 【命令执行】Command、 【其他】Other
category: Other
# 运行时镜像，必填项。支持公有镜像和私有镜像。私有镜像必须配置镜像访问凭证 imageCredential 参数。
image: xxx.cr.volces.com/ns/busybox:latest
# 拉取私有镜像的凭证信息，非必填。下文以火山引擎镜像仓库举例。
imageCredential:
  # 镜像仓库地址。仅需填写 host 地址。
  registry: xxx.cr.volces.com
  # 镜像仓库用户名。
  username: xxx@1400******
  # 镜像仓库访问密码，支持永久密码和临时密码。注意：临时密码存在有效期，临时密码失效后无法正常拉取私有镜像。
  # 前端展示自定义步骤 YAML 时，密码会做脱敏处理。
  password: xxxxxxxxx
# 运行脚本，必填项、不能为空。作用类似于 Dockerfile 文件中的 ENTRYPOINT，用于指定容器启动程序及参数。
# 可通过 export xxx=$(inputs.KEY) 注入步骤入参。注意 KEY 值与待引用 inputs.name 的值保持一致，否则将无法成功引用该步骤入参。
# 可通过 export xxx=$(预置变量名) 注入流水线预置变量。
script: |
  # 引用自定义步骤 input 配置项参数的示例。获取设置的命令并执行。
  $(inputs.cmd)
  # 引用自定义步骤 input 配置项参数的示例。获取配置项的值并输出。
  export ENV=$(inputs.pipeline-env)
  echo "ENV：$ENV"
  # 引用流水线预置变量的示例。打印流水线ID。
  echo "PIPELINE_ID：$(PIPELINE_ID)"
  # 引用流水线预置变量的示例。打印流水线执行时间。
  echo "DATETIME：$(DATETIME)"
# 定义步骤的输入信息，非必填。支持配置多条步骤入参。详细介绍请参见 https://www.volcengine.com/docs/6461/1108787。
inputs:
    # 字段名称，必填项。支持英文大小写、数字、“-”中横线，长度 2~50，不允许重名。
  - name: cmd
    # 字段显示名称，必填项。支持中英文大小写、数字、“-”中横线，长度 2~50，用作参数名称展示，不允许为空、不允许重名。
    displayName: 执行自定义命令
    description: 执行一条自定义命令
    # 字段类型，必填项。
    type: string
    # 字段默认值，选填项。
    defaultValue: echo hello world
    # 字段是否必填，必填项。设置为true时，步骤配置页面字段前会显示小红星，保存时会校验字段是否填写。
    required: true
    # 字段配置样式。
    uiConfig:
      type: CodeEditor
  - name: pipeline-env
    displayName: 变量
    description: 流水线环境变量引用示范
    type: string
    defaultValue:
    required: true
    uiConfig:
      type: Input
# 定义步骤的输出信息，非必填。当前仅支持 name、displayName、type 参数。type 默认为 string。
# 本示例不使用 outputs。
# outputs: 
#   - name: xxx
#     displayName: xxx
#     type: string

前提条件

已准备好自定义步骤使用的 Docker 镜像。建议上传至火山引擎镜像仓库。上传至火山引擎镜像仓库相关操作可参见 推送和拉取镜像。

使用限制

• 拥有 CPAdminAccess 权限的账号可创建自定义步骤。子用户可联系对应火山引擎账号授予该权限，具体操作请参考 配置权限。

• 上传自定义步骤时，仅支持上传.yaml文件，一次可上传 1 个文件，文件大小不超过 1 M。如需上传更大的文件，请 提交工单 申请。

• 暂不支持下载已上传自定义步骤的历史文件。建议您上传自定义步骤后，不要删除本地的历史文件，后续更新自定义步骤时需要使用。

• 自定义步骤暂不支持版本管理功能。

• 通过在 YAML 文件中配置镜像访问凭证 imageCredential，可实现自定义步骤使用私有镜像。如果您对镜像安全性有更高的要求，推荐使用以下方案。

  说明

  方案介绍：

  1. 将构建的自定义步骤镜像上传至火山引擎私有镜像仓库。具体操作可参考 推送和拉取镜像。
  2. 在容器服务安装镜像拉取免密组件，将私有镜像仓库设置为可免密拉取。具体操作可参考 安装免密组件。
  3. 使用容器服务集群作为私有资源池, 运行流水线自定义步骤。具体操作可参考 创建私有资源池。

操作步骤

1. 在本地编写自定义步骤 YAML 文件，并保存为*.yaml 文件。

2. 登录 持续交付控制台，在左侧导航栏选择 模板市场 > 步骤模板。

3. 在步骤模板页面，单击 创建自定义步骤，弹出创建自定义步骤面板。

4. 单击 上传自定义步骤 YAML 文件，在本地选择刚编写好的*.yaml 文件。

   

5. 上传完成后，单击 保存文件。
   上传成功的自定义步骤将展示在对应分类下。

   

后续操作

开发者将自定义步骤上传至持续交付后，团队成员便可在流水线中使用。具体操作可参见 使用自定义步骤。