使用 Docker Sandbox 解決 Bazel Remote Execution 的問題

回報問題 查看原始碼 Nightly · 7.4 . 7.3 · 7.2 · 7.1 · 7.0 · 6.5

在本機上成功的 Bazel 建構作業，在遠端執行時可能會失敗，因為不影響本機建構作業的限制和要求。有關這類故障的最常見原因，請參閱調整 Remote Execution 的 Bazel 規則。

本頁說明如何使用 Docker 沙箱功能識別及解決遠端執行時最常見的問題，這會對建構作業套用與遠端執行相同的限制。這樣一來，您就能排除建構問題，而無需使用遠端執行服務。

Docker 沙箱功能會模仿遠端執行的限制，如下所示：

  • 建構動作會在工具鍊容器中執行。您可以使用相同的工具鍊容器，透過支援容器化遠端執行的服務在本機和遠端執行建構作業。

  • 沒有其他資料會跨越容器邊界。只有明確宣告的輸入內容和輸出內容才能進入或離開容器，且必須在相關聯的建構動作成功完成後才行。

  • 每個動作都會在新的容器中執行。系統會為每個產生的建構動作建立新的不重複容器。

您可以使用下列任一方法排解這些問題：

  • 原生疑難排解。使用此方法時，Bazel 及其建構動作會在本機電腦中以原生方式執行。Docker 沙箱功能會對建構作業施加與遠端執行作業相同的限制。不過，這個方法不會偵測到本機工具、狀態和資料洩漏至建構作業，這會導致遠端執行作業發生問題。

  • 排解 Docker 容器中的問題。透過此方法，Bazel 及其建構動作會在 Docker 容器中執行，因此可以偵測從本機電腦外洩的工具、狀態和資料，而且除了會施加與遠端執行作業相同的限制。即使部分建構作業失敗，這個方法仍可提供建構作業的深入分析資訊。這個方法屬於實驗性質，並未獲得官方支援。

必要條件

開始排解問題前，請先完成以下步驟 (如果還未這個步驟)：

  • 安裝 Docker 並設定執行所需的權限。
  • 安裝 Bazel 0.14.1 以上版本。較舊版本不支援 Docker 沙箱功能。
  • 請按照這裡的說明，將已綁定至最新版本的 bazel-toolchains 存放區新增至建構作業的 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 和所有建構動作，是確認遠端執行作業是否成功的安全方法。

不過，使用這種方法時，本機安裝的工具、二進位檔和資料可能會流入您的建構作業，尤其是在使用設定樣式 WORKSPACE 規則時。這類漏洞會導致遠端執行作業發生問題。如要偵測這類漏洞，除了原生疑難排解外，還應在 Docker 容器中排解問題。

步驟 1：執行版本

  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 說明文件。如果問題仍未解決，請直接跳到「在 Docker 容器中疑難排解」一節。

步驟 2：解決系統偵測到的問題

以下是常見問題和解決方法。

  • Bazel 執行檔案樹狀目錄參照的檔案、工具、二進位檔或資源遺失了。確認受影響目標的所有依附元件均已明確宣告。詳情請參閱「管理隱含依附元件」。

  • 缺少絕對路徑或 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：執行版本

按照下方所示執行建構作業。輸出使用者為 root，因此會對應至可透過相同絕對路徑存取的目錄，包括 Bazel 執行所在的主機容器、Docker 沙箱功能產生的工具鏈容器 (其中執行 Bazel 的建構動作)，以及主機和動作容器執行所在的本機。

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

步驟 5：解決偵測到的問題

您可以按照下列步驟解決建構失敗問題：

  • 如果建構作業因「磁碟空間不足」錯誤而失敗，您可以使用標記 --memory=XX 啟動主機容器，藉此提高此限制，其中 XX 是分配的磁碟空間 (以 GB 為單位)。這項功能仍在實驗階段，可能會導致無法預測的行為。

  • 如果建構作業在分析或載入階段失敗，您在 WORKSPACE 檔案中宣告的一或多項建構規則與遠端執行不相容。如要瞭解可能的原因和解決方法，請參閱「調整 Bazel 規則以進行遠端執行」。

  • 如果建構作業因其他原因失敗，請參閱「步驟 2：解決偵測到的問題」中的疑難排解步驟。