• Docker 引擎版本兼容性
• 一般极狐GitLab Runner Docker 镜像使用
• 安装 Docker 镜像并启动容器
  • 选项一：使用本地系统卷挂载，启动 Runner 容器
  • 选项二：使用 Docker 卷启动 Runner 容器
  • 注册 Runner
• 升级配置
• 升级版本
• 读取极狐GitLab Runner 日志
• 安装受信任的 SSL 服务器证书
• Docker 镜像
  • 创建极狐GitLab Runner Docker 镜像
• SELinux
• 极狐GitLab Runner 容器镜像支持生命周期
  • 容器镜像和发布结束日期

在容器中运行极狐GitLab Runner

下面将向您介绍如何在 Docker 容器中运行极狐GitLab Runner。

Docker 引擎版本兼容性

一般来说，Docker Engine 的版本和极狐GitLab Runner 容器镜像的版本不需要匹配。 极狐GitLab Runner 镜像应该向后和向前兼容。 然而，为确保您拥有最新的功能和安全更新，您应该使用最新的稳定 Docker 引擎版本。

一般极狐GitLab Runner Docker 镜像使用

极狐GitLab Runner Docker 镜像（基于 Ubuntu 或 Alpine Linux）被设计为标准 gitlab-runner 命令周围的包装器，就像极狐GitLab Runner 直接安装在主机上一样。

一般规则是每个极狐GitLab Runner 命令通常会被执行为：

gitlab-runner <runner command and options...>

可以使用以下命令执行：

docker run <chosen docker options...> gitlab/gitlab-runner <runner command and options...>

例如，可以执行以下命令获取最高级别的极狐GitLab Runner 的帮助信息：

docker run --rm -t -i gitlab/gitlab-runner --help

NAME:
   gitlab-runner - a GitLab Runner

USAGE:
   gitlab-runner [global options] command [command options] [arguments...]

VERSION:
    15.1.0 (76984217)

(...)

简而言之，命令的 gitlab-runner 部分由 docker run [docker options] gitlab/gitlab-runner 替代，剩余部分保持与注册文档中描述的内容相一致。 唯一区别是 gitlab-runner 命令是在 Docker 容器中执行的。

安装 Docker 镜像并启动容器

开始之前，请确保已经安装 Docker。

如果想在 Docker 容器内运行 gitlab-runner，您需要确保重启容器时配置没有丢失。为此，以下描述两个选项：

请阅读 FAQ，它介绍了您在使用极狐GitLab Runner 时最可能遇到的问题。

• 如果使用 session_server，您也需要通过向 docker run 命令中添加 -p 8093:8093 暴露端口 8093。
• 如果您想通过 Docker Machine 执行器使用弹性伸缩功能，您还需要挂载 Docker Machine /root/.docker/machine 存储路径：
  • 通过为系统卷挂载添加 -v /srv/gitlab-runner/docker-machine-config:/root/.docker/machine。
  • 通过为 Docker 命名的卷添加 -v docker-machine-config:/root/.docker/machine。

选项一：使用本地系统卷挂载，启动 Runner 容器

以下示例使用挂载到 gitlab-runner 容器的配置卷的本地系统。这个卷用于配置资源和其他资源。

docker run -d --name gitlab-runner --restart always \
  -v /srv/gitlab-runner/config:/etc/gitlab-runner \
  -v /var/run/docker.sock:/var/run/docker.sock \
  gitlab/gitlab-runner:latest

选项二：使用 Docker 卷启动 Runner 容器

在这个例子中，您可以使用配置容器挂载您的自定义数据卷。

1. 创建 Docker 卷：

   docker volume create gitlab-runner-config
   

2. 使用刚创建的卷启动极狐GitLab Runner 容器：

   docker run -d --name gitlab-runner --restart always \
       -v /var/run/docker.sock:/var/run/docker.sock \
       -v gitlab-runner-config:/etc/gitlab-runner \
       gitlab/gitlab-runner:latest
   

注册 Runner

最后一步是注册新的 Runner。极狐GitLab Runner 容器在注册之前不会处理任何作业。

升级配置

如果您更改了 config.toml 中的配置，您可能需要重启 Runner 使更改生效。 请确保重启整个容器，而不是使用 gitlab-runner restart 命令：

docker restart gitlab-runner

升级版本

拉取最新版本（或者特定标签）：

docker pull gitlab/gitlab-runner:latest

停止并移除现存的容器：

docker stop gitlab-runner && docker rm gitlab-runner

像最开始那样启动容器：

docker run -d --name gitlab-runner --restart always \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v /srv/gitlab-runner/config:/etc/gitlab-runner \
  gitlab/gitlab-runner:latest

读取极狐GitLab Runner 日志

当极狐GitLab Runner 作为前台任务（不论是本地安装的二进制文件或 Docker 容器内部）被启动时，日志会被打印为标准输出。当极狐GitLab Runner 作为系统服务被启动时（例如，使用 Systemd），大多数情况下的日志都是通过 Syslog 或其他系统记录机制进行记录的。

极狐GitLab Runner 作为基于服务的 Docker 被启动，因为 gitlab-runner ... 命令是容器的主要进程，可以使用 docker logs 命令读取日志。

例如，如果使用以下命令启动极狐GitLab Runner：

docker run -d --name gitlab-runner --restart always \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v /srv/gitlab-runner/config:/etc/gitlab-runner \
  gitlab/gitlab-runner:latest

您可以使用以下命令获取日志：

docker logs gitlab-runner

其中 gitlab-runner 是容器的名称，可以在第一个命令中输入 --name gitlab-runner 进行设置。

关于处理容器日志的更多信息，请参见 Docker 文档页。

安装受信任的 SSL 服务器证书

如果您的极狐GitLab CI 服务器使用自签名 SSL 证书，那么您应该确保极狐GitLab CI 服务器证书受到极狐GitLab Runner 容器的信任，使其能够通信。

gitlab/gitlab-runner 镜像被配置为在 /etc/gitlab-runner/certs/ca.crt 中寻找受信任的 SSL 证书，也可以使用 -e "CA_CERTIFICATES_PATH=/DIR/CERT" 配置选项进行更改。

将 ca.crt 文件复制到数据卷（或容器）上的 certs 目录中。 ca.crt 文件应包含您希望极狐GitLab Runner 信任的所有服务器的根证书。 极狐GitLab Runner 容器在启动时导入 ca.crt 文件，因此如果您的容器已经在运行中，您可能需要重新启动它使更改生效。

Docker 镜像

以下多平台 Docker 镜像可用：

• 基于 Ubuntu 的 gitlab/gitlab-runner:latest。
• 基于 Alpine 的空间更小的 gitlab/gitlab-runner:alpine。 （~160/350 MB Ubuntu vs ~45/130 MB Alpine 压缩文件/解压缩文件）。

关于 Ubuntu 和 Alpine 镜像的构建说明，请参见极狐GitLab Runner 源。

创建极狐GitLab Runner Docker 镜像

截至 2021 年 8 月 3 日，基于 Alpine 的极狐GitLab Runner Docker 镜像使用的是 Alpine 3.12.0。然而，在极狐GitLab 仓库中可以使用它之前，您可以升级镜像的操作系统。

为最新的 Alpine 版本构建 gitlab-runner Docker 镜像：

1. 创建 alpine-upgrade/Dockerfile。

   ARG GITLAB_RUNNER_IMAGE_TYPE
   ARG GITLAB_RUNNER_IMAGE_TAG
   FROM gitlab/${GITLAB_RUNNER_IMAGE_TYPE}:${GITLAB_RUNNER_IMAGE_TAG}
      
   RUN apk update
   RUN apk upgrade
   

2. 创建升级的 gitlab-runner 镜像。

   GITLAB_RUNNER_IMAGE_TYPE=gitlab-runner GITLAB_RUNNER_IMAGE_TAG=alpine-v13.12.0 docker build -t $GITLAB_RUNNER_IMAGE_TYPE:$GITLAB_RUNNER_IMAGE_TAG --build-arg GITLAB_RUNNER_IMAGE_TYPE=$GITLAB_RUNNER_IMAGE_TYPE --build-arg GITLAB_RUNNER_IMAGE_TAG=$GITLAB_RUNNER_IMAGE_TAG -f alpine-upgrade/Dockerfile alpine-upgrade
   

3. 创建升级的 gitlab-runner-helper 镜像。

   GITLAB_RUNNER_IMAGE_TYPE=gitlab-runner-helper GITLAB_RUNNER_IMAGE_TAG=x86_64-v13.12.0 docker build -t $GITLAB_RUNNER_IMAGE_TYPE:$GITLAB_RUNNER_IMAGE_TAG --build-arg GITLAB_RUNNER_IMAGE_TYPE=$GITLAB_RUNNER_IMAGE_TYPE --build-arg GITLAB_RUNNER_IMAGE_TAG=$GITLAB_RUNNER_IMAGE_TAG -f alpine-upgrade/Dockerfile alpine-upgrade
   

SELinux

一些发行版（CentOS、Red Hat、Fedora）默认使用 SELinux 加强底层系统的安全。

您在处理这种配置时一定要特别注意。

1. 如果您想使用 Docker 执行器运行容器中的构建，您需要访问 /var/run/docker.sock。 然而，如果 SELinux 处于强制模式，当您访问 /var/run/docker.sock 时会出现 Permission denied 错误。 安装 selinux-dockersock 可以解决这个问题。
2. 确保在主机上创建了持久目录：mkdir -p /srv/gitlab-runner/config。
3. 在卷上使用 :Z 运行 Docker。

docker run -d --name gitlab-runner --restart always \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v /srv/gitlab-runner/config:/etc/gitlab-runner:Z \
  gitlab/gitlab-runner:latest

极狐GitLab Runner 容器镜像支持生命周期

我们将遵循用于创建极狐GitLab Runner 容器镜像的基本发行版（Ubuntu、Alpine、Red Hat Universal Base Image）的支持生命周期。

基本发行版的发布结束日期不一定与极狐GitLab 的大版本发布周期一致。这意味着我们将停止发布小版本中的极狐GitLab Runner 容器镜像版本。这样我们就不会发布上游发行版不再更新的镜像。

容器镜像和发布结束日期