# workflow 必选项，用于定义流程包含的各个步骤，以及步骤之间的依赖关系。一个workflow由多个步骤组成，每个步骤可以执行特定的任务，比如运行容器、执行FPGA程序，或是调用Spark服务加速等任意的华为云服务。当前支持的类型为运行容器，即：**GCS.Job**。未来会支持其他类型的任务。 #### workflow格式 ``` workflow: <任务名称>: description: <当前步骤的描述> type: <任务类型> tool: <当前任务运行的工具+版本> resources: <执行任务需要的资源> commands: <容器中执行的命令，直接给出方式> commands_iter: <容器中执行的命令，变量迭代方式> condition: <当前步骤是否执行的条件> depends: <依赖的任务> ``` 表1GCS.Job参数属性说明 | 属性 | 是否必选 | 参数类型 | 参数描述 | |:---|:---|:---|:---| | 任务名称 | 是 | String | 基因容器具体步骤的任务名称。 小写字母打头，由小写字母数字中划线组成，长度为\[1, 40\]。 | | description | 否 | String | 当前步骤的描述信息，支持中文，长度为\[0, 255 \] | | type | 是 | String | GCS支持的任务类型，当前仅支持运行容器类，此处填写"GCS.Job"。 | | tool | 是 | String | 当前任务运行的工具及版本，格式为"tool_name: tool_version"。例如，0.7.12版本的bwa设置为"tool: bwa:0.7.12"。 须知： 指定的工具必须存在。 | | resources | 否 | Struct | 执行任务需要的资源，参数说明参见[表2 resources属性说明]。 | | commands | 否 | array\[string\] | 容器中执行的命令，数组长度表示并发数量。每个成员表示一个容器中执行的命令。提示：**可以是任意的Linux命令**。如： a） 直接写要执行的命令，如： echo helloworld; touch sample.txt b） 把要执行的命令放入待挂载卷中，xx.sh文件，这里直接调用，如：sh /path/to/xx.sh 并发示例： 如下示例中，commands有四行，则表示容器并发数量为4，每个容器分别执行不同的命令 ``` commands: - sh /obs/gcscli/run-xxx/run.sh 1 a - sh /obs/gcscli/run-xxx/run.sh 2 a - sh /obs/gcscli/run-xxx/run.sh 1 b - sh /obs/gcscli/run-xxx/run.sh 2 b ``` 提示： 如果命令行是**由多行组成**，可以使用yaml语法中的"\|"（保留换行符，整个字符串当做yaml中一个key的value）格式。这样就可以把大篇幅的命令行原封不动的拷贝过来，如： ``` commands: - | samtools merge -f -@ ${nthread} -b ${volume-path-sfs}/${sample}/mergelist.txt \ ${volume-path-sfs}/${sample}/${sample}.sort.bam && \ samtools flagstat ${volume-path-sfs}/${sample}/${sample}.sort.bam > ${volume-path-sfs}/${sample}/${sample}.sort.flagstat ``` 详见： [yaml语法](https://support.huaweicloud.com/tr-gcs/gcs_tr_01_0008.html)。 须知： 给定的command默认会使用/bin/sh解释器执行，如果需要使用其他解释器如/bin/bash执行脚本，可以通过在命令行前添加解释器来控制，例如： ``` commands: - bash /obs/gcscli/run-xxx/run.sh 1 a #方式1 - bash -c "echo helloworld" #方式2 ``` 说明： 此参数和commands_iter二选一。如果容器中执行的命令需要带变量，可以使用commands_iter，正常则使用commands。 | | commands_iter | 否 | Struct | 容器中执行的命令，和commands区别为，commands_iter支持带变量的shell脚本。数组行数表示并发的数量，参数说明请参见[表3 commands_iter属性说明]。 | | condition | 否 | bool | 某个步骤是否执行的条件，用于流程条件分支控制。可以是引用[inputs变量](https://support.huaweicloud.com/tr-gcs/gcs_tr_01_0004.html)，也可以根据上一步的执行结果来判断当前步骤是否执行。详见 [条件分支控制](https://support.huaweicloud.com/tr-gcs/gcs_tr_01_0010.html)。 | | depends | 否 | array\[Struct\] | 指定当前任务所依赖的其他任务，数组格式，参数说明请参见[表4 depends属性说明]。 | 表2resources属性说明 | 属性 | 是否必选 | 参数类型 | 参数描述 | |:---|:---|:---|:---| | memory | 否 | String | 所需内存资源大小，单位为G。此处填写"数字+单位"。 - 数字支持小数。 - 单位为G或是g。 例如，需要内存大小为4G，则此处可填写为"4G"或是"4g"。 ``` resources: memory: 4G ``` 须知： 请确保请求内存量，小于容器集群中最大节点剩余内存大小。 | | cpu | 否 | String | 所需CPU核数，单位为C。此处填写"数字+单位"。 - 数字支持小数。 - 单位为C或是c。 例如，所需CPU核数为0.5核，则此处可填写为 "0.5c" 或者 "0.5C"。 ``` resources: cpu: 0.5c ``` 须知： 请确保请求CPU核数，小于容器集群中最大节点剩余核数大小。 | | gpu | 否 | Number | 所需GPU卡数量，仅数字，无单位。此处填写 "数字"。 - 数字支持小数。（注：一般GPU推荐整数） 例如，需要1个GPU显卡，则此处可填写为 "1" 。 ``` resources: gpu: 1 ``` 须知： 请确保请求GPU卡数，小于容器集群中最大GPU节点剩余数大小。 | | options | 否 | Struct | gpu的配置参数，参数说明请参见[表3]。 例如： ``` options: gpu-type: nvidia.com/gpu-tesla-v100-16GB gpu-driver: gpu-418.126 ``` 须知： 该参数只有在CCI环境中才生效。 | 表3gpu的配置参数 | 属性 | 是否必选 | 参数类型 | 取值约束 | |:---|:---|:---|:---| | gpu-type | 否 | String | gpu的类型，当前支持3种类型。 - nvidia.com/gpu-tesla-v100-16GB：NVIDIA Tesla V100 16G显卡 - nvidia.com/gpu-tesla-v100-32GB：NVIDIA Tesla V100 32G显卡 - nvidia.com/gpu-tesla-t4：NVIDIA Tesla T4显卡 详细说明请参见[使用GPU](https://support.huaweicloud.com/devg-cci/cci_05_0004.html#section3)。 | | gpu-driver | 否 | String | gpu驱动的版本。当前支持如下两个版本。 - gpu-460.106：460.106版本，配套CUDA 11.2.2 Update 2 及以下CUDA Toolkit版本。 - gpu-418.126：418.126版本，配套CUDA 10.1 (10.1.105)及以下CUDA Toolkit版本。 详细说明请参见[使用GPU](https://support.huaweicloud.com/devg-cci/cci_05_0004.html#section3)。 | 表4commands_iter属性说明 | 属性 | 是否必选 | 参数类型 | 取值约束 | |:---|:---|:---|:---| | command | 是 | String | 带变量的任意Linux脚本，具体可以参考[commands属性说明]，变量由如下两种获取方式： - 从vars或者vars_iter传递过来的变量，引用方式与shell一致，如"${1}"表示取第一个参数，取第二个参数则用"${2}"，依次递增。其中vars和vars_iter参数，两个二选一填写。vars参数需要列出所有组合，vars_iter参数为自动遍历组合（详见该字段描述）。 - 基因容器提供的**内置变量"${item}"**，表示容器并发执行时，当前执行到了第几个容器，该计数从零开始。例如并发4个容器时，command命令为"echo ${item}"，则将按容器执行顺序，分别打印0，1，2，3。 | | vars | 否 | array\[array\] | 二维数组，做为command代入变量，表示手动列出所有组合。 说明： vars和vars_iter二选一。如果变量变化有固定规则，推荐使用vars_iter，可自动迭代变量，不用手动列出该变量的所有组合。 - 二维数组中，每一行的成员代表command命令中的变量${1}，${2}，${3}等。${1}即代表各行的第一个成员，${2}代表各行第二个成员，${3}代表各行第三个成员。 - 二维数组中，有几行表示command命令迭代执行几次，同时也代表容器并发数量。在command命令执行过程中，先代入数组第一行，再按次序代入第二行，第三行等，直到数组代入完成。数组的行数即容器并发数量。 例如，如下示例中，vars有四行，则表示容器并发数量为4。 ``` command: echo ${1} ${2} ${item} vars: - [0, 0] # 每行代表一个并发。成员按顺序分别传入${1}和${2}... - [0, 1] # 这个并发中，0 -> ${1}; 1 -> ${2} - [1, 0] # 这个并发中，1 -> ${1}; 0 -> ${2} - [1, 1] # 这个并发中，1 -> ${1}; 1 -> ${2} ``` 执行后， 启动4个容器， 第一个容器代入数组第一行，执行： ``` echo 0 0 0 ``` 第二个容器代入数组第二行，执行： ``` echo 0 1 1 ``` 第三个容器代入数组第三行，执行： ``` echo 1 0 2 ``` 第四个容器代入数组第四行，执行： ``` echo 1 1 3 ``` | | vars_iter | 否 | array\[array\] | 二维数组，做为command代入变量，表示自动遍历组合。 数组的第一行成员遍历代入command命令中的变量${1}，第二行成员遍历代入命令中的变量${2}，以此类推。 **示例：**如下示例表示4个容器并发，执行效果与vars示例相同。 ``` command: echo ${1} ${2} vars_iter: - [0, 1] # 第一行表示${1} 的迭代范围 - [0, 1] # 第二行表示${2} 的迭代范围 ``` 如果某一行的数组成员很多，可以使用**range函数**。range(1,4)表示数组\[1, 2, 3\]。前闭区间，后开区间，例如： ``` vars_iter: - range(0, 4) ``` 等同于： ``` vars_iter: - [0, 1, 2, 3] ``` **提示** **：** 迭代范围可以使用输入变量，见[inputs](https://support.huaweicloud.com/tr-gcs/gcs_tr_01_0004.html)，如： ``` inputs: samples: # <=== 定义数组类型的变量 type: array default: [a, b, c, d] workflow: job-a: command: echo ${1} vars_iter: - ${samples} # <=== 使用此数组作为迭代范围 ``` | 表5depends属性说明 | 属性 | 是否必选 | 参数类型 | 取值约束 | |:---|:---|:---|:---| | target | 是 | String | 所依赖的任务名，请确保指定的任务名必需存在。 | | type | 否 | String | 依赖方式，可取值为： - whole，整体依赖，**此为默认值**。 - iterate，迭代式依赖。 例如，如果步骤一和步骤二都并发执行100个容器。 - 设置whole则表示步骤一全部执行结束后，才能开始执行步骤二。 - 设置iterate则表示，步骤一的1号执行完成，就可以开始执行步骤二的1号，并行执行，可以提高整体的并发效率。 | #### workflow配置样例 ``` workflow: job-a: tool: nginx:latest type: GCS.Job resources: memory: 2G cpu: 1c commands: - sleep `expr 3 \* ${wait-base}`; echo ${output-prefix}job-a | tee -a ${obs}/${output}/${result}; job-b: tool: nginx:latest type: GCS.Job commands_iter: command: sleep `expr ${1} \* ${wait-base}`; echo ${output-prefix}job-b-${item} | tee -a ${obs}/${output}/${result}; vars_iter: - range(0, 4) #内置函数range，实际表示 [0, 1, 2, 3]。最终并发执行4个容器，每个使用数组成员替代 depends: - target: job-a type: whole #可不写，whole为默认值 job-c: tool: nginx:latest type: GCS.Job resources: memory: 8G cpu: 2c commands_iter: command: sleep `expr ${1} \* ${wait-base}`; echo ${output-prefix}job-c-${item} | tee -a ${obs}/${output}/${result}; vars_iter: - [3, 20] #最终并发2个容器，每个使用数组成员替代 depends: - target: job-a type: iterate - target: job-b ```