自定义工作流

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

# 基本概念

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

# 新建

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

create_common_workflow

# 界面化配置

# 基本信息

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

common_workflow_config

# 阶段

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

common_workflow_config

参数说明：

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

# 任务

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

common_workflow_config

# 构建任务

common_workflow_config

参数说明：

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

提示

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

# 部署任务

common_workflow_config

参数说明：

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

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

# 通用任务

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

执行环境：参考构建环境配置
代码信息：参考代码信息配置
变量：参考通用任务变量
添加步骤：包括添加 Shell 脚本执行以及文件存储，可参考更多构建配置
高级配置：参考高级配置

common_workflow_config

# 自定义任务

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

# 人工审核

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

common_workflow_config

参数说明：

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

# YAML 方式配置

# 配置说明

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

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

1
2
3
4
5
6
7
8

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

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

1
2
3
4
5
6
7

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

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

1
2
3
4
5
6
7
8
9

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

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

name:「任务的名称」                    // 必填项
type: zadig-build                    // 必填项，指定为 zadig-build
spec:                                // 必填项
  docker_registry_id: 「镜像仓库 ID」
  service_and_builds:                // 服务组件的构建信息，可配置多个服务组件
    - service_module: 「服务组件名称」
      service_name: 「服务名称」
      build_name: 「构建名称」
      key_vals:                      // 构建变量信息，支持配置字符串和枚举类型的变量，分别见如下 string 和 choice 类型的变量示例
        - key: username              // 构建变量名称
          value: zadig               // 构建变量值
          is_credential: false       // 是否加密，默认为 false
          type: string
        - key: password
          value: v1
          is_credential: false
          type: choice
          choice_option:             // 枚举类型变量的可选值
            - v1
            - v2
    - service_module: 「服务组件名称」  // 更多服务组件的构建信息
      service_name: 「服务名称」
      build_name: 「构建名称」
      ...

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

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

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

1
2
3
4
5
6

# YAML 样例

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

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

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

name: pre-release-deploy
stages:
  - name: 构建
    parallel: true
    jobs:
      - name: build-myapps
        type: zadig-build
        spec:
          docker_registry_id: 6247eb0832a15f910118318c
          service_and_builds:
            - build_name: simple-service-build-nginx-1
              key_vals:
                - is_credential: false
                  key: username
                  type: string
                  value: admin
                - is_credential: false
                  choice_option:
                    - v1
                    - v2
                  key: password
                  type: choice
                  value: v1
              service_module: myapp-1
              service_name: a
            - build_name: simple-service-build-myapp-2
              service_module: myapp-2
              service_name: b
  - name: 部署
    approval:
      enabled: true
      approve_users:
        - user_id: af14dfd2-b57d-11ec-9511-9e1ccf83f7b3
          user_name: admin
        - user_id: 2d59d2f4-c6a5-11ec-a89e-2e173601a9ce
          user_name: zadig
      timeout: 120
      needed_approvers: 1
      description: '预发布环境部署，需审核通过方可执行'
    jobs:
      - name: deploy
        type: zadig-deploy
        spec:
          env: pre-release
          job_name: build-myapps
          source: fromjob
project: simple-service
description: 预发布环境部署
multi_run: false

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49

# 变量

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

# 项目

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

支持的变量见下表：

变量	说明
`{{.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

说明如下：

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

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

common_workflow_config

# 构建任务

内置构建任务中的变量。

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

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

common_workflow_config

# 部署任务

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

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

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

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

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

common_workflow_config

# 通用任务

通用任务中的变量。

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

common_workflow_config

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

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