Khắc phục sự cố Thực thi từ xa Bazel bằng Docker Sandbox

Báo cáo vấn đề Xem nguồn Nightly · 8.4 · 8.3 · 8.2 · 8.1 · 8.0 · 7.6

Các bản dựng Bazel thành công trên máy có thể không thành công khi được thực thi từ xa do các quy định hạn chế và yêu cầu không ảnh hưởng đến các bản dựng cục bộ. Những nguyên nhân phổ biến nhất gây ra lỗi như vậy được mô tả trong phần Điều chỉnh các quy tắc Bazel để thực thi từ xa.

Trang này mô tả cách xác định và giải quyết những vấn đề thường gặp nhất khi thực thi từ xa bằng tính năng hộp cát Docker. Tính năng này áp đặt các hạn chế đối với bản dựng tương đương với các hạn chế của việc thực thi từ xa. Điều này giúp bạn khắc phục sự cố bản dựng mà không cần dịch vụ thực thi từ xa.

Tính năng hộp cát Docker mô phỏng các hạn chế của quá trình thực thi từ xa như sau:

  • Các thao tác xây dựng sẽ thực thi trong vùng chứa chuỗi công cụ. Bạn có thể sử dụng cùng một vùng chứa chuỗi công cụ để chạy bản dựng cục bộ và từ xa thông qua một dịch vụ hỗ trợ việc thực thi từ xa trong vùng chứa.

  • Không có dữ liệu thừa nào vượt quá ranh giới vùng chứa. Chỉ những đầu vào và đầu ra được khai báo rõ ràng mới vào và rời khỏi vùng chứa, và chỉ sau khi thao tác tạo liên kết hoàn tất thành công.

  • Mỗi thao tác sẽ thực thi trong một vùng chứa mới. Một vùng chứa mới, riêng biệt được tạo cho mỗi thao tác tạo bản dựng được tạo.

Bạn có thể khắc phục những vấn đề này bằng một trong các phương thức sau:

  • Khắc phục sự cố một cách tự nhiên. Với phương thức này, Bazel và các thao tác xây dựng của nó sẽ chạy nguyên bản trên máy cục bộ của bạn. Tính năng hộp cát Docker áp đặt các quy định hạn chế đối với bản dựng tương đương với các quy định hạn chế của quá trình thực thi từ xa. Tuy nhiên, phương thức này sẽ không phát hiện các công cụ, trạng thái và dữ liệu cục bộ bị rò rỉ vào bản dựng của bạn, điều này sẽ gây ra vấn đề với quá trình thực thi từ xa.

  • Khắc phục sự cố trong vùng chứa Docker. Với phương thức này, Bazel và các thao tác tạo của nó sẽ chạy trong một vùng chứa Docker. Điều này cho phép bạn phát hiện các công cụ, trạng thái và dữ liệu bị rò rỉ từ máy cục bộ vào bản dựng, ngoài việc áp đặt các hạn chế tương đương với các hạn chế của việc thực thi từ xa. Phương thức này cung cấp thông tin chi tiết về bản dựng của bạn ngay cả khi một số phần của bản dựng không thành công. Đây là phương thức thử nghiệm và không được hỗ trợ chính thức.

Điều kiện tiên quyết

Trước khi bắt đầu khắc phục sự cố, hãy làm như sau nếu bạn chưa thực hiện:

  • Cài đặt Docker và định cấu hình các quyền cần thiết để chạy Docker.
  • Cài đặt Bazel 0.14.1 trở lên. Các phiên bản trước đó không hỗ trợ tính năng hộp cát Docker.
  • Thêm kho lưu trữ bazel-toolchains (được ghim vào phiên bản phát hành mới nhất) vào tệp WORKSPACE của bản dựng như mô tả tại đây.
  • Thêm cờ vào tệp .bazelrc để bật tính năng này. Tạo tệp này trong thư mục gốc của dự án Bazel nếu tệp này chưa tồn tại. Các cờ bên dưới là một mẫu tham chiếu. Vui lòng xem tệp .bazelrc mới nhất trong kho lưu trữ bazel-toolchains và sao chép các giá trị của cờ được xác định ở đó cho cấu hình 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

Nếu quy tắc của bạn yêu cầu các công cụ bổ sung, hãy làm như sau:

  1. Tạo một vùng chứa Docker tuỳ chỉnh bằng cách cài đặt các công cụ bằng Dockerfile và tạo hình ảnh cục bộ.

  2. Thay thế giá trị của cờ --experimental_docker_image ở trên bằng tên của hình ảnh vùng chứa tuỳ chỉnh.

Khắc phục sự cố một cách tự nhiên

Phương thức này thực thi Bazel và tất cả các thao tác tạo của Bazel ngay trên máy cục bộ và là một cách đáng tin cậy để xác nhận xem bản dựng của bạn có thành công hay không khi được thực thi từ xa.

Tuy nhiên, với phương thức này, các công cụ, tệp nhị phân và dữ liệu được cài đặt cục bộ có thể bị rò rỉ vào bản dựng của bạn, đặc biệt là nếu bản dựng đó sử dụng các quy tắc WORKSPACE theo kiểu định cấu hình. Những rò rỉ như vậy sẽ gây ra vấn đề với việc thực thi từ xa; để phát hiện những rò rỉ này, hãy khắc phục sự cố trong một vùng chứa Docker ngoài việc khắc phục sự cố một cách tự nhiên.

Bước 1: Chạy bản dựng

  1. Thêm cờ --config=docker-sandbox vào lệnh Bazel thực thi bản dựng của bạn. Ví dụ:

    bazel --bazelrc=.bazelrc build --config=docker-sandbox target

  2. Chạy bản dựng và đợi quá trình này hoàn tất. Bản dựng sẽ chạy chậm hơn bình thường tối đa 4 lần do tính năng hộp cát Docker.

Bạn có thể gặp phải lỗi sau:

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

Nếu có, hãy chạy lại bản dựng bằng cờ --experimental_docker_verbose. Cờ này cho phép hiển thị thông báo lỗi chi tiết. Lỗi này thường do quá trình cài đặt Docker bị lỗi hoặc thiếu quyền thực thi trong tài khoản người dùng hiện tại. Hãy xem tài liệu về Docker để biết thêm thông tin. Nếu vấn đề vẫn tiếp diễn, hãy chuyển đến phần Khắc phục sự cố trong vùng chứa Docker.

Bước 2: Giải quyết các vấn đề phát hiện được

Sau đây là những vấn đề thường gặp nhất và cách giải quyết.

  • Thiếu một tệp, công cụ, tệp nhị phân hoặc tài nguyên được cây runfiles của Bazel tham chiếu.. Xác nhận rằng tất cả các phần phụ thuộc của mục tiêu chịu ảnh hưởng đã được khai báo rõ ràng. Hãy xem phần Quản lý các phần phụ thuộc ngầm để biết thêm thông tin.

  • Thiếu một tệp, công cụ, tệp nhị phân hoặc tài nguyên được tham chiếu theo đường dẫn tuyệt đối hoặc biến PATH. Xác nhận rằng tất cả các công cụ cần thiết đều được cài đặt trong vùng chứa chuỗi công cụ và sử dụng các quy tắc chuỗi công cụ để khai báo đúng các phần phụ thuộc trỏ đến tài nguyên bị thiếu. Hãy xem phần Gọi các công cụ xây dựng thông qua quy tắc chuỗi công cụ để biết thêm thông tin.

  • Không thực hiện được tệp nhị phân. Một trong các quy tắc xây dựng đang tham chiếu đến một tệp nhị phân không tương thích với môi trường thực thi (vùng chứa Docker). Hãy xem phần Quản lý các tệp nhị phân phụ thuộc vào nền tảng để biết thêm thông tin. Nếu bạn không thể giải quyết vấn đề, hãy liên hệ với bazel-discuss@google.com để được trợ giúp.

  • Một tệp trong @local-jdk bị thiếu hoặc gây ra lỗi. Các tệp nhị phân Java trên máy cục bộ của bạn đang rò rỉ vào bản dựng trong khi không tương thích với bản dựng đó. Hãy sử dụng java_toolchain trong các quy tắc và mục tiêu thay vì @local_jdk. Hãy liên hệ với bazel-discuss@google.com nếu bạn cần được trợ giúp thêm.

  • Các lỗi khác. Hãy liên hệ với bazel-discuss@google.com để được trợ giúp.

Khắc phục sự cố trong vùng chứa Docker

Với phương pháp này, Bazel chạy bên trong một vùng chứa Docker lưu trữ và các thao tác xây dựng của Bazel sẽ thực thi bên trong các vùng chứa chuỗi công cụ riêng lẻ do tính năng hộp cát Docker tạo ra. Hộp cát tạo ra một vùng chứa chuỗi công cụ hoàn toàn mới cho mỗi thao tác xây dựng và chỉ một thao tác thực thi trong mỗi vùng chứa chuỗi công cụ.

Phương pháp này giúp bạn kiểm soát chặt chẽ hơn các công cụ được cài đặt trong môi trường lưu trữ. Bằng cách tách riêng quá trình thực thi bản dựng với quá trình thực thi các thao tác bản dựng và giảm thiểu các công cụ đã cài đặt, bạn có thể xác minh xem bản dựng của mình có phụ thuộc vào môi trường thực thi cục bộ hay không.

Bước 1: Tạo vùng chứa

  1. Tạo một Dockerfile để tạo vùng chứa Docker và cài đặt Bazel với một bộ công cụ xây dựng tối thiểu:

    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. Tạo vùng chứa dưới dạng bazel_container:

    docker build -t bazel_container - < Dockerfile

Bước 2: Khởi động vùng chứa

Khởi động vùng chứa Docker bằng lệnh bên dưới. Trong lệnh này, hãy thay thế đường dẫn đến mã nguồn trên máy chủ lưu trữ mà bạn muốn tạo.

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

Lệnh này chạy vùng chứa dưới dạng gốc, ánh xạ ổ cắm docker và gắn thư mục /tmp. Điều này cho phép Bazel tạo các vùng chứa Docker khác và sử dụng các thư mục trong /tmp để chia sẻ tệp với các vùng chứa đó. Mã nguồn của bạn có tại /src bên trong vùng chứa.

Lệnh này cố tình bắt đầu từ một vùng chứa cơ sở debian:stretch bao gồm các tệp nhị phân không tương thích với vùng chứa rbe-ubuntu16-04 được dùng làm vùng chứa chuỗi công cụ. Nếu các tệp nhị phân từ môi trường cục bộ bị rò rỉ vào vùng chứa chuỗi công cụ, thì chúng sẽ gây ra lỗi bản dựng.

Bước 3: Kiểm thử vùng chứa

Chạy các lệnh sau trong vùng chứa Docker để kiểm thử:

docker ps
bazel version

Bước 4: Chạy bản dựng

Chạy bản dựng như minh hoạ bên dưới. Người dùng đầu ra là root để tương ứng với một thư mục có thể truy cập bằng cùng một đường dẫn tuyệt đối từ bên trong vùng chứa lưu trữ nơi Bazel chạy, từ các vùng chứa chuỗi công cụ do tính năng hộp cát Docker tạo ra nơi các thao tác xây dựng của Bazel đang chạy và từ máy cục bộ nơi các vùng chứa lưu trữ và thao tác chạy.

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

Bước 5: Giải quyết các vấn đề phát hiện được

Bạn có thể giải quyết lỗi bản dựng như sau:

  • Nếu bản dựng không thành công do lỗi "hết dung lượng ổ đĩa", bạn có thể tăng giới hạn này bằng cách khởi động vùng chứa máy chủ lưu trữ bằng cờ --memory=XX, trong đó XX là dung lượng ổ đĩa được phân bổ tính bằng gigabyte. Đây là tính năng thử nghiệm và có thể dẫn đến hành vi khó đoán.

  • Nếu bản dựng không thành công trong giai đoạn phân tích hoặc tải, thì một hoặc nhiều quy tắc bản dựng mà bạn khai báo trong tệp WORKSPACE không tương thích với hoạt động thực thi từ xa. Hãy xem bài viết Điều chỉnh các quy tắc của Bazel để thực thi từ xa để biết các nguyên nhân có thể xảy ra và giải pháp tạm thời.

  • Nếu bản dựng không thành công vì bất kỳ lý do nào khác, hãy xem các bước khắc phục sự cố trong Bước 2: Giải quyết các vấn đề đã phát hiện.