• Docker 引擎版本兼容性
• 安装 Docker 镜像并启动容器
  • 使用本地系统卷
  • 使用 Docker 卷
• 更新 Runner 配置
• 升级 Runner 版本
• 读取极狐GitLab Runner 日志
• 安装受信任的 SSL 服务器证书
• Docker 镜像
  • 创建极狐GitLab Runner Docker 镜像
• 在容器中使用 SELinux

在容器中运行极狐GitLab Runner

您可以在 Docker 容器中运行极狐GitLab Runner 以执行 CI/CD 作业。极狐GitLab Runner Docker 镜像包含了所需的依赖：

• 运行极狐GitLab Runner
• 在容器中执行 CI/CD 作业

极狐GitLab Runner Docker 镜像以 Ubuntu or Alpine Linux 为基础镜像。它们包装了标准的 gitlab-runner 命令，就像直接在主机上安极狐 GitLab Runner 一样。

在 Docker 容器中运行 gitlab-runner 命令。这种设置将 Docker 守护进程的完全控制权委托给每个极狐GitLab Runner容器。

结果就是，如果在还运行其他负载的 Docker 守护进程中运行极狐GitLab Runner，隔离保证会失效。

在此设置中，您运行的每个极狐GitLab Runner 命令都等同于运行 docker run：

• runner 命令： gitlab-runner <runner command and options...>
• docker 命令： docker run <chosen docker options...> gitlab/gitlab-runner <runner command and options...>

比如，要获取最高级别的极狐GitLab Runner 的帮助信息，将 gitlab-runner 部分替换为 docker run [docker options] gitlab/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:
   16.5.0 (853330f9)

(...)

Docker 引擎版本兼容性

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

安装 Docker 镜像并启动容器

先决条件：

• 您已安装了 Docker。
• 您已经阅读了 FAQ，了解您在使用极狐GitLab Runner 时最可能遇到的问题。

1. 通过执行 docker pull gitlab/gitlab-runner:<version-tag> 命令下载 gitlab-runner Docker 镜像。

   要列出所有可用的版本标签。可查看极狐GitLab Runner 标签。

2. 通过使用 docker run -d []options] <image-uri> <runner-command> 命令运行 gitlab-runner Docker 镜像。

3. 当您在 Docker 容器中运行 gitlab-runner 时，请确保当您重启容器时配置不会丢失。挂载持久卷来存储配置。以下方法均可作为持久卷：

   • 本地系统卷
   • Docker 卷
4. 可选。如果您在使用 session_server，通过在 docker run 命令中添加 -p 8093:8093 来暴露端口 8093。
5. 可选。如果您想通过 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
6. 注册一个新的 Runner。极狐GitLab Runner 必须被注册以能够接受作业。

其他可用的配置选项包括：

• 使用 --env TZ=<TIMEZONE> 标志来设置容器的时区。查看可用的时区列表
• 符合FIPS标准的GitLab Runner 镜像，基础镜像为 redhat/ubi9-micro，标签为 gitlab/gitlab-runner:ubi-fips。
• 安装受信任的 SSL 服务端证书.

使用本地系统卷

为配置卷使用本地系统并将其他所有资源挂载进 gitlab-runner 容器。

1. 可选。在 MacOS 中，默认情况下 /srv 目录不存在。创建 /private/srv 或其他私有目录。

2. 执行以下命令，并按需修改：

   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 卷

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

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 配置

当您在 config.toml 文件中修改了 Runner 配置信息，通过执行命令 docker stop 和 docker run 来重启容器以让配置生效。

升级 Runner 版本

先决条件：

• 您必须使用和初始安装相同的方法来挂载您的数据，（-v /srv/gitlab-runner/config:/etc/gitlab-runner 或 -v gitlab-runner-config:/etc/gitlab-runner）。

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

   docker pull gitlab/gitlab-runner:latest
   

2. 停止并移除现存的容器：

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

3. 像最开始那样启动容器：

   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 日志

日志的位置取决于您如何启动 Runner。当您的启动方式为：

• 前台任务（Foreground task），本地二进制安装或在容器中运行，日志都会打印到标准输出 stdout。
• 系统服务（System service），比如 systemd，可以在系统日志机制中查看日志，比如 Syslog。
• 基于 Docker 的服务（Docker-based services），使用 docker logs 命令，因为 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

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

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

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

先决条件：

• 您的 ca.crt 文件应该包含所有您想让极狐GitLab Runner 信任的服务器的根证书。

1. 可选。gitlab/gitlab-runner 镜像会在 /etc/gitlab-runner/certs/ca.crt 路径下寻找受信任的 SSL 证书。要改变此行为，在证书配置选项中使用 -e "CA_CERTIFICATES_PATH=/DIR/CERT"。
2. 将 ca.crt 文件拷贝至数据卷（或容器）中的证书目录下。
3. 可选。如果您的容器已经在运行了，通过重启来导入 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 镜像

在极狐GitLab 仓库中的更新可用之前，您就可以升级您的镜像操作系统了。

先决条件：

• 您没在使用 IBM Z 镜像，因为它不包含 docker-machine 依赖。因为 Linux s390x 或 Linux ppc64le 平台没有进行维护。

为最新的 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-v16.1.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-v16.1.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