自定义工作流

自定义工作流中提供了充分的开放性，支持自由编排工作流流程，自定义执行步骤，下面展开介绍相关概念和具体使用。

基本概念

  • 自定义工作流：对工作流流程自由编排，由一系列阶段组成
  • 阶段：对工作流执行阶段进行逻辑分组，比如构建阶段、部署阶段…多个阶段串行运行，一个阶段可包括多个任务
  • 任务：一个完整的任务，比如构建、部署、测试、自定义任务…多个任务可串行执行或并发执行

新建

进入项目中点击新建工作流，选择自定义工作流，系统提供界面化和 YAML 两种方式来配置自定义工作流。

create_common_workflow create_common_workflow

界面化配置

基本信息

包括工作流名称和描述，同一项目下的工作流名称应唯一。

common_workflow_config

阶段

点击 +阶段 增加新的阶段配置。

common_workflow_config

参数说明：

  • 阶段名称：在同一个自定义工作流中，阶段名称唯一
  • 并发执行：开启后，在该阶段下配置的多个任务将会并发执行
  • 前置步骤：可按需开启人工审核。开启后，需要审核通过，该阶段下的任务才会被执行

任务

点击阶段下方的 +任务 为阶段增加任务配置，系统目前支持构建、部署、通用任务、Kubernetes 部署、测试、自定义任务 等任务类型。

common_workflow_config

构建任务

common_workflow_config

参数说明：

  • 任务名称：支持 32 位以内的小写英文字母、数字或者中划线，且以小写英文字母开头；在同一个自定义工作流中，任务名称需唯一
  • 镜像仓库：选择镜像仓库，当构建任务执行完成功后，构建出的镜像（即内置 $IMAGE 变量）会被推送到所选仓库中
  • 服务组件：选择服务组件以及该服务组件使用的构建名称，点击展开构建配置的 设置 可配置所选中的变量值以及代码库默认分支
    • 变量：参考 构建任务变量
    • 分支配置：选择代码库并指定默认分支，执行工作流时会默认使用指定的分支

提示

  1. 内置构建任务执行结束后会输出 $IMAGE 变量（页面中不可见，系统隐式逻辑），可用于内置部署任务中。
  2. 内置构建任务中不再支持 $ENV_NAME 构建变量，需要确保构建脚本中未使用该变量。
  3. 暂不支持使用 Jenkins 构建。

部署任务

common_workflow_config

参数说明：

  • 任务名称：支持 32 位以内的小写英文字母、数字或者中划线，且以小写英文字母开头；在同一个自定义工作流中，任务名称需唯一
  • 环境：选择要部署的环境，支持三种配置方式，具体请参考 部署任务变量 中关于环境信息的描述
  • 服务：配置要部署的服务，支持两种配置方式，具体请参考 部署任务变量 中关于服务信息的描述
  • 服务状态检测：若开启，部署任务会轮询服务运行状态，在部署超时之前该服务正常运行，任务状态才为成功

部署超时设置可参考 服务策略配置

通用任务

支持拉取代码、执行 Shell 脚本、文件存储等功能。

common_workflow_config common_workflow_config

Kubernetes 部署任务

部署指定集群指定命名空间中的容器。

common_workflow_config

参数说明：

  • 任务名称：在同一个自定义工作流中，任务名称需唯一
  • 镜像仓库：执行 Kubernetes 部署任务时，从哪个镜像仓库获取镜像来部署目标容器
  • 集群：待部署容器所在的集群
  • 命名空间：待部署容器所在的命名空间
  • 容器：指定命名空间中的容器应用（目前支持 Deployment 资源及 Statefulset 资源）
  • 容器状态检测：若开启，部署任务会轮询容器运行状态，在部署超时之前该容器正常运行，任务状态才为成功
  • 超时时间：容器部署超时时间

测试任务

支持在自定义工作流中引用项目下的测试配置。

common_workflow_config

选择具体的测试配置后，可对测试配置中的变量以及代码库默认分支进行设置。

common_workflow_config common_workflow_config

自定义任务

自己定义任务的实现，在工作流中配置自定义任务，详细使用方法请参考 自定义任务。

人工审核

开启阶段配置中的人工审核，在该阶段执行之前会触发审核。

common_workflow_config

参数说明：

  • 超时时间：从触发审核的时间点开始算起，当超过超时时间后视为审核超时失败，后续阶段中的任务将不会被执行
  • 审核人：选择希望参与审核的人员
  • 需要审核人数：当审核通过的人数满足此处指定的值时，即视为整个审核通过，该阶段中的任务会正常执行

YAML 方式配置

配置说明

用 YAML 文件的方式定义工作流，YAML 内容的整体结构描述如下：

  1. name:「工作流名称」                // 必填项，全局唯一，匹配 ^[a-z0-9-]{1,32}$
  2. stages:                          // 必填项，多个阶段将会按照先后顺序执行
  3.   - 「阶段 1 的配置」
  4.   - 「阶段 2 的配置」
  5.   - 「更多阶段的配置...」
  6. project: 「工作流所属项目名称」      // 必填项
  7. description: 「工作流描述」
  8. multi_run: 「可选值：true/false」  // 当同时触发多次工作流时，多条任务是否能并行执行，默认为 false

其中每一个阶段的具体配置如下：

  1. name: 「阶段的名称」              // 必填项
  2. parallel: 「可选值：true/false」  // 该阶段下的多个任务是否可以并发执行，默认为 false
  3. approval: 「人工审核配置」         // 非必填，按需配置
  4. jobs:                           // 必填项
  5.   - 「任务 1 的配置」
  6.   - 「任务 2 的配置」
  7.   - 「更多任务的配置...」

人工审核的具体配置如下：

  1. enabled: true
  2. approve_users:                     // 审核人信息，可配置多个
  3.   - user_id: 「审核人 ID」
  4.     user_name: 「审核人昵称」
  5.   - user_id: 「...」
  6.     user_name: 「...」
  7. timeout: 「审核超时时间」             // 整数类型，单位：分钟
  8. needed_approvers: 「需要审核的人数」  // 整数类型
  9. description: 「审核描述信息」         // 非必填

目前内置了构建和部署两种类型的任务，构建任务的具体配置如下：

在指定的构建中有相关构建变量配置时，在 YAML 中设置构建变量才有效。

  1. name:「任务的名称」                    // 必填项
  2. type: zadig-build                    // 必填项，指定为 zadig-build
  3. spec:                                // 必填项
  4.   docker_registry_id: 「镜像仓库 ID」
  5.   service_and_builds:                // 服务组件的构建信息，可配置多个服务组件
  6.     - service_module: 「服务组件名称」
  7.       service_name: 「服务名称」
  8.       build_name: 「构建名称」
  9.       key_vals:                      // 构建变量信息，支持配置字符串和枚举类型的变量，分别见如下 string 和 choice 类型的变量示例
  10.         - key: username              // 构建变量名称
  11.           value: zadig               // 构建变量值
  12.           is_credential: false       // 是否加密，默认为 false
  13.           type: string
  14.         - key: password
  15.           value: v1
  16.           is_credential: false
  17.           type: choice
  18.           choice_option:             // 枚举类型变量的可选值
  19.             - v1
  20.             - v2
  21.     - service_module: 「服务组件名称」  // 更多服务组件的构建信息
  22.       service_name: 「服务名称」
  23.       build_name: 「构建名称」
  24.       ...

内置部署任务的具体配置如下：

  1. name: 「任务的名称」                    // 必填项
  2. type: zadig-deploy                   // 指定为 zadig-deploy
  3. spec:
  4.   env: 「部署环境」                    // 必填项
  5.   source: 「部署时使用的服务镜像的来源」  // 必填项，可选：runtime（运行时输入） / fromjob（其他任务输出）
  6.   job_name: 「任务的名称」             // 当 source 为 fromjob 时需配置

YAML 样例

使用以下工作流配置为例：

  1. 第一个阶段：包含构建任务，并行构建 2 个服务（myapp-1 和 myapp-2）
  2. 第二个阶段：包含部署任务并开启人工审核，使用上述构建任务中的镜像产物来部署 pre-release 环境

对应的完整 YAML 配置示例如下，供参考：

  1. name: pre-release-deploy
  2. stages:
  3.   - name: 构建
  4.     parallel: true
  5.     jobs:
  6.       - name: build-myapps
  7.         type: zadig-build
  8.         spec:
  9.           docker_registry_id: 6247eb0832a15f910118318c
  10.           service_and_builds:
  11.             - build_name: simple-service-build-nginx-1
  12.               key_vals:
  13.                 - is_credential: false
  14.                   key: username
  15.                   type: string
  16.                   value: admin
  17.                 - is_credential: false
  18.                   choice_option:
  19.                     - v1
  20.                     - v2
  21.                   key: password
  22.                   type: choice
  23.                   value: v1
  24.               service_module: myapp-1
  25.               service_name: a
  26.             - build_name: simple-service-build-myapp-2
  27.               service_module: myapp-2
  28.               service_name: b
  29.   - name: 部署
  30.     approval:
  31.       enabled: true
  32.       approve_users:
  33.         - user_id: af14dfd2-b57d-11ec-9511-9e1ccf83f7b3
  34.           user_name: admin
  35.         - user_id: 2d59d2f4-c6a5-11ec-a89e-2e173601a9ce
  36.           user_name: zadig
  37.       timeout: 120
  38.       needed_approvers: 1
  39.       description: '预发布环境部署，需审核通过方可执行'
  40.     jobs:
  41.       - name: deploy
  42.         type: zadig-deploy
  43.         spec:
  44.           env: pre-release
  45.           job_name: build-myapps
  46.           source: fromjob
  47. project: simple-service
  48. description: 预发布环境部署
  49. multi_run: false

变量

自定义工作流中提供丰富的变量能力，以支持参数化配置工作流，并且在阶段和任务之间传递信息。以下分不同的使用范围分别介绍。

项目

项目级别的变量，可用于当前项目的所有自定义工作流中。

支持的变量见下表：

变量说明
{{.project}}项目的名称，下图例中即为 simple-service-demo

common_workflow_config

工作流

工作流级别的变量，可用于当前工作流的构建任务/部署任务/测试任务/通用任务/自定义任务中。

包括内置变量和自定义变量。

内置变量

支持的内置变量见下表：

变量说明
{{.workflow.name}}工作流的名称，下图例中即为 pre-release-deploy
{{.workflow.task.id}}工作流任务的 ID 序号，下图例中即为 1
{{.workflow.task.creator}}工作流任务的执行人，下图例中即为 admin
{{.workflow.task.timestamp}}工作流任务创建时的 Unix 时间戳，下图例中即为 1660555623

common_workflow_config

自定义变量

编辑工作流，点击页面右侧的 变量 进入自定义变量配置页面。

common_workflow_config

common_workflow_config

说明如下：

  • 类型：支持字符串/多行文本/枚举类型，其中字符串为单行文本
  • 键：自定义变量的 key，可以使用 {{.workflow.params.key}} 的形式为构建/部署/通用/自定义任务中的变量赋值
  • 值：自定义变量的值，支持以下两种配置方式：
    • 运行时输入：执行工作流时，在工作流变量设置中指定该变量的值
    • 固定值：指定变量的值，工作流执行时即使用该固定值，页面中该变量不可见

上图例中 LOG_LEVEL 和 MYSQL_USER_DB 的值为运行时输入，ISSUER_URL 的值为固定值，执行工作流时效果如下：

common_workflow_config

构建任务

内置构建任务中的变量。

变量的键和类型在此处不可更改，变量定义请阅读 构建配置 中的自定义构建变量部分。支持以下三种方式设置变量的值：

  • 运行时输入：执行工作流时再指定该变量的值
  • 固定值：指定变量的值，工作流执行时即使用该固定值，页面中该变量不可见
  • 全局变量：使用全局变量为构建任务中的变量赋值，工作流执行时会自动对全局变量进行渲染。全局变量包括 项目变量 和 工作流变量

common_workflow_config

部署任务

部署任务中的环境信息和服务信息。

环境信息支持以下三种配置方式：

  • 运行时输入：执行工作流时再指定部署环境
  • 固定值：设置部署环境为固定值，执行工作流时不可再更改
  • 全局变量：使用全局变量为环境赋值，工作流执行时会自动对全局变量进行渲染替换。全局变量包括 项目变量 和 工作流变量

服务信息支持以下两种配置方式：

  • 其他任务输出：可选择前置构建任务，使用任务中的 $IMAGE 变量来部署服务（如果前置构建任务中构建了多个服务，则部署任务中也会部署多个服务）
  • 运行时输入：执行工作流时手动指定服务的镜像

common_workflow_config

Kubernetes 部署任务

内置 Kubernetes 部署任务中的容器信息。

容器信息支持以下两种配置方式：

  • 运行时输入：执行工作流时再指定要部署的容器
  • 固定值：设置待部署容器为固定值，执行工作流时不可再更改

common_workflow_config

测试任务

测试任务中的变量信息。

支持以下三种配置方式：

  • 运行时输入：执行工作流时再指定要测试配置中的变量值
  • 固定值：设置测试配置中的变量为固定值，执行工作流时不可再更改
  • 全局变量：使用全局变量为测试任务中的变量赋值，工作流执行时会自动对全局变量进行渲染。全局变量包括 项目变量 和 工作流变量

common_workflow_config

通用任务

通用任务中的变量。

包括内置变量和自定义变量。

common_workflow_config

内置变量请参考 构建变量 中关于内置构建变量的描述，自定义变量说明如下：

  • 类型：支持创建字符串类型和枚举类型的自定义变量
  • 键：自定义变量的 key，可在 添加步骤 中通过 $key 的形式来使用
  • 值：自定义变量的值，支持以下三种配置方式：
    • 运行时输入：执行工作流时再指定该变量的值
    • 固定值：指定变量的值，工作流执行时即使用该固定值，页面中该变量不可见
    • 全局变量：使用全局变量为通用任务中的自定义变量赋值，工作流执行时会自动对全局变量进行渲染。全局变量包括 项目变量 和 工作流变量

自定义任务

自定义任务中的变量。

在自定义任务的 YAML 文件中定义，YAML 定义请参考 工作流任务，变量值的配置支持以下三种方式：

  • 运行时输入：执行工作流时再指定该变量的值
  • 固定值：指定变量的值，工作流执行时即使用该固定值，页面中该变量不可见
  • 全局变量：使用全局变量为通用任务中的自定义变量赋值，工作流执行时会自动对全局变量进行渲染。全局变量包括 项目变量 和 工作流变量

common_workflow_config

触发器配置

包括 Git 触发器和定时器。

Git 触发器

为工作流配置 Webhook 触发器，当满足触发条件的事件发生时会自动触发工作流执行，暂不支持通过 SSH 协议或 AccessToken 方式接入的代码源。

点击右侧的 触发器 -> 选择 Git 触发器即可配置，实现代码变更自动触发工作流。

common_workflow_config common_workflow_config common_workflow_config

参数说明：

  • 工作流执行变量：希望被 Webhook 触发执行的任务，以及任务中的具体配置
  • 其他参数：请参考 触发器基本配置 中的描述

定时器

点击右侧的 触发器 -> 选择 定时器。

common_workflow_config common_workflow_config

触发方式以及时间配置可参考 定时器配置，在工作流执行变量中可设置定时运行的任务以及任务中的变量配置。

common_workflow_config

通知配置

编辑工作流，点击右侧的 通知 进入通知配置页面。

common_workflow_config

目前支持配置工作流通知到飞书/企业微信/钉钉中，详细的参数说明可参考：IM 状态通知。

common_workflow_config

高级配置

在高级配置中开启并发运行策略后，多次触发工作流执行产生的多条工作流任务将会并发执行，提升工作流运行效率。

common_workflow_config

自定义工作流样例

可在自定义工作流中自由编排流程，下面简单举例几种场景。

场景一：构建镜像到不同的仓库

配置多个构建任务，每个任务中指定不同的镜像仓库。

common_workflow_demo

场景二：同时部署多个环境

配置多个部署任务，每个任务中指定不同的环境。

common_workflow_demo

场景三：使用不同的镜像仓库来部署不同的环境

配置多个构建任务，每个构建任务中指定不同的镜像仓库；为每个环境配置部署任务，服务来源选择其他任务输出并指定对应任务。

common_workflow_demo

场景四：审核通过后再部署环境

部署阶段配置中增加人工审核。

common_workflow_demo common_workflow_demo

在部署步骤执行之前会触发审核，审核通过后工作流才会继续执行。

common_workflow_demo

执行

点击执行工作流，可修改工作流变量的值，按需选择被执行的任务：

若工作流变量的值被设置为固定值，则执行工作流时该变量在页面中不可见。

run_common_workflow

点击具体的构建任务可查看构建日志：

任务名称规则为：服务名-服务组件名-任务名

run_common_workflow