使用 Docker 沙盒排查 Bazel 远程执行问题

报告问题 查看源代码

在本地成功执行的 Bazel 构建可能会因限制和要求不会影响本地构建而远程执行。为远程执行调整 Bazel 规则中描述了此类失败的最常见原因。

本页面介绍如何使用 Docker 沙盒功能找出并解决远程执行方面最常见的问题,此功能会对构建施加与远程执行相同的限制。这样,您无需远程执行服务即可对构建进行问题排查。

Docker 沙盒功能模拟远程执行的限制,如下所示:

  • 构建操作在工具链容器中执行。您可以使用相同的工具链容器通过支持容器化远程执行的服务在本地和远程运行构建。

  • 没有无关的数据超出容器边界。只有在明确声明的输入和输出才会进入和离开容器,并且仅在关联的构建操作成功完成后才会发生。

  • 每个操作都在新的容器中执行。系统会为每个生成的构建操作创建一个新的唯一容器。

您可以使用以下方法之一排查这些问题:

  • 原生问题排查。使用此方法,Bazel 及其构建操作会以原生方式在本地计算机上运行。Docker 沙盒功能对构建施加了与远程执行相同的限制。不过,此方法不会检测本地工具、状态和数据泄露到 build 中,这会导致远程执行出现问题。

  • 在 Docker 容器中排查问题。通过这种方法,Bazel 及其构建操作在 Docker 容器内运行,可让您检测到从本地机器向构建泄露的工具、状态和数据,并施加与远程执行相同的限制。即使构建的某些部分失败,此方法也能深入分析您的构建。此方法是实验性功能,未获得官方支持。

前提条件

开始排查问题之前,请先执行以下操作(如果您尚未执行此操作):

  • 安装 Docker 并配置运行 Docker 所需的权限。
  • 安装 Bazel 0.14.1 或更高版本。早期版本不支持 Docker 沙盒功能。
  • 按照固定方式,将 bazel-toolchains 代码库固定到 build 的 WORKSPACE 文件中,如此处所述。
  • .bazelrc 文件添加标志即可启用此功能。在 Bazel 项目的根目录中创建该文件(如果该文件不存在)。以下标志是参考示例。请查看 bazel-toolchains 代码库中最新的 .bazelrc 文件,并复制为配置 docker-sandbox 定义的标志的值。
# Docker Sandbox Mode
build:docker-sandbox --host_javabase=<...>
build:docker-sandbox --javabase=<...>
build:docker-sandbox --crosstool_top=<...>
build:docker-sandbox --experimental_docker_image=<...>
build:docker-sandbox --spawn_strategy=docker --strategy=Javac=docker --genrule_strategy=docker
build:docker-sandbox --define=EXECUTOR=remote
build:docker-sandbox --experimental_docker_verbose
build:docker-sandbox --experimental_enable_docker_sandbox

如果您的规则需要其他工具,请执行以下操作:

  1. 使用 Dockerfile 安装工具并在本地构建映像,以创建自定义 Docker 容器。

  2. 将上述 --experimental_docker_image 标志的值替换为自定义容器映像的名称。

原生问题排查

此方法会直接在本地机器上执行 Bazel 及其所有构建操作,是确认构建远程执行是否成功的可靠方式。

不过,如果使用此方法,本地安装的工具、二进制文件和数据可能会泄露到 build 中,尤其是使用配置样式的 WORKSPACE 规则时。 此类泄露会导致远程执行出现问题;除了以原生方式排查问题之外,还要在 Docker 容器中排查问题

第 1 步:运行 build

  1. --config=docker-sandbox 标志添加到执行构建的 Bazel 命令。例如:

    bazel --bazelrc=.bazelrc build --config=docker-sandbox target
    
  2. 运行构建并等待其完成。由于 Docker 沙盒功能,构建速度会比正常速度慢四倍。

您可能会遇到以下错误:

ERROR: 'docker' is an invalid value for docker spawn strategy.

如果确实如此,请使用 --experimental_docker_verbose 标志再次运行构建。此标志启用详细的错误消息。此错误通常是由于 Docker 安装错误或没有权限在当前用户帐号下执行。如需了解详情,请参阅 Docker 文档。如果问题仍然存在,请跳至在 Docker 容器中排查问题

第 2 步:解决检测到的问题

以下是最常见的问题及其解决方法。

  • 缺少 Bazel runfiles 树引用的文件、工具、二进制文件或资源。确认已明确声明受影响目标的所有依赖项。如需了解详情,请参阅管理隐式依赖项

  • 绝对路径或 PATH 变量引用的文件、工具、二进制文件或资源缺失。确认所有所需工具均安装在工具链容器中,并使用工具链规则正确声明指向缺失资源的依赖项。如需了解详情,请参阅通过工具链规则调用构建工具

  • 二进制执行失败。其中一个构建规则正在引用与执行环境(Docker 容器)不兼容的二进制文件。如需了解详情,请参阅管理依赖于平台的二进制文件。如果您无法解决问题,请通过 bazel-discuss@google.com 寻求帮助。

  • @local-jdk 中的文件缺失或导致错误。本地机器上的 Java 二进制文件在与构建不兼容时泄漏到构建中。请在规则和目标中使用 java_toolchain,而不是 @local_jdk。如果您需要进一步的帮助,请发送电子邮件至 bazel-discuss@google.com

  • 其他错误。请发送电子邮件至 bazel-discuss@google.com 获取帮助。

在 Docker 容器中排查问题

使用此方法,Bazel 在主机 Docker 容器内运行,Bazel 的构建操作在 Docker 沙盒功能生成的各个工具链容器中执行。沙盒会为每个构建操作生成一个全新的工具链容器,每个工具链容器中只执行一项操作。

这种方法可以更精细地控制主机环境中安装的工具。通过将构建的执行与执行的构建操作分开,并尽可能减少已安装的工具,您可以验证构建是否依赖于本地执行环境。

第 1 步:构建容器

  1. 创建一个 Dockerfile,用于创建 Docker 容器并使用一组最少的构建工具安装 Bazel:

    FROM debian:stretch
    
    RUN apt-get update && apt-get install -y apt-transport-https curl software-properties-common git gcc gnupg2 g++ openjdk-8-jdk-headless python-dev zip wget vim
    
    RUN curl -fsSL https://download.docker.com/linux/debian/gpg | apt-key add -
    
    RUN add-apt-repository "deb [arch=amd64] https://download.docker.com/linux/debian $(lsb_release -cs) stable"
    
    RUN apt-get update && apt-get install -y docker-ce
    
    RUN wget https://releases.bazel.build/<latest Bazel version>/release/bazel-<latest Bazel version>-installer-linux-x86_64.sh -O ./bazel-installer.sh && chmod 755 ./bazel-installer.sh
    
    RUN ./bazel-installer.sh
    
  2. 将容器构建为 bazel_container

    docker build -t bazel_container - < Dockerfile
    

第 2 步:启动容器

使用如下所示的命令启动 Docker 容器。在该命令中,替换指向您要构建的主机上源代码的路径。

docker run -it \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v /tmp:/tmp \
  -v your source code directory:/src \
  -w /src \
  bazel_container \
  /bin/bash

此命令以 root 身份运行容器,映射 Docker 套接字,并装载 /tmp 目录。这样一来,Bazel 便可以生成其他 Docker 容器,并使用 /tmp 下的目录与这些容器共享文件。您的源代码位于容器内的 /src 下。

该命令有意从 debian:stretch 基础容器开始,此容器包含与用作工具链容器的 rbe-ubuntu16-04 容器不兼容的二进制文件。如果来自本地环境的二进制文件泄露到工具链容器中,会导致构建错误。

第 3 步:测试容器

在 Docker 容器内运行以下命令以对其进行测试:

docker ps
bazel version

第 4 步:运行 build

运行构建,如下所示。输出用户的根目录为:对应于一个目录,该目录可通过运行 Bazel 的主机容器、运行 Bazel 构建操作的 Docker 沙盒功能生成的工具链容器以及运行主机和操作容器的本地机器访问。

bazel --output_user_root=/tmp/bazel_docker_root --bazelrc=.bazelrc \ build --config=docker-sandbox target

第 5 步:解决检测到的问题

您可以按如下方式解决构建失败问题:

  • 如果构建失败并显示“磁盘空间不足”错误,您可以通过启动带有 --memory=XX 标志的主机容器来提高此限制,其中 XX 是分配的磁盘空间(以 GB 为单位)。这是实验性功能,可能会导致不可预见的行为。

  • 如果构建在分析或加载阶段失败,则 WORKSPACE 文件中声明的一个或多个构建规则与远程执行不兼容。如需了解可能的原因和解决方法,请参阅为远程执行调整 Bazel 规则

  • 如果 build 因任何其他原因而失败,请参阅第 2 步:解决检测到的问题中的问题排查步骤。