パイプラインの障害のトラブルシューティング

カスタマイズ フェーズで Image Builder パイプラインが失敗した場合は、ログファイルを確認し、ワーカー VM でインタラクティブ デバッグ フラグを構成するか、中間デバッグ イメージを分析して、コンパイル時またはスクリプトのエラーを特定します。

始める前に

  • まだ設定していない場合は、認証を設定します。認証では、 Google Cloud サービスと API にアクセスするための ID が確認されます。ローカル開発環境からコードまたはサンプルを実行するには、次のいずれかのオプションを選択して Compute Engine に対する認証を行います。

    1. Google Cloud CLI をインストールします。インストール後、次のコマンドを実行して Google Cloud CLI を初期化します。

      gcloud init

      外部 ID プロバイダ（IdP）を使用している場合は、まず連携 ID を使用して gcloud CLI にログインする必要があります。

    2. デフォルトのリージョンとゾーンを設定します。

ロギング チャンネルを確認する

Image Builder は、スタックのさまざまなレベルで障害を診断できるように、複数の場所にログを書き込みます。

  • Cloud Build オーケストレーター ログ: Cloud Build コンソールに高レベルのビルダー ステップが表示されます。ステップが失敗すると、対応する Cloud Storage workdir ディレクトリへのリンクが出力されます。
  • カスタマイズ VM エージェントのログ: カスタマイズ エージェントは、カスタマイズ手順の標準出力（stdout）と標準エラー（stderr）をキャプチャします。オーケストレーターはこれらのレコードをポーリングし、Cloud Build トレースログに直接ストリーミングします。ログが切り捨てられている場合や、ログ全体を検査する必要がある場合は、_GCS_WORKDIR バケットでビルド ID に一致するフォルダに移動します。
  • シリアル コンソールのログ: ゲスト OS が起動に失敗すると、カスタマイズ エージェントは起動できません。このような場合は、シリアル コンソール ログを確認します。オーケストレーターは、ワーカー VM のシリアルポート出力を Cloud Storage の workdir バケットに直接ストリーミングします。失敗した Cloud Build トレースの最後に、シリアルログ ファイルへのリンクが出力されます。
  • ゲスト OS ジャーナル ログ: Linux でシステムレベルの詳細なトラブルシューティングを行うため、カスタマイズ エージェントは実行の最後に、システム全体の journal ログのコピーを Cloud Storage の workdir バケットにアップロードします。

デバッグフラグを使用してスクリプトの失敗を解決する

デフォルトでは、カスタマイズ ステップが失敗すると、Image Builder は実行を終了し、ワーカー VM を直ちに削除してコストを制御します。

スクリプトをインタラクティブにデバッグするには、debug フラグを有効にします。これにより、VM がアクティブな状態になり、SSH を使用してアクティブなゲスト システムに直接接続できます。

デバッグフラグを有効にする

imagebuilder.yaml ファイルで、infrastructureConfig ブロックの下に debug: true を設定します。

infrastructureConfig:
  machineType: e2-standard-4
  zone: us-central1-a
  # Enable interactive debugging
  debug: true
  instanceDurationHours: 1.5

ビルドをトリガーして失敗を待つ

標準的な方法でビルドを送信します。パイプラインでスクリプト エラーが発生すると、次のようになります。

  1. オーケストレーターはビルドの実行を一時停止します。
  2. Image Builder はワーカー VM を削除しません。プロジェクトで実行されたままになります。
  3. VM は、自動終了までの instanceDurationHours プロパティで指定された時間、アクティブな状態を維持します。

ワーカー VM に接続してデバッグする

Cloud Build コンソールの出力を確認して、アクティブなワーカー VM インスタンスの名前を取得します。ターミナルを開き、gcloud compute ssh を使用してワーカー VM に接続します。

gcloud compute ssh WORKER_VM_NAME \
    --zone=BUILD_ZONE \
    --project=PROJECT_ID

imagebuilder.yaml ファイルで externalIP: none が構成され、外部 IP アドレスが生成されない場合は、Identity-Aware Proxy（IAP）TCP 転送を使用して接続するために --tunnel-through-iap フラグを含めます。

gcloud compute ssh WORKER_VM_NAME \
    --zone=BUILD_ZONE \
    --project=PROJECT_ID \
    --tunnel-through-iap

接続すると、コマンドをリアルタイムで実行したり、ターゲット ファイルを検査したり、実行中のプロセスを分析したり、インストーラの履歴ログを確認したり、ディスク上でテスト スクリプトの変更を直接テストしたりできます。

中間デバッグ画像を分析する

debug フラグを使用してワーカー VM をアクティブに保つ代わりに、自動生成されたデバッグ イメージを使用してディスクの状態を分析できます。

  1. debug: false（デフォルト）でビルドが失敗するたびに、オーケストレーターは部分的にカスタマイズされたブートディスクを Compute Engine イメージとしてエクスポートします。
  2. デバッグ イメージの名前は image-builder-debug-image-BUILD_ID パターンで指定され、image-builder-debug-images イメージ ファミリーに割り当てられます。

  3. ファイル システムを検査するには、このデバッグ イメージをブートディスクとして使用して、一時 VM インスタンスを作成します。

    gcloud compute instances create temp-debug-vm \
    --image-family=image-builder-debug-images \
    --zone=ZONE \
    --project=PROJECT_ID

  4. temp-debug-vm インスタンスに接続してディスクを調べ、カスタマイズが失敗した理由を特定します。

Cloud Build のタイムアウトを解決する

Image Builder パイプラインの実行に想定よりも時間がかかると、Cloud Build ジョブが停止し、TIMEOUT ステータスで失敗します。

ビルド時間は変動する可能性があり、通常は大規模なマシンタイプほど長くなります。そのため、ビルドが完了するまでの時間を長くするために、タイムアウトを設定します。設定しない場合、デフォルトの Cloud Build タイムアウトは 1 時間（3600s）です。

タイムアウトを長くするには、cloudbuild.yaml ファイルのルートレベルで timeout フィールドを設定します。

options:
  automapSubstitutions: true
  requestedVerifyOption: VERIFIED
  substitutionOption: ALLOW_LOOSE
  dynamicSubstitutions: true
  logging: CLOUD_LOGGING_ONLY

# Increase the overall build timeout (for example, 2 hours)
timeout: '7200s'

タイムアウト値を更新したら、ビルドを再実行し、Image Builder パイプラインが完了まで実行できることを確認します。

timeout パラメータの詳細については、Cloud Build ドキュメントの timeout をご覧ください。