为弹性伸缩 Docker Machine 安装和注册极狐GitLab Runner

弹性伸缩功能引入于极狐GitLab Runner 1.1.0。

Docker Machine 执行器在极狐GitLab 17.5 中已弃用。如果您还在使用 AWS EC2、Microsoft Azure Compute 或 Google Compute Engine (GCE) 上的 Docker Machine 执行器，请迁移到 GitLab Runner Autoscaler。

如果您想了解弹性伸缩，请参见弹性伸缩文档。

Docker machine 的分叉版本

Docker 已经弃用了 Docker Machine。但是，极狐GitLab 维护了一个 Docker Machine 的分叉供极狐GitLab Runner 用户使用 Docker Machine 执行器。这个分叉基于 docker-machine 的最新 main 分支，加上一些修复关键问题和错误的补丁，这些问题和错误会影响运行成本：

Docker Machine 分叉的目的是只修复关键问题和错误，这些问题和错误会影响运行成本。不会添加新功能。

准备环境

如果您想使用弹性伸缩功能，Docker 和极狐GitLab Runner 必须安装在同一台机器上：

登录新的基于 Linux 的机器，这个机器作为堡垒服务器，Docker 在其上生成新机器。
安装极狐GitLab Runner。
从 Docker Machine 派生安装 Docker Machine。
可选但推荐。准备代理容器镜像库和缓存服务器，和弹性伸缩 Runner 一起使用。

配置极狐GitLab Runner

熟悉与 gitlab-runner 一起使用 docker-machine 的核心概念：
- 阅读极狐GitLab Runner 弹性伸缩。
- 阅读极狐GitLab Runner Machine 选项。
第一次使用 Docker Machine 时，最好使用您的 Docker Machine 驱动手动执行 docker-machine create ... 命令。和您打算在极狐GitLab Runner MachineOptions 部分配置的选项一起运行这个命令。这会合理设置 Docker Machine 环境，也会对特定选项进行很好的验证。在这之后，您可以使用 docker-machine rm [machine_name] 销毁机器并启动 Runner。

多个第一次使用时就完成的 docker-machine create 的并发请求是不好的。当使用 docker+machine 执行器，Runner 或许会启动很少的并发 docker-machine create 命令。如果之前从未在这个环境中使用过 Docker Machine，每个启动的进程都会试图准备 SSH 密钥和 SSL 证书（极狐GitLab Runner 和弹性伸缩所生成的机器上的 Docker Engine 之间的 Docker API 鉴权），并且这些并发进程互相干扰。在非工作环境中这些可以结束。这也是您第一次使用 Docker Machine 设置极狐GitLab Runner 时手动创建测试机很重要的原因。
注册 Runner 并选择 docker+machine 执行器。
编辑 config.toml 并配置 Runner 使用 Docker Machine。详情请参见极狐GitLab Runner 弹性伸缩。
现在您可以试着在您的项目中启动新流水线。几秒钟后，如果您运行 docker-machine ls，您应该能看见正在创建的新机器。

升级极狐GitLab Runner

检查您的操作系统是否配置了自动重启极狐GitLab Runner（例如，检查服务文件）：
- 如果配置了自动重启，确保服务管理器配置成使用 SIGQUIT 并使用服务工具停止进程：
```
# For systemd
sudo systemctl stop gitlab-runner

# For upstart
sudo service gitlab-runner stop
```
- 如果没配置自动重启，您可能需要手动停止进程：
```
sudo killall -SIGQUIT gitlab-runner
```
发送 SIGQUIT 信号会优雅关闭进程。进程不再接受新作业，当前作业完成后，会马上退出。
一直等待，直到极狐GitLab Runner 退出。您可以使用 gitlab-runner status 查看它的状态，或使用以下命令等待为时 30 分钟的优雅关闭：
```
for i in `seq 1 180`; do # 1800 seconds = 30 minutes
    gitlab-runner status || break
    sleep 10
done
```
您现在可以不打断任何作业安全安装新版本的极狐GitLab Runner 了。

使用 Docker Machine 的分叉版本

安装

下载合适的 docker-machine 二进制。复制二进制到可以访问 PATH 的位置，使其可执行。例如，下载并安装 v0.16.2-gitlab.21：

 curl -O "https://gitlab-docker-machine-downloads.s3.amazonaws.com/v0.16.2-gitlab.21/docker-machine-Linux-x86_64"
 cp docker-machine-Linux-x86_64 /usr/local/bin/docker-machine
 chmod +x /usr/local/bin/docker-machine

在谷歌计算引擎上使用 GPU

引入于极狐GitLab Docker Machine 0.16.2-gitlab.10 和极狐GitLab Runner 13.9。

每个执行器都支持 GPU。没必要只为了 GPU 支持而使用 Docker Machine。Docker Machine 执行器很容易就可以向上或向下伸缩 GPU，但是使用 Kubernetes 执行器同样可以完成。

您可以使用 Docker Machine 派生创建使用图形处理单元（GPU）的谷歌计算引擎实例。

Docker Machine GPU 选项

如果您想使用 GPU 创建实例，请使用以下 Docker Machine 选项：

选项	示例	描述
`--google-accelerator`	`type=nvidia-tesla-p4,count=1`	指定附属于实例（`type=TYPE,count=N` 格式）的 GPU 加速器的类型和数量。
`--google-maintenance-policy`	`TERMINATE`	一直使用 `TERMINATE`，因为谷歌云不允许 GPU 实例热迁移。
`--google-machine-image`	`https://www.googleapis.com/compute/v1/projects/deeplearning-platform-release/global/images/family/tf2-ent-2-3-cu110`	GPU 启用的操作系统的 URL。详情请参见可用镜像列表。
`--google-metadata`	`install-nvidia-driver=True`	这个标记让镜像安装 NVIDIA GPU 驱动。

这些参数映射到 gcloud compute 的命令行参数。详情请参见谷歌关于使用关联 GPU 创建虚拟机的文档。

验证 Docker Machine 选项

如果您想准备您的系统并测试可以使用谷歌计算引擎创建 GPU：

为Docker Machine 设置谷歌计算引擎驱动证书。如果您的虚拟机没有默认服务账号，您可能需要向 Runner 导出环境变量。如何完成取决于如何发布 Runner。例如：
- 通过 systemd 或 upstart：参见设置自定义环境变量的文档。
- 通过使用 Helm Chart 的 Kubernetes：更新 values.yaml 条目。
- 通过 Docker：使用 -e 选项（例如，docker run -e GOOGLE_APPLICATION_CREDENTIALS=/path/to/credentials.json gitlab/gitlab-runner）。

验证 docker-machine 可以使用预期选项创建虚拟机。例如，使用单个 NVIDIA Telsa P4 加速器创建 n1-standard-1 机器，用一个名称替代 test-gpu 并运行：

docker-machine create --driver google --google-project your-google-project \
  --google-disk-size 50 \
  --google-machine-type n1-standard-1 \
  --google-accelerator type=nvidia-tesla-p4,count=1 \
  --google-maintenance-policy TERMINATE \
  --google-machine-image https://www.googleapis.com/compute/v1/projects/deeplearning-platform-release/global/images/family/tf2-ent-2-3-cu110 \
  --google-metadata "install-nvidia-driver=True" test-gpu

为了验证 GPU 有效，您需要通过 SSH 进入机器并运行 nvidia-smi：

$ docker-machine ssh test-gpu sudo nvidia-smi
+-----------------------------------------------------------------------------+
| NVIDIA-SMI 450.51.06    Driver Version: 450.51.06    CUDA Version: 11.0     |
|-------------------------------+----------------------+----------------------+
| GPU  Name        Persistence-M| Bus-Id        Disp.A | Volatile Uncorr. ECC |
| Fan  Temp  Perf  Pwr:Usage/Cap|         Memory-Usage | GPU-Util  Compute M. |
|                               |                      |               MIG M. |
|===============================+======================+======================|
|   0  Tesla P4            Off  | 00000000:00:04.0 Off |                    0 |
| N/A   43C    P0    22W /  75W |      0MiB /  7611MiB |      3%      Default |
|                               |                      |                  N/A |
+-------------------------------+----------------------+----------------------+

+-----------------------------------------------------------------------------+
| Processes:                                                                  |
|  GPU   GI   CI        PID   Type   Process name                  GPU Memory |
|        ID   ID                                                   Usage      |
|=============================================================================|
|  No running processes found                                                 |
+-----------------------------------------------------------------------------+

移除测试实例以省钱：
```
 docker-machine rm test-gpu
```

配置极狐GitLab Runner

一旦您验证了这些选项，配置 Docker 执行器以在 runners.docker 配置中使用所有可用 GPU。然后向您的极狐GitLab Runner runners.machine 配置中的 MachineOptions 设置中添加 Docker Machine 选项。例如：

[runners.docker]
  gpus = "all"
[runners.machine]
  MachineOptions = [
    "google-project=your-google-project",
    "google-disk-size=50",
    "google-disk-type=pd-ssd",
    "google-machine-type=n1-standard-1",
    "google-accelerator=count=1,type=nvidia-tesla-p4",
    "google-maintenance-policy=TERMINATE",
    "google-machine-image=https://www.googleapis.com/compute/v1/projects/deeplearning-platform-release/global/images/family/tf2-ent-2-3-cu110",
    "google-metadata=install-nvidia-driver=True"
  ]

故障排查

当使用 Docker Machine 执行器的时候，您可能会遇到以下问题。

错误：创建机器时发生错误

当安装 Docker Machine 时，您可能会遇到一个错误：ERROR: Error creating machine: Error running provisioning: error installing docker。

Docker Machine 试图使用如下脚本在新创建的虚拟机上安装 Docker：

if ! type docker; then curl -sSL "https://get.docker.com" | sh -; fi

如果 docker 命令执行成功，Docker Machine 会假设 Docker 已经安装并继续。

如果 docker 命令没有执行成功，Docker Machine 会尝试下载并运行 https://get.docker.com 脚本。如果安装失败，可能是因为操作系统不再受 Docker 支持。

为了解决这个问题，您可以在安装极狐GitLab Runner 的环境中通过设置 MACHINE_DEBUG=true 来开启 Docker Machine 调试模式。

错误：无法连接到 Docker 守护进程

作业可能会在准备阶段失败，并报如下错误：

Preparing environment
ERROR: Job failed (system failure): prepare environment: Cannot connect to the Docker daemon at tcp://10.200.142.223:2376. Is the docker daemon running? (docker.go:650:120s). Check https://docs.gitlab.com/runner/shells/index.html#shell-profile-loading for more information

当 Docker 守护进程在由 Docker Machine 执行器创建的虚拟机中未能在预期时间内启动时，就会发生这个错误。为了修复此问题，在runner docker 部分中增加 wait_for_services_timeout 的值。