このページでは、リモート キャッシュ、キャッシュをホストするサーバーの設定、リモート キャッシュを使用したビルドの実行について説明します。
リモート キャッシュは、デベロッパーのチームや継続的インテグレーション（CI）システムがビルド出力を共有するために使用します。ビルドを再現できる場合、1 台のマシンの出力を別のマシンで安全に再利用できるため、ビルドを大幅に高速化できます。
概要
Bazel はビルドを個別のステップ（アクション）に分割します。各アクションには入力、出力名、コマンドライン、環境変数があります。必要な入力と期待される出力は、アクションごとに明示的に宣言されます。
これらのアクション出力であるビルド出力のリモート キャッシュにサーバーを設定できます。これらの出力は、出力ファイル名のリストとその内容のハッシュで構成されます。リモート キャッシュを使用すると、新しい出力をローカルで生成することなく、別のユーザーのビルドの出力を再利用できます。
リモート キャッシュを使用するには:
- キャッシュのバックエンドとしてサーバーを設定する
- リモート キャッシュを使用するように Bazel ビルドを構成する
- Bazel バージョン 0.10.0 以降を使用する
リモート キャッシュには、次の 2 種類のデータが保存されます。
- アクション キャッシュ。アクション ハッシュとアクション結果メタデータのマップです。
- 出力ファイルのコンテンツ アドレス指定可能なストア（CAS）。
リモート キャッシュには、すべてのアクションの stdout と stderr も格納されることに注意してください。したがって、Bazel の stdout/stderr の検査は、キャッシュ ヒットの推定に適していません。
ビルドでリモート キャッシュを使用する方法
サーバーをリモート キャッシュとして設定したら、次のようにキャッシュを使用します。
- リモート キャッシュへの読み取りと書き込み
- 特定のターゲットを除くリモート キャッシュの読み取り / 書き込み
- リモート キャッシュからのみ読み取る
- リモート キャッシュをまったく使用しない
リモート キャッシュへの読み取りと書き込みが可能な Bazel ビルドを実行すると、ビルドは次の手順で実行されます。
- Bazel は、ビルドする必要があるターゲットのグラフを作成し、必要なアクションのリストを作成します。これらのアクションにはそれぞれ入力ファイル名と出力ファイル名が 宣言されています
- Bazel は、ローカルマシンで既存のビルド出力をチェックし、見つかったものを再利用します。
- Bazel は、キャッシュで既存のビルド出力を確認します。出力が見つかった場合、Bazel は出力を取得します。これはキャッシュ ヒットです。
- 出力が見つからなかった必要なアクションについては、Bazel はローカルでアクションを実行し、必要なビルド出力を作成します。
- 新しいビルドの出力がリモート キャッシュにアップロードされます。
キャッシュのバックエンドとしてサーバーを設定する
キャッシュのバックエンドとして機能するサーバーを設定する必要があります。HTTP/1.1 サーバーは Bazel のデータを不透明なバイトとして扱うことができるため、多くの既存のサーバーをリモート キャッシュ バックエンドとして使用できます。リモート キャッシュをサポートするのは、Bazel の HTTP キャッシュ プロトコルです。
キャッシュに保存する出力を格納するバックエンド サーバーの選択、設定、メンテナンスはお客様の責任となります。サーバーを選ぶ際には、以下の点を考慮してください。
- ネットワーク速度。たとえば、チームが同じオフィスにいる場合は、独自のローカル サーバーを実行することをおすすめします。
- セキュリティはその中の 1 つでしょう。リモート キャッシュにはバイナリが含まれるため、セキュリティを確保する必要があります。
- 管理のしやすさ。たとえば、Google Cloud Storage はフルマネージド サービスです。
リモート キャッシュに使用できるバックエンドは多数あります。次のようなオプションがあります。
nginx
nginx はオープンソースのウェブサーバーです。[WebDAV モジュール] を使用すると、Bazel のリモート キャッシュとして使用できます。Debian と Ubuntu では、nginx-extras パッケージをインストールできます。macOS の場合、nginx は Homebble から利用できます。
brew tap denji/nginxbrew 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 リモート キャッシュ API と gRPC リモート キャッシュ API の両方がサポートされています。
使用方法については、GitHub のページをご覧ください。
Google Cloud Storage
[Google Cloud Storage] は、Bazel のリモート キャッシュ プロトコルと互換性のある HTTP API を提供するフルマネージド オブジェクト ストアです。課金が有効になっている Google Cloud アカウントが必要です。
Cloud Storage をキャッシュとして使用するには:
Storage バケットを作成します。ネットワーク帯域幅はリモート キャッシュにとって重要であるため、最も近いバケットのロケーションを選択してください。
Bazel が Cloud Storage を認証するためのサービス アカウントを作成します。サービス アカウントの作成をご覧ください。
シークレット JSON キーを生成し、認証のために Bazel に渡します。鍵を保持しているユーザーは、GCS バケットとの間で任意のデータを読み書きできるため、鍵は安全に保管してください。
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フラグを使用して認証鍵を渡します。
- フラグ
古いファイルを自動的に削除するように 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 コマンドにフラグを追加する必要があります。構成とそのフラグのリストについては、以下をご覧ください。
選択したサーバーに固有の認証を構成することも必要になる場合があります。
Bazel の実行時に毎回指定しなくても済むように、これらのフラグを .bazelrc ファイルに追加することをおすすめします。プロジェクトとチームの状況に応じて、次のフラグを .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 では、ファイル システム上のディレクトリをリモート キャッシュとして使用できます。これは、ブランチを切り替えるときや、複数のチェックアウトなど、同じプロジェクトの複数のワークスペースで作業するときに、ビルド アーティファクトを共有する場合に便利です。次のようにディスク キャッシュを有効にします。
build --disk_cache=path/to/build/cache
~ エイリアスを使用して、ユーザー固有のパスを --disk_cache フラグに渡すことができます（Bazel は現在のユーザーのホーム ディレクトリに置き換えます）。これは、プロジェクトのチェックイン済み .bazelrc ファイルを使用して、プロジェクトのすべてのデベロッパーに対してディスク キャッシュを有効にする場合に便利です。
ガベージ コレクション
Bazel 7.4 以降では、--experimental_disk_cache_gc_max_size と --experimental_disk_cache_gc_max_age を使用して、ディスク キャッシュの最大サイズまたは個々のキャッシュ エントリの存続時間を設定できます。Bazel は、ビルド間のアイドル状態中にディスク キャッシュを自動的にガベージ コレクションします。アイドル タイマーは --experimental_disk_cache_gc_idle_delay で設定できます（デフォルトは 5 分）。
自動ガベージ コレクションの代替として、ガベージ コレクションをオンデマンドで実行するツールも用意されています。
既知の問題
ビルド中の入力ファイルの変更
ビルド中に入力ファイルが変更されると、Bazel は無効な結果をリモート キャッシュにアップロードすることがあります。変更検出を有効にするには、--experimental_guard_against_concurrent_changes フラグを使用します。既知の問題はなく、今後のリリースではデフォルトで有効になる予定です。最新情報については、[issue #3360] をご覧ください。通常、ビルド中にソースファイルを変更しないでください。
アクションに漏洩する環境変数
アクション定義には環境変数を含めます。これは、マシン間でリモート キャッシュ ヒットを共有する場合に問題になる可能性があります。たとえば、$PATH 変数が異なる環境では、キャッシュヒットは共有されません。アクション定義には、--action_env で明示的にホワイトリストに登録された環境変数のみが含まれます。Bazel の Debian / Ubuntu パッケージは、$PATH などの環境変数のホワイトリストを使用して /etc/bazel.bazelrc をインストールしていました。キャッシュ ヒットが想定よりも少ない場合は、環境に古い /etc/bazel.bazelrc ファイルがないことを確認します。
Bazel はワークスペースの外部ツールを追跡しません
Bazel では現在、ワークスペースの外部ツールを追跡していません。たとえば、アクションが /usr/bin/ のコンパイラを使用している場合、これは問題になる可能性があります。この場合、異なるコンパイラがインストールされている 2 人のユーザーが、アクション ハッシュは同じでも出力が異なるため、誤ってキャッシュ ヒットを共有します。最新情報については、問題 #4558 をご覧ください。
Docker コンテナ内でビルドを実行すると、増分インメモリ状態が失われる Bazel は、単一の Docker コンテナで実行する場合でも、サーバー/クライアント アーキテクチャを使用します。サーバーサイドでは、Bazel はビルドを高速化するためにインメモリ状態を維持します。CI など、Docker コンテナ内でビルドを実行すると、メモリ内状態が失われます。Bazel は、リモート キャッシュを使用する前に、その状態を再ビルドする必要があります。