このページでは、リモート キャッシュ、キャッシュをホストするサーバーの設定、リモート キャッシュを使用したビルドの実行について説明します。
リモート キャッシュは、デベロッパー チームや継続的インテグレーション（CI）システム（あるいはその両方）がビルド出力を共有するために使用します。ビルドが再現可能な場合、あるマシンの出力を別のマシンで安全に再利用できるため、ビルドが大幅に高速化されます。
概要
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 は Homebrew を介して利用できます。
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 は、インフラストラクチャで使用できるオープンソースの Remote Build キャッシュです。2018 年初頭から、複数の企業で実際に利用されています。Bazel プロジェクトでは、bazel-remote のテクニカル サポートは提供されません。
このキャッシュにはディスク上のコンテンツが格納されます。また、ガベージ コレクションによって、ストレージの上限を適用し、未使用のアーティファクトをクリーンアップすることもできます。キャッシュは [docker image] として入手でき、そのコードは GitHub で入手できます。REST と gRPC の両方のリモート キャッシュ API がサポートされています。
使用方法については、GitHub ページをご覧ください。
Google Cloud Storage
[Google Cloud Storage] は、Bazel のリモート キャッシュ プロトコルと互換性のある HTTP API を提供する、フルマネージド オブジェクト ストアです。課金が有効になっている Google Cloud アカウントが必要です。
Cloud Storage をキャッシュとして使用するには:
ストレージ バケットを作成する。リモート キャッシュではネットワーク帯域幅が重要であるため、最も近いバケットのロケーションを選択してください。
Bazel が Cloud Storage に対して認証を行うためのサービス アカウントを作成します。サービス アカウントの作成をご覧ください。
シークレット JSON キーを生成し、認証のために Bazel に渡します。鍵を持っているユーザーは GCS バケットとの間で任意のデータの読み取り/書き込みを行えるため、鍵は安全に保管してください。
Bazel コマンドに次のフラグを追加して Cloud Storage に接続します。
--remote_cache=https://storage.googleapis.com/bucket-nameフラグを使用して、Bazel に URL を渡します。ここで、bucket-nameは、ストレージ バケットの名前です。- Application Authentication を使用するには、フラグ
--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 の時点で、Bazel に HTTP Basic 認証が追加されています。リモート キャッシュの 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_cache_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 を介して明示的に許可リストに登録された環境変数のみが含まれます。Bazel の Debian/Ubuntu パッケージで、$PATH を含む環境変数の許可リストを含む /etc/bazel.bazelrc のインストールに使用。キャッシュ ヒットが想定よりも少ない場合は、環境に古い /etc/bazel.bazelrc ファイルがないことを確認してください。
Bazel がワークスペースの外でツールを追跡しない
Bazel は現在、ワークスペース外のツールを追跡しません。たとえば、アクションが /usr/bin/ のコンパイラを使用している場合に問題になります。その場合、異なるコンパイラがインストールされている 2 人のユーザーは、出力が異なるもののアクション ハッシュが同じであるため、キャッシュ ヒットを誤って共有します。更新については、問題 #4558 をご覧ください。
Docker コンテナ内でビルドを実行すると、メモリ内の増分状態が失われます。Bazel は、単一の Docker コンテナで実行している場合でも、サーバー/クライアント アーキテクチャを使用します。 サーバー側では、Bazel がメモリ内状態を維持し、ビルドを高速化します。 CI などの Docker コンテナ内でビルドを実行すると、メモリ内状態は失われ、リモート キャッシュを使用する前に Bazel でビルドを再構築する必要があります。