文档

自定义步骤 Flow-CLI 子命令:step

更新时间:

Flow-CLI工具全新升级,老版工具不再支持新建步骤,请升级工具到最新版本后使用(企业已有自定义步骤使用不受影响)。

Flow-CLI 是云效流水线 Flow 推出的一款命令行工具,用以管理 Flow 中各种资源,子命令 step 可以让用户在流水线中运行自定义镜像及命令达到扩展流水线能力的效果。

Flow 中一个流水线中运行的镜像被称为一个“步骤”,步骤是有一段描述 yaml 和一个 docker 镜像组成的一个最小运行单元,yaml 描述决定步骤运行时的入参,docker 镜像决定步骤运行的环境;这篇文档将引导用户在 Flow 上创建一个自定义步骤。

下载安装

操作系统

下载地址

macOS

arm

https://rdc-plugin-storage.oss-cn-beijing.aliyuncs.com/flow-cli/1.0/darwin_arm64_flow_cli

amd

https://rdc-plugin-storage.oss-cn-beijing.aliyuncs.com/flow-cli/1.0/darwin_amd64_flow_cli

windows

arm

https://rdc-plugin-storage.oss-cn-beijing.aliyuncs.com/flow-cli/1.0/windows_arm64_flow_cli.exe

amd

https://rdc-plugin-storage.oss-cn-beijing.aliyuncs.com/flow-cli/1.0/windows_amd64_flow_cli.exe

linux

arm

https://rdc-plugin-storage.oss-cn-beijing.aliyuncs.com/flow-cli/1.0/linux_arm64_flow_cli

amd

https://rdc-plugin-storage.oss-cn-beijing.aliyuncs.com/flow-cli/1.0/linux_amd64_flow_cli

以 Mac 为例:

$ curl https://rdc-plugin-storage.oss-cn-beijing.aliyuncs.com/flow-cli/1.0/darwin_arm64_flow_cli -o /usr/local/bin/flow && chmod +x /usr/local/bin/flow 
$ flow -v                       # 输出版本信息说明安装成功

登录 Flow

$ flow login                    # 登录

浏览器会打开进入 Flow 登录页面,如果已经登录会提示 success,登录成功后命令行会提示选择账号下企业,输入企业对应的数字进入企业。

新建步骤

$ flow step init <your-step-sign>               # 新建步骤

<your-step-sign> 更换为你自己的步骤标识,注意:step 标识为整个云效唯一,若被其他步骤占用则无法创建成功。

这个命令会在本地创建如下文件:

.step
  |- ..
  |- entry.sh               # 步骤需要的基础脚本
<your-step-sign>
  |- Dockerfile             # 用于构建步骤镜像
  |- step.sh                # 步骤执行脚本
  |- step.yaml              # 用于描述步骤所有信息的 yaml
  • entry.sh:步骤执行的基础入口脚本,非特殊情况无需修改。

  • step.yaml:用于定义 step 执行所需的输入参数,包括 step 的运行的镜像环境地址,以及在流水线配置时该步骤所需的配置参数。

  • step.sh:步骤运行时执行的脚本文件,你可以在该脚本内获取流水线的环境变量、step.yaml 中配置的参数,并定义你想要执行脚本逻辑。

  • Dockerfile:用于构建步骤镜像的 Dockerfile文件,当你进行步骤推送时,会根据此文件构建你的步骤环境镜像,并推送到 step.yaml 中定义的镜像地址中。

当你完成自定义步骤配置推送后,流水线执行你的自定义步骤时,会先从你的环境镜像地址拉取镜像,并在该环境中执行你所定义的脚本文件。

对初始化文件进行简单修改,下面通过一个示例详细讲解 3 个关键文件的具体作用。

1. step.yaml 里定义了步骤有关的描述:

---
name: 自定义步骤              # 步骤名称
sign: <your-step-sign>      # 步骤唯一标识
description: 我的第一个步骤   # 步骤描述
image: <docker-image-url>   # 步骤运行环境镜像
items:                      # 入参表单
  - label: 执行命令
    name: command
    type: shell
    value: |
      # input your command here
      echo hello,world!
  - label: 参数 abc
    name: abc
    type: input

其中 image 为该步骤环境镜像的地址,请填写您自己的镜像仓库地址。当你进行步骤推送时,会根据 Dockerfile 进行镜像构建并推送至该地址。

重要

请确保该镜像地址为公网不通过认证可以公开访问的地址,以确保构建机可以正常拉取。

items 定义了流水线编辑页面中该供用户配置的输入表单,支持多种前端组件,如输入框 input, 下拉款 dropdown, 复选框 checkbox 等;示例中 type 类型 Shell 为一个脚本输入框。更多语法见步骤 yaml 描述语言。示例中定义了两个 item,分别为类型为 Shell 的 command、类型为 input 的 abc。

2. step.sh 既步骤执行的命令,step.sh 在流水线中运行时可以以环境变量的方式获取到来自流水线上下文的系统变量,以及用户通过编辑页面、运行传入的方式写入的入参,脚本中列举了一部分可供使用的环境变量:

#!/bin/sh
set -e                                     # 脚本遇到错误退出
# 系统提供参数,从流水线上下文获取
echo [INFO] PIPELINE_ID=$PIPELINE_ID       # 流水线ID
echo [INFO] PIPELINE_NAME=$PIPELINE_NAME   # 流水线名称
echo [INFO] BUILD_NUMBER=$BUILD_NUMBER     # 流水线运行实例编号
echo [INFO] EMPLOYEE_ID=$EMPLOYEE_ID       # 触发流水线用户ID
echo [INFO] WORK_SPACE=$WORK_SPACE         # /root/workspace容器中目录
echo [INFO] PROJECT_DIR=$PROJECT_DIR       # 代码库根路径,默认为/root/workspace/code
echo [INFO] PLUGIN_DIR=$PLUGIN_DIR         # 插件路径,默认为/root/workspace/plugins
echo [INFO] BUILD_JOB_ID=$BUILD_JOB_ID     # build-service 任务ID
cd $PROJECT_DIR                            # 进入代码库所在路径
sh -ex $WORK_SPACE/user_command.sh         # 执行 command 脚本
echo ${abc}                                # 输出 abc

示例中通过 sh -ex $WORK_SPACE/user_command.sh 直接执行在步骤中配置的指令。另外,将我们在 step.yaml 中配置的参数 abc 进行了输出。

说明

user_command.sh 为 Flow 的一个默认规则,会将 step.yaml 中,name 为 command 的 Shell 脚本转化为 user_command.sh。当然,你也可以定义其他的 Shell 脚本,通过环境变量来获取脚本指令。

3. Dockerfile 中包含了步骤运行时所需要的环境,目前步骤所需的基础镜像必须是公网不通过认证可拉取的。

FROM registry.cn-beijing.aliyuncs.com/rdc-builds/base:1.0
MAINTAINER xxx <xxx@alibaba-inc.com>
COPY .step/*.sh /root/
COPY <your-step-sign>/step.sh /root/step.sh
RUN chmod +x /root/*.sh
ENTRYPOINT [ "/root/entry.sh"]

Dockerfile 本质是提供你执行 step.sh 的镜像环境,你可以:

  • 直接在 Dockerfile 中安装你所需的依赖。

  • 或修改基础镜像地址,请确保基础镜像中已经安装了 jq

上线步骤

$ flow step publish <your-step-sign>             # 发布镜像

这个命令会执行两个动作:

1. 将本地的 Dockerfile 构建成为 step.yaml 中的 docker 镜像并 push 到远端仓库。请确保本地已经安装了 Docker。

2. 将 step.yaml 描述的步骤原信息 publish 到云效的服务器。

使用flow step ls可以查看已经发布的步骤

使用步骤

进入 Flow 流水线页面,从空模板创建流水线,点击阶段 ->添加步骤->自定义步骤,找到刚才创建的步骤。

123213

步骤添加完成之后,可以对步骤的内容进行配置,点击保存并运行

123213

可以看到步骤在流水线中运行起来,并打印出 hello world! 和 123。

1231231

更新步骤

若你需要更新步骤,可以修改 step.yaml、step.sh、Dockerfile 文件后,重新执行 flow step publish <your-step-sign>,Flow CLI 会重新进行镜像构建和步骤上传。

若你进入流水线编辑页后,发现步骤参数配置内容未发生变化,可以尝试刷新缓存。

其他操作

image

image