ローカルでのビルドとデバッグ

このページでは、ローカルマシンで Cloud Build を使用する方法について説明します。ローカル ビルダーを使用すると、次のことが可能になります。

• ローカルマシンでより迅速にビルドを繰り返します。
• ドライランで構成ファイルを検証します。

ローカル ビルダーは Linux または macOS でビルドできます。

警告: Cloud Build のローカル ビルダーは、ベスト エフォートで Cloud Build のローカル デバッグツールとして維持されます。ホストされている Cloud Build サービスと同等の機能を 100% サポートしている訳ではないため、本番環境のワークロードには使用しないでください。

始める前に

1. Google Cloud SDK をインストールして初期化します。

2. Docker をインストールします。Cloud Build と同じ Docker バージョンを使用することをおすすめします。

3. ビルドするソースコード、ビルドのビルド構成ファイルが必要です。また、ビルドステップで必要なツールと依存関係にローカルマシンからアクセスする必要があります。

4. ビルドで非公開レジストリにアクセスする必要がある場合、次のコマンドを実行して Cloud Build の Docker 認証ヘルパーをインストールして構成します。

   gcloud components install docker-credential-gcr
   gcloud auth configure-docker
   

ローカルビルダーをインストールする

ローカル ビルダーは、Google Cloud CLI の中の gcloud CLI のコンポーネントです。これは、システムに応じて、gcloud コマンド、apt-get、または yum を使用してインストールできます。

ローカル ビルダーをインストールするには、次のコマンドを実行します。

gcloud

gcloud components install cloud-build-local

apt-get

sudo apt-get install google-cloud-sdk-cloud-build-local

yum

sudo yum install google-cloud-sdk-cloud-build-local

ローカル ビルダーのインストール後:

• コマンドラインのヘルプを表示するには、次のコマンドを実行します。

  cloud-build-local --help
  

• インストールされているローカル ビルダーのバージョンを確認するには、次のコマンドを実行します。

  cloud-build-local --version
  

ローカルにビルドする

警告: ローカルマシンで同時に実行できるビルドは 1 つだけです。複数のビルドを同時に実行すると、ローカル ビルダーが失敗します。

プロジェクトをまだ設定していない場合、クイックスタートの構成を使用してローカル ビルダーをテストできます。

ローカルでビルドするには、次のコマンドを実行します。

cloud-build-local --config=[BUILD_CONFIG] --dryrun=false --push [SOURCE_CODE]

ここで

• [BUILD_CONFIG] は、ビルド構成ファイルのパスと名前です。
  • たとえば、構成ファイルが作業ディレクトリにあり、名前が cloudbuild.json の場合は、--config=cloudbuild.json フラグを使用します。
  • デフォルト値は cloudbuild.yaml です。構成ファイルが作業ディレクトリにあり、名前が cloudbuild.yaml の場合は、このフラグを追加する必要はありません。
• [SOURCE_CODE] はソースコードのパスです。
  • Cloud Build と同様、ソースコードが現在の作業ディレクトリにある場合は、. を使用してソースを表すことができます。
  • ビルドでソースコードが必要ない場合は、[SOURCE_CODE] の代わりに --no-source フラグを使用します。
• --dryrun=false でビルドを実行できます。--dryrun フラグのデフォルトは true です。デフォルト値で実行すると、構成ファイルはチェックされますが、ビルドコマンドは実行されません。ビルドを実行するには、--dryrun=false を明示的に設定する必要があります。
• --push は、構成ファイルの images または artifacts フィールドで定義されている宛先に生成されたイメージまたはアーティファクトを push します。デフォルトでは、イメージとアーティファクトはビルドされますが、push されません。

ビルドが完了すると、作成されたイメージは Docker を介してローカルマシンで利用できます。ビルドコマンドに追加すると、--push を指定したリポジトリで使用できるようになります。

中間アーティファクトを保存する

ビルド中に、中間アーティファクトが workspace というディレクトリに配置されます。デフォルトでは、ビルドの最後にワークスペースとその内容が削除されます。

ビルドを実行してワークスペースのアーティファクトを保存するには、次のコマンドを実行します。

cloud-build-local --config=[BUILD_CONFIG] --dryrun=false --write-workspace=[LOCAL_DIRECTORY_PATH] [SOURCE_CODE]

ここで

• [BUILD_CONFIG] は構成ファイルのパスです。
• [SOURCE_CODE] はソースコードのパスです。
• [LOCAL_DIRECTORY_PATH] は、ローカルマシン上にワークスペースを保存する、ローカル ディレクトリです。このディレクトリは、[SOURCE_CODE] ディレクトリ内に配置しないでください。

ワークスペースを保存すると、次のことが可能になります。

• ビルドのデバッグ時に中間アーティファクトを分析します。
• ビルダーがワークスペースで作成したビルド結果（バイナリなど）にアクセスします。

ビルドで置換を使用する

ビルドで置換を使用するには、置換する key=value ペアと一緒に --substitutions フラグを使用します。特定のデフォルト変数の値と定義した変数の値を指定できることに注意してください。

例:

cloud-build-local --config=[BUILD_CONFIG] --dryrun=false --substitutions _KEY=value,_FOO=foo [SOURCE_CODE]

ここで

• [BUILD_CONFIG] は構成ファイルのパスです。
• [SOURCE_CODE] はソースコードのパスです。
• この例では、_KEY は value に置換され、_FOO は foo に置換されます。

必要な構文など、置換の詳細については、置換をご覧ください。

ビルドをローカルでデバッグする

ビルドをデバッグするには、次の操作を行います。

• ビルドのドライランを実行して、構成ファイルが正しいことを確認します。
• ビルド中にワークスペースに作成された中間アーティファクトを検査します。詳細については、前述の中間アーティファクトを保存するをご覧ください。

ローカルビルドは、実行時にローカルホスト上で使用可能な権限で実行されます。Cloud Build では、ビルドステップはプロジェクトのサービス アカウントの権限を使用して実行されます。権限の問題をデバッグする場合は、ローカルビルドが Cloud Build 環境に可能な限り近くなるように、Cloud Build サービス アカウントの権限と一致するように権限を設定してください。

ドライランでビルドを検証する

ビルドのドライランを実行すると、構成ファイルがチェックされ、問題が見つかるとエラーが発生します。ドライランはビルドを実行しないので、ビルドを実行するオーバーヘッドなしに構成ファイルを確認できます。ビルダーのドライランを実行するには、ローカル ビルダーを使用する必要があります。

1. 次のコマンドを使用して、ビルドのドライランを実行します。

   cloud-build-local --config=[BUILD_CONFIG] [SOURCE_CODE]
   

   ここで

   • [BUILD_CONFIG] は構成ファイルのパスです。
   • [SOURCE_CODE] はソースコードのパスです。

2. エラー メッセージを確認して、構成ファイルの問題を修正します。

制限事項

• ローカル ビルダーは Linux または macOS でビルドできます。
• 特定のホストでローカル ビルダーが同時に実行できるビルドは 1 つだけです。複数のビルドを同時に実行すると、ローカル ビルダーが失敗します。
• ローカル ビルダーは、ホストされている Cloud Build サービスとの同等の機能を完全にサポートするものではありません。ローカル ビルダーでサポートされていない機能の例は次のとおりです（ただし、これらに限定されません）。
  • 動的置換
  • プライベート プール

ローカル ビルダーと Cloud Build の違い

ローカル ビルダーは Cloud Build を模倣して設計されていますが、完全な相互運用性はありません。ローカル ビルダーで正常に実行されたビルドは、Cloud Build で同じように動作しますが、どちらの方向の互換性も保証されません。また、Cloud Build には、ローカル ビルダーに実装されていない機能があります。

この 2 つのビルダーの環境の違いは次のとおりです。

• ローカル ビルダーはローカルマシンで実行されますが、Cloud Build は Google Cloud Platform で実行されます。
• ビルドを実行する場合、ローカル ビルダーが個人のアカウントを使用し、Cloud Build が cloudbuild サービス アカウント [PROJECT_ID]@cloudbuild.gserviceaccount.com を使用します。ローカル ビルダー用の個人アカウントに権限を設定した場合、cloudbuild サービス アカウントにこれらの権限を複製する必要が生じる場合があります。詳細については、サービス アカウント権限の設定をご覧ください。
• ビルダーによって使用される Docker のバージョンが異なる場合があります。インストールされている Docker のバージョンが Cloud Build で使用されているバージョンと異なる場合、ローカル ビルダーは実行中に警告を出力します。Cloud Build で使用されているのと同じ Docker バージョンを使用することをおすすめします。

次のステップ

• Cloud Build でのビルドについて学習する。