workflow-components

README

腾讯云工作流组件打包指引

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

---

工作流组件规范

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

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

TencentHubComponent 格式规范:

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

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

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

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

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

输入值、输出值 name 规范:

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

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

---

工作流输入输出流转

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

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

1. 工作流的全局变量
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的用户名是您TencentHub的用户名，密码是您开通TencentHub用户时设置的密码

将镜像推送到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]

---