极狐 GitLab Logo

在 Docker 容器中运行极狐GitLab Runner

  • Tier: 基础版，专业版，旗舰版
  • Offering: JihuLab.com，私有化部署

你可以在 Docker 容器中运行极狐GitLab Runner 来执行 CI/CD 任务。极狐GitLab Runner 的 Docker 镜像包含所有需要的依赖项：

  • 运行极狐GitLab Runner。
  • 在容器中执行 CI/CD 任务。

极狐GitLab Runner 的 Docker 镜像使用 Ubuntu 或 Alpine Linux 作为基础。它们封装了标准的 gitlab-runner 命令，类似于直接在主机上安装极狐GitLab Runner。

gitlab-runner 命令在 Docker 容器中运行。此设置将对 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，如下所示：

shell
1docker run --rm -t -i gitlab/gitlab-runner --help
2
3NAME:
4   gitlab-runner - a GitLab Runner
5
6USAGE:
7   gitlab-runner [global options] command [command options] [arguments...]
8
9VERSION:
10   17.9.1 (bbf75488)
11
12(...)

Docker 引擎版本兼容性#

Docker 引擎和极狐GitLab Runner 容器镜像的版本不必匹配。极狐GitLab Runner 镜像具有向后和向前兼容性。为了确保拥有最新的功能和安全更新，你应始终使用最新稳定的 Docker 引擎版本。

安装 Docker 镜像并启动容器#

前提条件：

  • 你已安装 Docker。
  • 你已阅读常见问题解答，了解极狐GitLab Runner 中的常见问题。

  1. 使用 docker pull gitlab/gitlab-runner:<version-tag> 命令下载 gitlab-runner Docker 镜像。

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

  3. 在 Docker 容器中运行 gitlab-runner 时，确保在重新启动容器时配置不会丢失。挂载一个永久卷来存储配置。可以以以下两种方式挂载卷：

  4. 可选。如果使用 session_server，通过在 docker run 命令中添加 -p 8093:8093 来公开端口 8093。

  5. 可选。要使用 Docker 机器执行器进行自动扩展，请通过在 docker run 命令中添加卷挂载来挂载 Docker 机器存储路径 (/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 容器必须注册以获取任务。

一些可用的配置选项包括：

从本地系统卷#

要将本地系统用于挂载到 gitlab-runner 容器的配置卷和其他资源：

  1. 可选。在 MacOS 系统中，/srv 默认不存在。创建 /private/srv 或其他私有目录进行设置。

  2. 运行此命令，根据需要进行修改：

    shell
    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 卷：

    shell
    docker volume create gitlab-runner-config

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

    shell
    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 配置后，通过使用 docker stop 和 docker run 重新启动容器来应用更改。

升级 runner 版本#

前提条件：

  • 你必须使用与最初挂载数据卷相同的方法 （-v /srv/gitlab-runner/config:/etc/gitlab-runner 或 -v gitlab-runner-config:/etc/gitlab-runner）。

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

    shell
    docker pull gitlab/gitlab-runner:latest

  2. 停止并删除现有容器：

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

  3. 按原样启动容器：

    shell
    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

查看 runner 日志#

日志文件的位置取决于你如何启动 runner。当你将其作为：

  • 前台任务，无论是作为本地安装的二进制文件还是在 Docker 容器中，日志都会打印到 stdout。
  • 系统服务，如使用 systemd，日志可以在系统日志机制（如 Syslog）中查看。
  • 基于 Docker 的服务，使用 docker logs 命令，因为 gitlab-runner ... 命令是容器的主进程。

例如，如果你用此命令启动容器，则其名称设置为 gitlab-runner：

shell
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 为你的容器名称：

shell
docker logs gitlab-runner

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

如果你的极狐GitLab CI/CD 服务器使用自签名 SSL 证书，请确保你的 runner 容器信任极狐GitLab CI 服务器证书。这可以防止通信失败。

前提条件：

  • 你的 ca.crt 文件应包含所有你希望极狐GitLab Runner 信任的服务器的根证书。
  1. 可选。gitlab/gitlab-runner 镜像在 /etc/gitlab-runner/certs/ca.crt 中查找受信任的 SSL 证书。要更改此行为，请使用 -e "CA_CERTIFICATES_PATH=/DIR/CERT" 配置选项。
  2. 将你的 ca.crt 文件复制到数据卷（或容器）上的 certs 目录中。
  3. 可选。如果你的容器已经在运行，请重新启动它以在启动时导入 ca.crt 文件。

Docker 镜像#

在极狐GitLab Runner 17.10.0 中，基于 Alpine 的 Docker 镜像使用 Alpine 3.19。以下是可用的多平台 Docker 镜像：

  • gitlab/gitlab-runner:latest 基于 Ubuntu，约 800 MB。
  • gitlab/gitlab-runner:alpine 基于 Alpine，约 460 MB。

创建一个 runner Docker 镜像#

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

前提条件：

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

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

  1. 创建 alpine-upgrade/Dockerfile。

    dockerfile
    1ARG GITLAB_RUNNER_IMAGE_TYPE
2ARG GITLAB_RUNNER_IMAGE_TAG
3FROM gitlab/${GITLAB_RUNNER_IMAGE_TYPE}:${GITLAB_RUNNER_IMAGE_TAG}
4
5RUN apk update
6RUN apk upgrade

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

    shell
    1GITLAB_RUNNER_IMAGE_TYPE=gitlab-runner \
2GITLAB_RUNNER_IMAGE_TAG=alpine-v17.9.1 \
3docker build -t $GITLAB_RUNNER_IMAGE_TYPE:$GITLAB_RUNNER_IMAGE_TAG \
4  --build-arg GITLAB_RUNNER_IMAGE_TYPE=$GITLAB_RUNNER_IMAGE_TYPE \
5  --build-arg GITLAB_RUNNER_IMAGE_TAG=$GITLAB_RUNNER_IMAGE_TAG \
6  -f alpine-upgrade/Dockerfile alpine-upgrade

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

    shell
    1GITLAB_RUNNER_IMAGE_TYPE=gitlab-runner-helper \
2GITLAB_RUNNER_IMAGE_TAG=x86_64-v17.9.1 \
3docker build -t $GITLAB_RUNNER_IMAGE_TYPE:$GITLAB_RUNNER_IMAGE_TAG \
4  --build-arg GITLAB_RUNNER_IMAGE_TYPE=$GITLAB_RUNNER_IMAGE_TYPE \
5  --build-arg GITLAB_RUNNER_IMAGE_TAG=$GITLAB_RUNNER_IMAGE_TAG \
6  -f alpine-upgrade/Dockerfile alpine-upgrade

在你的容器中使用 SELinux#

一些发行版，如 CentOS、Red Hat 和 Fedora 默认使用 SELinux（Security-Enhanced Linux）来增强底层系统的安全性。

使用此配置时请谨慎。

前提条件：

  • 要使用 Docker 执行器 在容器中运行构建，runners 需要访问 /var/run/docker.sock。
  • 如果你在强制模式下使用 SELinux，请安装 selinux-dockersock 以防止在 runner 访问 /var/run/docker.sock 时出现 Permission denied 错误。

  1. 在主机上创建一个持久目录：mkdir -p /srv/gitlab-runner/config。

  2. 在卷上使用 :Z 运行 Docker：

    shell
    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