文档中心 Tencent Hub 工作流 工作流组件规范

工作流组件规范

最近更新时间:2019-09-11 17:40:45

工作流组件(component) 是工作流的执行单元, 用于执行特定的 devops 操作。每个工作流组件本质上是一个 docker 容器镜像, 理论上任何 docker 容器镜像都可以作为工作流组件使用。 Tencent Hub 工作流系统还提供了一套组件定义规范, 遵循此规范的组件在 Tencent Hub 工作流系统能达到更好的使用效果。

工作流组件规范

遵循此规范的组件在 Tencent Hub 工作流编排中可以在 UI 控制台选中,并解析该组件的输入/输出在 UI 控制台中,有更好的操作体验和更好的使用效果。

存储于 Tencent Hub 的工作流组件需要有一个名为TencentHubComponentImage Label 来进行标识, 该 label 的内容是一个固定格式的 json 字符串, 在编写时需要进行正确的转义。

Tencent Hub Component 格式规范:

字段 类型 必要/可选 说明
desc string 可选 组件描述信息
input array 可选 组件输入列表
output array 可选 组件输出列表

组件输入列表input 格式如下:

字段 类型 必要/可选 说明
name string 必要 输入值名称
desc string 可选 输入值描述
default array 可选 输入值的默认展示值

组件输入列表output 格式如下:

字段 类型 必要/可选 说明
name string 必要 输出值名称
desc string 可选 输出值描述

输入值、输出值 name 规范:

输入值、输出值在工作流中将转换为环境变量进行流转, 因此输入值、输出值 名称应该符合环境变量的命名约定:

  • 由字母数字下划线构成
  • 字母建议使用全大写, 用下划线进行分割

工作流输入输出流转

工作流中的组件可以定义输入输出, 下游组件可以使用上游已结束组件的输出, 组件的输入通过环境变量读取, 组件的输入通过特定格式的 stdout 进行输出。

组件的输入包括 2 个来源:

  • 工作流的全局变量
  • 上游组件的输出

组件输出给下游的变量需要在 stdout 中以前缀[JOB_OUT]进行包裹,用=连接输出值得 key 和 value, 多个输出值通过换行进行分隔:

[JOB_OUT] ARTIFACT = ./vendor
[JOB_OUT] IMAGE_ID = c442b20ea805

组件执行状态判断

组件最终的执行状态有:

  • 执行成功
  • 执行失败
  • 执行超时

对于组件退出码大于 0 的情况,工作流会标记组件执行失败。

对于组件退出码等于 0 的情况,默认认为组件执行成功,但是在某些业务场景下,用户希望标记该执行为失败,这种情况可以通过特殊的组件输出JOB_RESULT = false进行强制标记组件失败。

腾讯云工作流系统环境变量

workflow 引擎在执行用户工作流时,会根据场景生成一些预置的全局环境变量,在整个 flow 的 job 中都可以按需读取使用:

环境变量名称 含义 生成场景 内容说明
_WORKFLOW_BUILD_TYPE 构建类型, 表示工作流被触发的方式 默认生成 manually: 手动触发; webhook: webhook触发; api: API触发
_WORKFLOW_GIT_CLONE_URL git 克隆地址 当工作流和已授权的 git 关联 包含 Basic Auth 信息的 git 克隆地址
_WORKFLOW_GIT_REF git 引用 同上 可以是 git tag, git branch 或者 git commit
_WORKFLOW_GIT_TYPE git 引用类型 同上 用于指示_WORKFLOW_GIT_REF的类型, 可选值: tag, branch, commit

工作流组件示例

dockerfile 示例如下:

FROM ubuntu
RUN apt-get -yqq update && apt-get -yqq install docker.io && apt-get -yqq install git
RUN mkdir -p /root/src
WORKDIR /root/src
COPY . /usr/bin/
CMD ["component-docker"]

LABEL TencentHubComponent='{\
  "description": "TencentHub container component, build docker image",\
  "input": [\
    {"name": "GIT_CLONE_URL", "desc": "required, git clone url"},\
    {"name": "GIT_REF", "desc": "optional, git target reference, it can be a git commit, git tag or git branch"},\
    {"name": "GIT_TPYE", "desc": "optional, type of `GIT_REF`, it can be branch, tag or commit"},\
    {"name": "IMAGE", "desc": "optional, the result docker image tag, like `hub.cloud.tencent.com/fox/nodejs`, it can with or without tag"},\
    {"name": "IMAGE_TAG_FORMAT", "desc": "optional, image tag format"},\
    {"name": "IMAGE_TAG", "desc": "optional, the result docker image tag, default is `latest`"},\
    {"name": "EXTRA_IMAGE_TAG", "desc": "optional, extra docker image tag"},\
    {"name": "BUILD_WORKDIR", "default": ".", "desc": "optional, the work dir to run docker build"},\
    {"name": "DOCKERFILE_PATH", "default": "Dockerfile", "desc": "optional, Dockerfile path`"},\
    {"name": "BUILD_ARGS", "desc": "optional, arguments pass to docker build as build-arg, it must be valid json string, like `{\"HTTP_PROXY\":\"http://10.20.30.2:1234\",\"TIMEOUT\":\"10\"}`"}\
  ],\
  "output": [\
    {"name": "IMAGE", "desc": "url of pushed image without tag"},\
    {"name": "IMAGE_ID", "desc": "ID of pushed image tag"},\
    {"name": "IMAGE_DIGEST", "desc": "Image digest of pushed image tag"}\
  ]\
}'

在 docker 环境中使用

docker build -t [ImageName:tag] .

编译出镜像组件,推送到镜像仓库中,即可以在工作流中使用该镜像组件。docker 镜像基础知识请参考 指引

推送镜像仓库指引

登录腾讯云 docker registry

sudo docker login --username=yourname hub.tencentyun.com

登录 registry 的用户名是您 Tencent Hub 的用户名,密码是您开通 Tencent Hub 用户时设置的密码

将镜像推送到 registry

sudo docker login --username=yourname hub.tencentyun.com
sudo docker tag [ImageId] hub.tencentyun.com/3321337994/my_awesome_component:[tag]

其中 [ImageId] 为您编译出的镜像 ID,[tag] 请根据您的镜像版本信息进行自定义填写。

sudo docker push hub.tencentyun.com/yourname/my_awesome_component:[tag]