本文介绍了 Bazel 中的沙盒化以及如何调试沙盒环境。
沙盒是一种权限限制策略,用于将进程彼此隔离,或者将进程与系统中的资源隔离开来。对于 Bazel,这意味着限制对文件系统的访问权限。
Bazel 的文件系统沙盒在仅包含已知输入的工作目录中运行进程,因此编译器和其他工具不会看到不应访问的源文件,除非它们知道它们的绝对路径。
沙盒不会以任何方式隐藏承载环境。进程可以自由访问文件系统上的所有文件。但是,在支持用户命名空间的平台上,进程无法修改其工作目录以外的任何文件。这样可以确保 build 图没有可能会影响 build 可再现性的隐藏依赖项。
更具体地说,Bazel 会为每个操作构建一个 execroot/
目录,它在执行时充当该操作的工作目录。execroot/
包含操作的所有输入文件,并用作任何生成的输出的容器。然后,Bazel 会使用操作系统提供的技术(Linux 上的容器和 macOS 上的 sandbox-exec
)将操作限制在 execroot/
中。
采用沙盒的原因
如果没有操作沙盒,Bazel 不知道工具是否使用了未声明的输入文件(操作的依赖项中未明确列出的文件)。当其中一个未声明的输入文件发生更改时,Bazel 仍会认为 build 是最新版本,不会重新构建相应操作。这可能会导致增量 build 不正确。
错误重复使用缓存条目会导致远程缓存出现问题。共享缓存中错误缓存条目会影响项目上的每位开发者,而清除整个远程缓存也不是可行的解决方案。
沙盒可以模仿远程执行的行为。如果构建可与沙盒配合使用,那么它很可能也可以与远程执行配合使用。通过使远程执行上传所有必要的文件(包括本地工具),您可以显著降低编译集群的维护费用,而不是每次想要试用新编译器或更改现有工具时都需要在集群中的每台机器上安装这些工具。
应使用的沙盒策略
您可以使用策略标志选择要使用的沙盒类型(如果有)。使用 sandboxed
策略会使 Bazel 选择下面列出的沙盒实现之一,首选操作系统专用的沙盒,而非封闭的通用沙盒。如果传递 --worker_sandboxing
标志,持久性工作器将在通用沙盒中运行。
local
(也称为 standalone
)策略不会执行任何类型的沙盒操作。它只是执行该操作的命令行,并将工作目录设置为工作区的 execroot。
processwrapper-sandbox
是一种不需要任何“高级”功能的沙盒策略,可以直接用于任何 POSIX 系统。它会构建一个沙盒目录(其中包含指向原始源文件的符号链接),执行该操作的命令行并将工作目录设置为此目录(而不是 execroot),然后将已知的输出工件从沙盒移至 execroot,并删除沙盒。这样可以防止操作意外使用任何未声明的输入文件,并防止相应 execroot 被包含未知输出文件。
linux-sandbox
更进一步,基于 processwrapper-sandbox
构建。与 Docker 在后台执行的操作类似,它使用 Linux 命名空间(用户、装载、PID、网络和 IPC 命名空间)将操作与主机隔离开来。也就是说,这会将整个文件系统设为只读(沙盒目录除外),因此该操作不会意外修改主机文件系统上的任何内容。这可以防止有 bug 的测试意外地对 $HOME 目录执行 rm -rf 转换等情况。您还可选择阻止该操作访问网络。linux-sandbox
使用 PID 命名空间来防止操作查看任何其他进程,并在最后可靠地终止所有进程(甚至包括该操作生成的守护程序)。
darwin-sandbox
类似,但适用于 macOS。它使用 Apple 的 sandbox-exec
工具实现与 Linux 沙盒大致相同的效果。
由于操作系统提供的机制的限制,linux-sandbox
和 darwin-sandbox
均无法在“嵌套”场景中运行。由于 Docker 还对其容器魔法使用 Linux 命名空间,因此除非您使用 docker run --privileged
,否则无法在 Docker 容器内轻松运行 linux-sandbox
。在 macOS 上,您无法在已沙盒化的进程中运行 sandbox-exec
。因此,在这些情况下,Bazel 会自动回退到使用 processwrapper-sandbox
。
如果您不希望出现构建错误(例如,为了避免使用不太严格的执行策略意外进行构建),请明确修改 Bazel 尝试使用的执行策略列表(例如 bazel build
--spawn_strategy=worker,linux-sandbox
)。
动态执行通常需要沙盒才能在本地执行。如需停用,请传递 --experimental_local_lockfree_output
标志。动态执行会以静默方式将持久性工作器沙盒化。
沙盒化的缺点
沙盒环境会产生额外的设置和拆解费用。此费用的大小取决于许多因素,包括 build 的形状和主机操作系统的性能。对于 Linux,沙盒化 build 速度几乎不会超过百分之几。设置
--reuse_sandbox_directories
可以降低设置和拆解费用。沙盒可有效停用该工具可能具有的任何缓存。您可以使用持久性工作器来缓解此问题,但以较弱的沙盒保证为代价。
多路复用工作器需要显式工作器支持才能进行沙盒化。不支持多路沙盒的工作器在动态执行下作为单工工作器运行,可能会消耗额外的内存。
调试
请按照以下策略调试沙盒问题。
已停用的命名空间
在某些平台(例如 Google Kubernetes Engine 集群节点或 Debian)上,出于安全问题的考虑,用户命名空间默认处于停用状态。如果 /proc/sys/kernel/unprivileged_userns_clone
文件存在且包含 0,您可以通过运行以下命令激活用户命名空间:
sudo sysctl kernel.unprivileged_userns_clone=1
规则执行失败
沙盒可能会因系统设置而无法执行规则。如果您看到类似 namespace-sandbox.c:633: execvp(argv[0], argv): No such file or
directory
的消息,请尝试使用 --strategy=Genrule=local
(对于 genrule)和 --spawn_strategy=local
(对于其他规则)停用沙盒。
构建失败的详细调试
如果构建失败,请使用 --verbose_failures
和 --sandbox_debug
让 Bazel 显示构建失败时运行的确切命令,包括设置沙盒的部分。
错误消息示例:
ERROR: path/to/your/project/BUILD:1:1: compilation of rule
'//path/to/your/project:all' failed:
Sandboxed execution failed, which may be legitimate (such as a compiler error),
or due to missing dependencies. To enter the sandbox environment for easier
debugging, run the following command in parentheses. On command failure, a bash
shell running inside the sandbox will then automatically be spawned
namespace-sandbox failed: error executing command
(cd /some/path && \
exec env - \
LANG=en_US \
PATH=/some/path/bin:/bin:/usr/bin \
PYTHONPATH=/usr/local/some/path \
/some/path/namespace-sandbox @/sandbox/root/path/this-sandbox-name.params --
/some/path/to/your/some-compiler --some-params some-target)
现在,您可以检查生成的沙盒目录,查看 Bazel 创建了哪些文件,然后再次运行该命令以查看其行为方式。
请注意,使用 --sandbox_debug
时,Bazel 不会删除沙盒目录。除非您主动调试,否则应停用 --sandbox_debug
,因为它会随着时间的推移填满您的磁盘。