备案控制台
文档
产品文档
输入文档关键字查找
首页 云效 操作指南 流水线 快速入门 更多原理说明 流水线 Runner

流水线 Runner

更新时间：
一键部署
产品详情
相关技术圈
我的收藏

云效流水线 Runner 是安装在用户构建机和部署主机上的一个本地服务。这个服务使用长轮询的方式与云效流水线服务端通信，拉取相应的构建任务或部署任务，并将运行过程中的日志和运行状态同步回云效流水线服务端。

1. 安装 Runner

Runner 的作用是作为流水线构建或部署的通道，安装 Runner 的机器需要归属于一个构建集群或者一个主机组中，因此需要首先创建私有构建集群或者主机组。

  • 进入Flow首页 -> 全局设置 -> 构建集群管理，点击 新建构建集群。用于流水线任务构建环境。

  • 进入Flow首页 -> 全局设置 -> 主机组管理，点击 新建主机组。可用于流水线主机部署任务。

image.png

image.png

在私有构建集群和主机组中添加主机的流程类似，以下主要以构建集群添加主机为例来描述如何使用Runner。

1.1 网络连通性要求

Runner使用长轮询的方式和云效流水线服务端进行通信，因此需要安装 Runner 的机器可以访问到云效流水线服务端。如果使用 手动安装Runner 的方式安装 Runner，则需要主机可以访问以下公网服务：

  • https://devops-build-new.aliyuncs.com

  • https://gray-devops-build.aliyuncs.com

如果你使用的是以下区域的阿里云ECS：北京、杭州、张家口、深圳、上海、青岛、呼和浩特、新加坡、河源、广州、乌兰察布、成都，并且使用 阿里云ECS 的方式安装 Runner，则 Runner 会自动通过相应阿里云区域内的内网端点连接到流水线服务端，ECS 主机本身不需要可以访问公网。

注：如果是向构建集群中添加主机，则无论是通过 阿里云ECS 方式安装Runner，还是 手动安装Runner ，都需要这台主机可以访问公网，因为在构建过程中，Runner 可能会拉取所需的公网地址的镜像。

1.2 主机要求

流水线Runner支持Linux、Windows、macOS主机的接入。其中：

  • Linux 操作系统需要支持以下服务之一：Systemd、Upstart、System V。

  • Windows 操作系统需要支持Windows service。

对于上述操作系统，均支持 amd64 和 arm64 的芯片架构。

为了安装Runner，在 Linux 上需要使用 root 用户，在 Windows 上需要使用 Administrator 用户，在 macOS 上可以使用任意用户。

1.3 在主机上安装Runner

进入Flow首页 -> 全局设置 -> 构建集群管理，找到并进入目标构建集群详情页，点击 接入新节点 的按钮来接入新的构建主机。

image

选择你需要的操作系统，然后选择添加方式：

  • 手动安装Runner。复制安装命令，并在主机上执行即可，如上图所示。

  • 阿里云ECS。

    • 按照提示，按需创建对应阿里云账号的ECS服务连接

    • 选择对应的ECS主机，云效流水线会通过云助手下发安装命令，安装完成之后可以在页面上查看安装日志。

image

image

对于Linux和Windows主机，可以通过手动安装和阿里云ECS两种方式安装Runner，对于macOS主机，仅支持通过手动安装的方式安装Runner。

在所有操作系统上，都是以服务的形式安装Runner。

  • 在 Linux 上，Runner支持以下几种服务类型：Systemd、Upstart、System V。如果主机支持多种服务类型，则按照上述的顺序从上到下选择服务类型来启动Runner。可以在Runner的安装日志中看到实际选择的是那种服务类型：

image

  • 在 Windows 上使用 Windows service 启动 Runner。

  • 在 macOS 上使用 Launchd 启动 Runner。

1.4 Runner 服务命名

云效是一个租户化的服务，在不同的云效企业中可以在同一台主机上安装不同的服务。

云效的每一个企业有一个命名空间，是一个24位的随机字母串，比如aaaaaaaaaaaaaaaaaaaaaaaa。且当前安装的Runner软件的版本是v0.1.0，则服务名称为runner-v0.1.1-be-aaaaaaaaaaaaaaaaaaaaaaaa。如果另一个企业的命名空间为bbbbbbbbbbbbbbbbbbbbbbbb，那么可以同时在机器上安装两个服务：

runner-v0.1.1-be-aaaaaaaaaaaaaaaaaaaaaaaa
runner-v0.1.1-be-bbbbbbbbbbbbbbbbbbbbbbbb

理论上，可以在一台主机上安装同一个企业下不同版本的Runner服务，但实际上不应该这么做。所以请不要在一台主机上重复执行安装命令，并传入不同的Runner版本号。

事实上，当你在机器上安装了某个版本的Runner服务之后，Runner会自动检测服务端是否存在新版本的Runner，并自动更新，确保同一个企业下只存在一个Runner的服务。所以无需再一台主机上重复执行Runner安装命令。

2. 配置 Runner

Runner安装成功之后，可以在主机上查看Runner的配置。通常不需要修改默认的配置文件。在不同的操作系统上，需要用不同的方式找到配置文件，并使其生效。

2.1 可配置项

Runner支持对以下配置项进行设置：

  • scanInterval，Runner和流水线服务端发起心跳的时间间隔，单位为秒，通常不需要修改。

  • concurrency，允许的最大的并发的任务数。

  • autoUpgrade，是否开启自动更新，如果开启，则Runner会尝试进行自动更新，详细规则见自动更新。

  • upgradeInteval，检查Runner版本更新的时间间隔，单位为秒。

2.2 修改配置文件

假设机器上存在以下两个服务：

runner-v0.1.1-be-aaaaaaaaaaaaaaaaaaaaaaaa
runner-v0.1.1-be-bbbbbbbbbbbbbbbbbbbbbbbb

Linux

使用对应 OS 的服务查看命令查看服务：

#Systemd
$ systemctl | grep "runner-v" | awk '{print $1}'
runner-v0.1.1-be-aaaaaaaaaaaaaaaaaaaaaaaa.service
runner-v0.1.1-be-bbbbbbbbbbbbbbbbbbbbbbbb.service

#Upstart
$ initctl list | grep 'runner-v' | awk '{print $1}'
runner-v0.1.1-be-aaaaaaaaaaaaaaaaaaaaaaaa
runner-v0.1.1-be-bbbbbbbbbbbbbbbbbbbbbbbb

#System V
$ service --status-all 2>&1 | grep 'runner-v' | awk '{print $4}'
runner-v0.1.1-be-aaaaaaaaaaaaaaaaaaaaaaaa
runner-v0.1.1-be-bbbbbbbbbbbbbbbbbbbbbbbb

选择需要查看的服务，并解析出服务名称和企业命名空间：

$ SERVICE_NAME=runner-v0.1.1-be-aaaaaaaaaaaaaaaaaaaaaaaa.service
# 如果是System V或者Upstart SERVICE_NAME=runner-v0.1.1-be-aaaaaaaaaaaaaaaaaaaaaaaa
$ NAMESPACE=`echo $SERVICE_NAME | awk -F '-' '{print $3"-"$4}' | awk -F "." '{print $1}'`
$ echo $NAMESPACE
be-aaaaaaaaaaaaaaaaaaaaaaaa

查看服务的配置文件：

$ vi /root/yunxiao/${NAMESPACE}/runner/config/config.yml

Windows

# 查看服务
PS C:\> Get-Service  | Select-Object -Property Name | findstr runner
runner-be-aaaaaaaaaaaaaaaaaaaaaaaa 
runner-be-bbbbbbbbbbbbbbbbbbbbbbbb

# 设置SERVICE_NAME和NAMESPACE
PS C:\> $Env:SERVICE_NAME = "runner-be-bbbbbbbbbbbbbbbbbbbbbbbb"
PS C:\> $Env:NAMESPACE = "be-aaaaaaaaaaaaaaaaaaaaaaaa"

# 查看服务的配置文件
PS C:\> cat C:\yunxiao\data\$Env:NAMESPACE\runner\config\config.yml

macOS

# 查看服务
$ launchctl list | grep runner-v | awk '{print $3}'
runner-v0.1.1-be-aaaaaaaaaaaaaaaaaaaaaaaa
runner-v0.1.1-be-bbbbbbbbbbbbbbbbbbbbbbbb

# 设置SERVICE_NAME和NAMESPACE
$ SERVICE_NAME=runner-v0.1.1-be-aaaaaaaaaaaaaaaaaaaaaaaa
$ NAMESPACE=`echo $SERVICE_NAME | awk -F '-' '{print $3"-"$4}'`
$ echo $NAMESPACE
be-bbbbbbbbbbbbbbbbbbbbbbbb

# 查看服务的配置文件
cat ~/.yunxiao-runner/$NAMESPACE/config/config.yml

修改完配置文件，需要重启Runner，使其生效。

3. 运维 Runner

3.1 启停、禁用/启用 Runner

Linux

参照上述 Linux 上查看服务的方式设置好SERVICE_NAME。

  • Systemd

#启动
$ systemctl start $SERVICE_NAME
#停止
$ systemctl stop $SERVICE_NAME
#重启
$ systemctl restart $SERVICE_NAME
#禁用
$ systemctl enable $SERVICE_NAME
#启用
$ systemctl disable $SERVICE_NAME

  • Upstart

#启动
$ start $SERVICE_NAME
#停止
$ stop $SERVICE_NAME
#重启
$ restart $SERVICE_NAME
#禁用
#不适用
#启用
#不适用

  • System V

#启动
$ service $SERVICE_NAME start
#停止
$ service $SERVICE_NAME stop
#重启
$ service $SERVICE_NAME stop && service $SERVICE_NAME start
#禁用
$ update-rc.d $SERVICE_NAME defaults
#启用
$ update-rc.d $SERVICE_NAME remove

Windows

请在Windows操作系统 服务 中进行操作：

image

macOS

参照上述macOS上查看服务的方式设置好SERVICE_NAME。

#启动
$ launchctl start $SERVICE_NAME
#停止
# 不适用，如不在需要服务请直接卸载
#重启
$ launchctl stop $SERVICE_NAME #stop后服务会立即重启
#禁用
# 不适用
#启用
# 不适用

3.2 查看 Runner 日志

Linux

参照上述Linux上查看服务的方式设置好NAMESPACE。

$ tail -f /root/yunxiao/$NAMESPACE/runner/__flow_logs/runner.log

Windows

PS C:\> Get-Service  | Select-Object -Property Name | findstr runner
runner-be-aaaaaaaaaaaaaaaaaaaaaaaa
PS C:\> $Env:NAMESPACE_SHORT="aaaa" #服务名称去掉前面的be-之后的前四位
PS C:\> Get-Content -Tail 10  C:\yunxiao\d\$Env:NAMESPACE_SHORT\runner\__flow_logs\runner.log -Wait

macOS

参照上述macOS上查看服务的方式设置好NAMESPACE。

$ tail -f ~/.yunxiao-runner/$NAMESPACE/__flow_logs/runner.log

3.3 清理主机上的临时文件

Runner运行过程中会产生一些临时文件：

  • 查看日志中的runner.log

  • 构建日志的临时存储

  • 本地缓存的临时存储

  • 如果是容器化构建，则会拉取相应的镜像

  • 如果使用了镜像构建任务，则会产生一些临时的层

针对部分临时文件，Runner有以下自动清理规则：

  • runner.log文件单个最大为500Mb，超过500Mb的最多备份14个归档日志文件，所有日志文件最多保留7天。超过的话，会自动删除最早的日志。

  • 构建日志的临时存储为3天，3天后会自动删除。

其他的需要手动执行下列命令进行清理。该命令的作用：

  • 清理15天没有更新过的构建缓存

  • 针对容器化构建方式，清理已停止容器

  • 清理悬空无 tag 镜像

  • 清理自定义环境构建产生的中间镜像

docker run -v /var/run/docker.sock:/var/run/docker.sock -v /root/yunxiao:/root/yunxiao registry.cn-beijing.aliyuncs.com/build-steps/cache-cleaner:0.0.3-20230914183240

3.4 自动更新

Runner 的版本的格式为v<major>.<minor>.<patch>的格式。Runner 默认会每隔一段询问流水线服务端是否有可用的版本更新，当服务端的最新版本相比本地版本的minor版本号有变化，则会进行自动更新。

3.5 手动更新

暂不支持，如有需要升级Runner patch版本，需要卸载Runner之后，再重新安装最新版。

4. 删除/卸载Runner

Linux

参照上述Linux上查看服务的方式设置好SERVICE_NAME和NAMESPACE。

  • Systemd

$ systemctl stop $SERVICE_NAME
$ systemctl disable $SERVICE_NAME
$ rm /etc/systemd/system/$SERVICE_NAME
$ rm -rf /root/yunxiao/$NAMESPACE
#如果要删除该主机上的所有租户的Runner服务，除了对每个服务执行上述命令之外，在执行以下命令
$ rm -rf /root/yunxiao

  • Upstart

$ initctl stop $SERVICE_NAME
$ mv /etc/init/$SERVICE_NAME.conf /etc/init/$SERVICE_NAME.conf.disabled
$ rm -rf /root/yunxiao/$NAMESPACE
#如果要删除该主机上的所有租户的Runner服务，除了对每个服务执行上述命令之外，在执行以下命令
$ rm -rf /root/yunxiao

  • System V

$ service $SERVICE_NAME stop
$ for i in /etc/rc*.d/S*$SERVICE_NAME; do rm -f $i; done
$ rm -rf /etc/init.d/$SERVICE_NAME
$ rm -rf /root/yunxiao/$NAMESPACE
#如果要删除该主机上的所有租户的Runner服务，除了对每个服务执行上述命令之外，在执行以下命令
$ rm -rf /root/yunxiao

Windows

参照上述Windows上查看服务的方式设置好SERVICE_NAME和NAMESPACE，参照Windows上查看日志，配置好NAMESPACE_SHORT。

  • 先在服务管理中停止Runner服务。

image.png

  • 然后按照如下命令删除相应的目录。

PS C:\> C:\yunxiao\d\ohce\runner
PS C:\> Remove-Item -Path "C:\yunxiao\d\$Env:NAMESPACE_SHORT\runner" -Recurse -Force
#如果要删除该主机上的所有租户的Runner服务，除了对每个服务执行上述命令之外，在执行以下命令
PS C:\> Remove-Item -Path "C:\yunxiao" -Recurse -Force

macOS

参照上述macOS上查看服务的方式设置好SERVICE_NAME和NAMESPACE。

$ sudo launchctl bootout gui/`id -u`/$SERVICE_NAME
$ rm -f ~/Library/LaunchAgents/$SERVICE_NAME.plist
$ rm -rf ~/.yunxiao-runner/$NAMESPACE
#如果要删除该主机上的所有租户的Runner服务，除了对每个服务执行上述命令之外，在执行以下命令
$ rm -rf ~/.yunxiao-runner

5. 其他限制和已知问题

两台主机的config.yml内容相同

请不要将一台主机上的 config.yml 文件 copy 到另一台主机，并启动 Runner 服务。这会导致两个 Runner 服务都尝试去拉取任务，但目标主机并不存在于构建集群或者主机组中，从而可能会出现预期之外的构建行为。

上一篇：更多原理说明下一篇：流水线缓存
文档推荐