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

更新时间:2025-04-30 03:08:07

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

重要

Flow-CLI 工具全新升级 V2 版本,请前往 自定义步骤CLI工具(新版)- 推荐查看使用。

下载安装

以 Mac 为例,执行以下命令下载 Flow-CLI 工具并赋予执行权限。

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输出版本信息说明安装成功。

root@test-01:~# flow -v
Flow version 1.0

登录 Flow

  1. 执行以下命令登录 Flow。

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

新建步骤

Flow 中一个流水线中运行的镜像被称为一个“步骤”,步骤是由一段描述 yaml 和一个 docker 镜像组成的一个最小运行单元,yaml 描述决定步骤运行时的入参,docker 镜像决定步骤运行的环境。
  1. 执行以下命令新建步骤,注意将 <your-step-sign> 更换为你自己的步骤标识。

    step 标识为整个云效唯一,若被其他步骤占用则无法创建成功。
    flow step init <your-step-sign>
  2. 这个命令会在本地创建如下文件:

    .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. 对初始化文件进行简单修改。

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

    下面通过一个示例详细讲解 3 个关键文件的具体作用。

    • 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。

    • 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 脚本,通过环境变量来获取脚本指令。

    • 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

上线步骤

  1. 执行以下命令发布镜像:

    flow step publish <your-step-sign>

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

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

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

  2. 使用flow step ls查看已经发布的步骤。

使用步骤

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

    123213

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

    123213

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

    1231231

更新步骤

如需更新步骤,在修改 step.yamlstep.shDockerfile 文件后,重新执行 flow step publish <your-step-sign>,Flow CLI 会重新进行镜像构建和步骤上传。

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

  • 本页导读 (1)
  • 下载安装
  • 登录 Flow
  • 新建步骤
  • 上线步骤
  • 使用步骤
  • 更新步骤
AI助理

点击开启售前

在线咨询服务

你好,我是AI助理

可以解答问题、推荐解决方案等