リモート キャッシュ

問題を報告 ソースを表示

このページでは、リモート キャッシュ、キャッシュをホストするサーバーの設定、リモート キャッシュを使用したビルドの実行について説明します。

リモート キャッシュは、開発者チームや継続的インテグレーション（CI）システムがビルド出力を共有するために使用します。ビルドが再現可能な場合、あるマシンからの出力を別のマシンで安全に再利用できるため、ビルドを大幅に高速化できます。

概要

Bazel は、ビルドをアクションと呼ばれる個別のステップに分割します。各アクションには、入力、出力名、コマンドライン、環境変数があります。必須入力と想定される出力は、アクションごとに明示的に宣言されます。

ビルド出力（これらのアクション出力）用のリモート キャッシュとしてサーバーを設定できます。これらの出力は、出力ファイル名のリストとその内容のハッシュで構成されます。リモート キャッシュを使用すると、新しい出力をローカルでビルドすることなく、別のユーザーのビルドからのビルド出力を再利用できます。

リモート キャッシュを使用するには:

  • サーバーをキャッシュのバックエンドとして設定する
  • リモート キャッシュを使用するように Bazel ビルドを構成する
  • Bazel バージョン 0.10.0 以降を使用します

リモート キャッシュには、次の 2 種類のデータが格納されます。

  • アクション キャッシュ。アクション ハッシュとアクション結果メタデータのマッピングです。
  • 出力ファイルのコンテンツ アドレス指定可能なストア（CAS）。

リモート キャッシュにはさらに、すべてのアクションの stdout と stderr が格納されます。したがって、Bazel の stdout/stderr を調べることは、キャッシュ ヒットの推定を行う際の適切なシグナルではありません。

ビルドがリモート キャッシュを使用する仕組み

サーバーがリモート キャッシュとして設定されると、キャッシュは複数の方法で使用されます。

  • リモート キャッシュの読み取りと書き込み
  • 特定のターゲットを除くリモート キャッシュに対する読み取り/書き込み
  • リモート キャッシュからのみ読み取る
  • リモート キャッシュをまったく使用しない

リモート キャッシュの読み書きが可能な Bazel ビルドを実行する場合、ビルドの手順は次のとおりです。

  1. Bazel は、ビルドする必要があるターゲットのグラフを作成してから、必要なアクションのリストを作成します。これらの各アクションでは、入力と出力ファイル名が宣言されています。
  2. Bazel は、ローカルマシンで既存のビルド出力を確認し、検出結果を再利用します。
  3. Bazel は、キャッシュで既存のビルド出力を確認します。出力が見つかると、Bazel は出力を取得します。これはキャッシュ ヒットです。
  4. 出力が見つからない必要なアクションの場合、Bazel はアクションをローカルで実行し、必要なビルド出力を作成します。
  5. 新しいビルド出力はリモート キャッシュにアップロードされます。

サーバーをキャッシュのバックエンドとして設定する

キャッシュのバックエンドとして機能するサーバーを設定する必要があります。HTTP/1.1 サーバーは Bazel のデータを不透明なバイトとして扱うことができるため、既存のサーバーの多くをリモート キャッシュ バックエンドとして使用できます。リモート キャッシュは Bazel の HTTP キャッシュ プロトコルでサポートされています。

キャッシュに保存された出力を保存するバックエンド サーバーの選択、設定、メンテナンスはお客様側で行う必要があります。サーバーを選択する際は、次の点を考慮してください。

  • ネットワーク速度。たとえば、チームが同じオフィスにいる場合は、独自のローカル サーバーを実行する必要があります。
  • セキュリティはその中の 1 つでしょう。リモート キャッシュにはバイナリがあるため、安全である必要があります。
  • 管理のしやすさ。たとえば、Google Cloud Storage はフルマネージド サービスです。

リモート キャッシュに使用できるバックエンドは多数あります。次のようなオプションがあります。

nginx

nginx はオープンソースのウェブサーバーです。[WebDAV モジュール] により、Bazel のリモート キャッシュとして使用できます。Debian と Ubuntu では、nginx-extras パッケージをインストールできます。macOS では、nginx を Homebrew を介して入手できます。

brew tap denji/nginx
brew install nginx-full --with-webdav

以下に、nginx の構成例を示します。/path/to/cache/dir を、nginx が読み取りと書き込みの権限がある有効なディレクトリに変更する必要があります。出力ファイルが大きい場合は、client_max_body_size オプションをより大きい値に変更する必要があります。サーバーには、認証などの他の構成が必要になります。

nginx.conf の server セクションの構成例:

location /cache/ {
  # The path to the directory where nginx should store the cache contents.
  root /path/to/cache/dir;
  # Allow PUT
  dav_methods PUT;
  # Allow nginx to create the /ac and /cas subdirectories.
  create_full_put_path on;
  # The maximum size of a single file.
  client_max_body_size 1G;
  allow all;
}

Bazel-Remote

bazel-remote は、インフラストラクチャで使用できるオープンソースのリモートビルド キャッシュです。2018 年の初めから、複数の企業で本番環境での使用に成功しています。Bazel プロジェクトでは、bazel-remote のテクニカル サポートを提供していません。

このキャッシュはコンテンツをディスクに格納します。また、ストレージの上限を適用し、未使用のアーティファクトをクリーンアップするためのガベージ コレクションも提供します。キャッシュは [Docker イメージ] として利用でき、コードは GitHub で入手できます。REST と gRPC のリモート キャッシュ API の両方がサポートされています。

使用方法については、GitHub ページをご覧ください。

Google Cloud Storage

[Google Cloud Storage] は、Bazel のリモート キャッシュ プロトコルと互換性のある HTTP API を提供するフルマネージド オブジェクト ストアです。課金が有効になっている Google Cloud アカウントが必要です。

Cloud Storage をキャッシュとして使用するには:

  1. Storage バケットを作成します。リモート キャッシュではネットワーク帯域幅が重要なため、最も近いバケットのロケーションを選択してください。

  2. Bazel が Cloud Storage で認証を行うためのサービス アカウントを作成します。サービス アカウントの作成をご覧ください。

  3. JSON シークレット キーを生成し、認証のために Bazel に渡します。鍵があれば、誰でも GCS バケットとの間で任意のデータの読み書きができるため、鍵は安全に保管してください。

  4. Bazel コマンドに次のフラグを追加して、Cloud Storage に接続します。

    • --remote_cache=https://storage.googleapis.com/bucket-name フラグを使用して、次の URL を Bazel に渡します。bucket-name はストレージ バケットの名前です。
    • アプリケーション認証を使用するには、フラグ --google_credentials=/path/to/your/secret-key.json または --google_default_credentials を使用して認証キーを渡します。

  5. 古いファイルを自動的に削除するように Cloud Storage を構成できます。これを行うには、オブジェクトのライフサイクルの管理をご覧ください。

その他のサーバー

キャッシュのバックエンドとして PUT と GET をサポートする任意の HTTP/1.1 サーバーを設定できます。ユーザーからは、Hazelcast、Apache httpd、AWS S3 などのキャッシュ バックエンドが成功したという報告が寄せられています。

認証

バージョン 0.11.0 で HTTP 基本認証のサポートが Bazel に追加されました。 リモート キャッシュ URL を使用して、ユーザー名とパスワードを Bazel に渡すことができます。構文は https://username:password@hostname.com:port/path です。HTTP 基本認証は、ユーザー名とパスワードをネットワーク経由で平文で送信するので、常に HTTPS で使用することが重要です。

HTTP キャッシュ プロトコル

Bazel は、HTTP/1.1 を介したリモート キャッシュをサポートしています。プロトコルは概念的にシンプルです。バイナリデータ（BLOB）は PUT リクエストによってアップロードされ、GET リクエストによってダウンロードされます。アクションの結果メタデータはパス /ac/ に保存され、出力ファイルはパス /cas/ に保存されます。

たとえば、http://localhost:8080/cache で実行されているリモート キャッシュについて考えてみましょう。SHA256 ハッシュ 01ba4719... を使用するアクションのアクション結果メタデータをダウンロードする Bazel リクエストは次のようになります。

GET /cache/ac/01ba4719c80b6fe911b091a7c05124b64eeece964e09c058ef8f9805daca546b HTTP/1.1
Host: localhost:8080
Accept: */*
Connection: Keep-Alive

SHA256 ハッシュ 15e2b0d3... を含む出力ファイルを CAS にアップロードする Bazel リクエストは次のようになります。

PUT /cache/cas/15e2b0d3c33891ebb0f1ef609ec419420c20e320ce94c65fbc8c3312448eb225 HTTP/1.1
Host: localhost:8080
Accept: */*
Content-Length: 9
Connection: Keep-Alive

0x310x320x330x340x350x360x370x380x39

リモート キャッシュを使用して Bazel を実行する

サーバーがリモート キャッシュとして設定されたら、リモート キャッシュを使用するには、Bazel コマンドにフラグを追加する必要があります。以下の構成とフラグのリストをご覧ください。

選択したサーバーに固有の認証を構成する必要がある場合もあります。

これらのフラグを .bazelrc ファイルに追加すると、Bazel を実行するたびにフラグを指定する必要がなくなります。プロジェクトとチームの動向に応じて、.bazelrc ファイルに次のフラグを追加できます。

  • ローカルマシンの場合
  • プロジェクトのワークスペース（チームで共有）
  • CI システムの場合

リモート キャッシュの読み取りと書き込み

リモート キャッシュへの書き込み権限があるユーザーに注意してください。CI システムのみがリモート キャッシュに書き込めるようにすることもできます。

リモート キャッシュの読み取りと書き込みを行うには、次のフラグを使用します。

build --remote_cache=http://your.host:port

HTTP 以外にも、HTTPS、grpc、grpcs のプロトコルがサポートされています。

リモート キャッシュからの読み取りのみを行うには、上のフラグに加えて次のフラグを使用します。

build --remote_upload_local_results=false

特定のターゲットをリモート キャッシュの使用から除外する

特定のターゲットをリモート キャッシュの使用から除外するには、ターゲットに no-remote-cache のタグを付けます。次に例を示します。

java_library(
    name = "target",
    tags = ["no-remote-cache"],
)

リモート キャッシュからコンテンツを削除する

リモート キャッシュからコンテンツを削除する作業はサーバー管理の一環です。リモート キャッシュからコンテンツを削除する方法は、キャッシュとして設定したサーバーによって異なります。出力を削除する場合は、キャッシュ全体を削除するか、古い出力を削除します。

キャッシュに保存された出力は、名前とハッシュのセットとして保存されます。コンテンツを削除するときに、どの出力が特定のビルドに属しているかを区別することはできません。

以下の場合は、キャッシュからコンテンツを削除することをおすすめします。

  • キャッシュが汚染された後にクリーン キャッシュを作成する
  • 古い出力を削除して、使用するストレージの量を減らす

Unix ソケット

リモート HTTP キャッシュは、Unix ドメイン ソケットを介した接続をサポートしています。この動作は、curl の --unix-socket フラグと同様です。Unix ドメイン ソケットを構成するには、次のコマンドを使用します。

   build --remote_cache=http://your.host:port
   build --remote_proxy=unix:/path/to/socket

この機能は Windows ではサポートされていません。

ディスク キャッシュ

Bazel は、ファイル システム上のディレクトリをリモート キャッシュとして使用できます。これは、ブランチを切り替えるときや、同じプロジェクトの複数のワークスペース（複数のチェックアウトなど）で作業するときにビルド アーティファクトを共有する場合に便利です。Bazel ではディレクトリのガベージ コレクションが行われないため、このディレクトリの定期的なクリーンアップを自動化することをおすすめします。次のようにディスク キャッシュを有効にします。

build --disk_cache=path/to/build/cache

~ エイリアスを使用して、ユーザー固有のパスを --disk_cache フラグに渡すことができます（Bazel は現在のユーザーのホーム ディレクトリに置き換えられます）。これは、プロジェクトのチェックイン済み .bazelrc ファイルを介してプロジェクトのすべてのデベロッパーがディスク キャッシュを有効にする場合に便利です。

既知の問題

ビルド中の入力ファイルの変更

ビルド中に入力ファイルが変更されると、Bazel が無効な結果をリモート キャッシュにアップロードすることがあります。変更検出を有効にするには、--experimental_guard_against_concurrent_changes フラグを使用します。既知の問題はなく、今後のリリースではデフォルトで有効になる予定です。 更新については、[問題 #3360] をご覧ください。一般的に、ビルド中にソースファイルを変更しないでください。

環境変数がアクションに流出している

アクション定義には環境変数が含まれます。これは、マシン間でリモート キャッシュ ヒットを共有する場合に問題になる可能性があります。たとえば、$PATH 変数が異なる環境では、キャッシュ ヒットは共有されません。アクション定義には、--action_env を介して明示的に許可リストに登録された環境変数のみが含まれます。$PATH などの環境変数のホワイトリストと /etc/bazel.bazelrc のインストールに使用される Bazel の Debian/Ubuntu パッケージ。キャッシュ ヒットが予想よりも少ない場合は、環境に古い /etc/bazel.bazelrc ファイルがないことを確認してください。

Bazel はワークスペース外のツールを追跡しない

Bazel では現在、ワークスペース外のツールを追跡しません。これは、たとえば、アクションが /usr/bin/ のコンパイラを使用している場合には問題になります。すると、異なるコンパイラがインストールされている 2 人のユーザーが、出力は異なるもののアクション ハッシュが同じであるため、キャッシュ ヒットが誤って共有されてしまいます。更新については、問題 #4558 をご覧ください。

Docker コンテナ内でビルドを実行すると、増分メモリ内状態が失われます。単一の Docker コンテナで実行している場合でも、Bazel はサーバー/クライアント アーキテクチャを使用します。サーバー側では、Bazel がメモリ内の状態を維持して、ビルドを高速化します。CI などの Docker コンテナ内でビルドを実行すると、メモリ内の状態が失われ、リモート キャッシュを使用する前に Bazel が再ビルドする必要があります。