Google は AI 技術を使用して、コンテンツをご希望の言語に翻訳しています。AI 翻訳には誤りが含まれる場合があります。

Flex テンプレートのトラブルシューティング

このページでは、Dataflow Flex テンプレートを使用している場合に役立つ可能性があるトラブルシューティングのヒントとデバッグ戦略について説明します。デフォルトでは、Flex テンプレートの起動プロセスのタイムアウトは 12 分です。この起動プロセスには、テンプレートコンテナイメージの pull と、ジョブグラフを構築するコードの実行が含まれます。この 12 分以内に起動が完了しない場合、ジョブは「ポーリング結果ファイルのタイムアウト」エラーで失敗します。この情報は、ポーリングタイムアウトの検出、タイムアウトの理由の特定、問題の解決に役立ちます。

Google Cloud コンソールでテンプレートリストの読み込み中にエラーが発生する

Google Cloud コンソールで、Dataflow の [テンプレートからジョブを作成] ページでテンプレートのリストを表示しようとすると、次のようなエラーが表示されます。

Error retrieving templates. Custom templates can still be used.

組織でプリンシパルアクセス境界（PAB）ポリシーを使用している場合、プリンシパル（ユーザーやサービスアカウントなど）が Google 提供のテンプレートを表示して実行できないことがあります。この問題を解決するには、プリンシパルアクセス境界ポリシーを使用して Google 提供のテンプレートにアクセスするのガイダンスを試してください。

ポーリングタイムアウトエラー

ジョブから次のいずれかのエラーメッセージが返されることがあります。

Timeout in polling result file: FILE_PATH. Possible causes are:
1. Your launch takes too long time to finish. Please check the logs on stackdriver.
2. Service account SERVICE_ACCOUNT may not have enough permissions to pull
container image IMAGE_PATH or create new objects in FILE_PATH.
3. Transient errors occurred, please try again.

Timeout in polling result file: FILE_PATH.
Service account: SERVICE_ACCOUNT
Image URL: IMAGE_PATH
Troubleshooting guide at https://cloud.google.com/dataflow/docs/guides/common-errors#timeout-polling

エラーの原因としては、次のことが考えられます。

ベース Docker イメージがオーバーライドされた。
SERVICE_ACCOUNT に入力されるサービスアカウントに必要な権限が付与されていない。
外部 IP アドレスが無効で、VM が Google API とサービスで使用される外部 IP アドレスのセットに接続できない。
ランチャー VM が gcr.io を解決またはアクセスできない。
Flex テンプレートのコンテナイメージが大きい。
グラフを作成するプログラムの完了に時間がかかっている。
ランチャー VM で実行されているコードの完了に時間がかかりすぎる。
断続的なネットワークエラーまたは Cloud Storage エラー。
パイプラインオプションが上書きされている。
Python ユーザー: 依存関係のインストールまたはステージングに時間がかかりすぎている。
一時的なエラーが発生した。

この問題を解決するには、まずジョブログを確認して再試行し、一時的なエラーがないか確認してください。

早期起動に関する問題セクションのガイダンスに沿って、シリアルポートのロギングを有効にします。これにより、追加情報が明らかになる可能性があります。

上記の手順で問題を解決できない場合は、次のトラブルシューティング手順をお試しください。

省略可: テンプレートを実行して問題をさらに診断する

前述の理由の中から、このエラーの原因となっている可能性のあるものを特定するには、次の方法をお試しください。

Google 提供の WordCount テンプレートを実行します。共有 VPC プロジェクトのサブネットワーク、ワーカー VM のプライベート IP、使用する Dataflow ワーカーサービスアカウントなど、ご自身のユースケースに固有のパラメータを指定してください。これらのパラメータの指定方法の詳細については、gcloud リファレンスと API リファレンスをご覧ください。

このジョブを正常に完了できた場合は、ネットワーキング、IAM 権限、プライベート Google アクセスが正しく構成されている可能性が高いと考えられます。
クイックスタートのジョブビルダーを使用してパイプラインを実行するを完了します。これにより、ジョブが Flex テンプレートとして実行されます。ワーカー VM の起動前にジョブが失敗した場合は、ランチャー VM にアクセスし、次のようなコマンドを使用してサンプル Docker イメージをダウンロードしてみてください。
```
docker run --entrypoint /bin/bash -it gcr.io/dataflow-templates/2025-03-11-00_rc02/yaml-template
```
このコマンドが失敗した場合は、イメージのダウンロードでネットワーキングの問題が発生している可能性があります。この場合は、社内のネットワーキングチームに問い合わせてください。
Google 提供の Flex テンプレートを実行し、結果を確認します。Google 提供のテンプレートジョブが正常に完了した場合、問題は特定のカスタムテンプレートコードファイルに関連している可能性があります。この場合は、特定のコードのトラブルシューティングを続けて問題を解決する必要があります。

Docker エントリポイントを確認する

提供されたテンプレートを使用せずに、カスタム Docker イメージからテンプレートを実行する場合は、この手順を試してください。

次のコマンドを使用して、コンテナエントリポイントを確認します。

docker inspect $TEMPLATE_IMAGE

次の出力が表示されます。

Java

/opt/google/dataflow/java_template_launcher

Python

/opt/google/dataflow/python_template_launcher

出力が異なる場合は、Docker コンテナのエントリポイントがオーバーライドされています。$TEMPLATE_IMAGE をデフォルトに戻します。

サービスアカウントの権限を確認する

メッセージにあるサービスアカウントに次の権限があることを確認します。

メッセージの ${file_path} にある Cloud Storage パスの読み取りと書き込み
メッセージの ${image_url} にある Docker イメージの読み取り

限定公開の Google アクセスを構成する

外部 IP アドレスが無効になっている場合は、Compute Engine VM が Google API とサービスで使用される一連の外部 IP アドレスに接続できるようにする必要があります。VM のネットワークインターフェースが使用するサブネットで、限定公開の Google アクセスを有効にします。

構成の詳細は、プライベート Google アクセスの構成をご覧ください。

デフォルトでは、Compute Engine VM がネットワークインターフェースに割り当てられた外部 IP アドレスを持たない場合、他の内部 IP アドレスの宛先にのみパケットを送信できます。

GCR.io のアクセスに関する問題

Flex テンプレートランチャー VM は、ロギングエージェントコンテナ（gcr.io/dataflow-templates-base/template-launcher-logger-distroless）を pull するために gcr.io にアクセスする必要があります。このエージェントは、ランチャーログを Cloud Logging にストリーミングします。ランチャー VM が gcr.io を解決できない、または接続できない場合、起動プロセスが応答を停止し、ポーリングタイムアウトが発生することがあります。

この問題は、カスタムテンプレートイメージが Artifact Registry に保存されている場合でも発生する可能性があります。これは、Logging エージェントが常に gcr.io から pull されるためです。

この問題を診断して解決するには:

シリアルポートのロギングを有効にする: 早期起動に関する問題セクションの手順に沿って操作します。cloud-init プロセスが停止している場合や、gcr-wait-online.service に関連するエラーが発生している場合は、DNS またはネットワークの問題が発生している可能性があります。
ランチャー VM に SSH 接続する: gcloud compute ssh コマンドを使用して、ランチャー VM が実行されている間に接続します。
```
gcloud compute ssh launcher-JOB_ID --tunnel-through-iap
```
JOB_ID は、Dataflow ジョブの ID に置き換えます。
DNS の解決を確認する: ランチャー VM 内で次のコマンドを実行します。
```
curl -I https://gcr.io
```
コマンドが "Could not resolve host" エラーで失敗した場合、DNS 構成に gcr.io のエントリがありません。
起動サービスが停止していないか確認する: cloud-init 出力ログを調べます。
```
sudo cat /var/log/cloud-init-output.log
```
プロセスがネットワークまたは gcr.io がアクセス可能になるのを待機していることを示すメッセージを探します。

また、VPC の DNS 設定で gcr.io の解決が許可されていることを確認してください。一部のプライベートネットワーク構成では、制限付き Google API または限定公開の Google API の IP 範囲を指す gcr.io の特定の DNS A レコードを追加する必要があります。

大きなコンテナイメージ

Flex テンプレートのコンテナイメージが大きい場合、テンプレートの pull と起動がデフォルトの 12 分のタイムアウトを超え、ジョブが失敗する可能性があります。

この問題を軽減するには、次の方法をお試しください。

イメージを最適化してサイズを小さくし、pull プロセスを高速化します。
--launcher-machine-type フラグを使用して、CPU コア数の多いマシンタイプを選択します。これにより、イメージの pull が高速化され、起動が高速化されます。
gcloud CLI の --launcher-vm-timeout-secs フラグ、または REST API と Managed Service for Apache Airflow の ft_launch_timeout_secs 起動オプションを使用して、起動タイムアウトをデフォルトの 12 分（720 秒）の上限を超えて延長します。例については、Flex テンプレートの起動タイムアウトを延長するをご覧ください。

ランチャープログラムを終了できないかどうかを確認する

パイプラインを構築するプログラムは、パイプラインの起動前に終了する必要があります。ポーリングエラーは、時間がかかりすぎたことを示している可能性があります。

コード内で原因を特定するには、次のような方法があります。

プログラムの終了をブロックしているスレッドがないことを確認します。一部のクライアントが独自のスレッドを作成している場合があります。このようなクライアントがシャットダウンされない場合、プログラムはこれらのスレッドが参加するまで待機します。
パイプラインを定義するコードでは、waitUntilFinish（Java の場合）または wait_until_finish（Python の場合）を使用しないでください。これらの関数はプログラムの終了をブロックするため、Flex テンプレートがパイプラインを起動できなくなります。

テンプレートを使用しない直接起動するパイプラインにこうした制限はありません。したがって、パイプラインが直接動作してもテンプレートとして機能していない場合は、テンプレートの使用が根本原因である可能性があります。テンプレートの問題を見つけて修正すると、問題が解決することがあります。

ランチャー VM で長時間実行されるコード

メインプログラムのコードの実行に時間がかかりすぎると、パイプラインが起動する前に Flex テンプレートがタイムアウトすることがあります。これは、初期化中にコードが複雑な計算を実行したり、外部リソースに対して同期呼び出しを行ったりした場合に発生する可能性があります。

この問題を診断するには、ジョブログを確認して、完了までに時間がかかっているオペレーションがないか確認します。たとえば、外部リソースのリクエスト、大規模なデータルックアップ、パイプライン実行フェーズに移動できる重い初期化ロジックなどです。初期化を最適化した後もパイプラインの起動に 12 分以上かかる場合は、Flex テンプレートの起動タイムアウトを延長するをご覧ください。

断続的なネットワークエラーまたは Cloud Storage エラー

ネットワークレイテンシが高い場合や、Cloud Storage API で一時的な問題が発生した場合、「Timeout in polling result file」または「Failed to read the result file」というエラーが断続的に発生することがあります。VPC 内、特にプライベート Google アクセスパス内で慢性的なネットワーク競合が発生すると、多くの場合、400 ～ 500 ミリ秒のレイテンシが発生します。

「結果ファイルのポーリングでタイムアウトが発生しました」は通常、低速障害ですが、「結果ファイルの読み取りに失敗しました」は高速障害です。ただし、どちらも同じ根本的な接続の問題を示していることがよくあります。

これらの断続的な障害を診断するには:

ネットワークレイテンシを確認する: VPC 内のネットワークレイテンシをモニタリングします。レイテンシが高い状態が続くと、ランチャー VM が Cloud Storage からジョブ結果ファイルの書き込みまたは読み取りを試行したときにタイムアウトが発生する可能性があります。
Cloud Storage API の指標をモニタリングする:
1. Google Cloud コンソールで、[API とサービス] ダッシュボードに移動します。
  
  [有効な API とサービス] に移動
2. フィルタして [Cloud Storage API] を選択します。
3. [トラフィック]（送受信バイト数）と [エラー率] のグラフを確認します。
4. ジョブの失敗の正確な時刻と一致する 5xx エラー（503 エラーなど）の急増を探します。

エラーの急増または高レイテンシを特定した場合は、VPC のネットワークパフォーマンスを調査するか、Cloud カスタマーケアにお問い合わせください。

必要なパイプラインオプションが抑制されているかどうかを確認する

Flex テンプレートを使用する場合、パイプラインの初期化時にパイプラインオプションを構成できますが、すべてを構成できるわけではありません。詳細については、このドキュメントのジョブファイルの読み取りに失敗したセクションをご覧ください。

Python ユーザー: 依存関係の管理

requirements.txt ファイルで追加の依存関係を指定する Python Flex テンプレートジョブを実行すると、ジョブの起動に失敗することがあります。このエラーは、要件ファイルで指定された依存関係のダウンロードまたはインストールが、Flex テンプレートの起動に割り当てられた時間よりも長くかかる場合に発生します。

ジョブのパフォーマンスを最適化するには、テンプレートの作成時に依存関係をパッケージ化して、テンプレートの起動時に依存関係をダウンロードまたはインストールする必要がないようにします。詳細については、「Flex テンプレートを構成する」の Python のパッケージ依存関係をご覧ください。依存関係のステージングまたは実行グラフの作成がデフォルトの 12 分の起動タイムアウトを超えている場合は、Flex テンプレートの起動タイムアウトを延長するをご覧ください。

Flex テンプレートの起動タイムアウトを延長する

デフォルトでは、Dataflow は Flex テンプレートの起動フェーズに 720 秒（12 分）のタイムアウトを適用します。大きなコンテナイメージの pull、依存関係のステージング、複雑な実行グラフの作成に 720 秒以上かかる場合は、起動メソッドの起動タイムアウトオプションを構成して、このタイムアウトを増やすことができます。

gcloud CLI

gcloud CLI から Flex テンプレートを実行するときにランチャー VM のタイムアウトを延長するには、--launcher-vm-timeout-secs フラグを gcloud dataflow flex-template run コマンドに渡します。

gcloud dataflow flex-template run JOB_NAME \
  --template-file-gcs-location=TEMPLATE_GCS_PATH \
  --region=REGION \
  --launcher-vm-timeout-secs=TIMEOUT_SECONDS

次の値を置き換えます。

JOB_NAME: Dataflow ジョブの名前。
TEMPLATE_GCS_PATH: Flex テンプレート仕様ファイルの Cloud Storage URI（gs://my-bucket/templates/my-template.json など）。
REGION: ジョブが実行される Dataflow リージョン。
TIMEOUT_SECONDS: ランチャー VM のタイムアウト時間（秒単位）。単位サフィックスなしで正の整数を指定します。デフォルトのタイムアウトは 720（12 分）です。タイムアウトを延長するには、720 より大きく、5400（90 分）以下の整数を指定します。たとえば、20 分の場合は 1200、30 分の場合は 1800 を指定します。

REST API

projects.locations.flexTemplates.launch REST エンドポイントを呼び出して Flex テンプレートを起動する場合は、launchParameter.launchOptions マップの ft_launch_timeout_secs キーを、タイムアウト時間を秒単位で整数として含む文字列に設定します。単位の接尾辞は付けません。

{
  "launchParameter": {
    "jobName": "JOB_NAME",
    "containerSpecGcsPath": "TEMPLATE_GCS_PATH",
    "launchOptions": {
      "ft_launch_timeout_secs": "TIMEOUT_SECONDS"
    }
  }
}

次の値を置き換えます。

JOB_NAME: Dataflow ジョブの名前。
TEMPLATE_GCS_PATH: Flex テンプレート仕様ファイルの Cloud Storage URI（gs://my-bucket/templates/my-template.json など）。
TIMEOUT_SECONDS: ランチャー VM のタイムアウト時間（秒単位）。単位サフィックスのない文字列として正の整数を指定します。デフォルトのタイムアウトは "720"（12 分）です。タイムアウトを延長するには、720 より大きく、5400（90 分）以下の整数を指定します。たとえば、20 分の場合は "1200"、30 分の場合は "1800" を指定します。

Managed Airflow

Managed Airflow または Apache Airflow で DataflowStartFlexTemplateOperator 演算子を使用して Flex テンプレートジョブをオーケストレートする場合は、body 辞書の launchParameter.launchOptions の下に ft_launch_timeout_secs キーを含めます。

from airflow.providers.google.cloud.operators.dataflow import (
    DataflowStartFlexTemplateOperator,
)

start_flex_template = DataflowStartFlexTemplateOperator(
    task_id="start_flex_template",
    project_id="PROJECT_ID",
    location="REGION",
    body={
        "launchParameter": {
            "jobName": "JOB_NAME",
            "containerSpecGcsPath": "TEMPLATE_GCS_PATH",
            "launchOptions": {
                "ft_launch_timeout_secs": "TIMEOUT_SECONDS",
            },
        }
    },
)

次の値を置き換えます。

PROJECT_ID: 実際の Google Cloud プロジェクト ID。
REGION: ジョブが実行される Dataflow リージョン。
JOB_NAME: Dataflow ジョブの名前。
TEMPLATE_GCS_PATH: Flex テンプレート仕様ファイルの Cloud Storage URI（gs://my-bucket/templates/my-template.json など）。
TIMEOUT_SECONDS: ランチャー VM のタイムアウト時間（秒単位）。単位サフィックスなしの文字列として正の整数を指定します。デフォルトのタイムアウトは "720"（12 分）です。タイムアウトを延長するには、720 より大きく、5400（90 分）以下の整数を指定します。たとえば、20 分の場合は "1200"、30 分の場合は "1800" を指定します。

ジョブ起動エラー

次のセクションでは、ジョブの起動の失敗原因となる一般的なエラーと、エラーの解決またはトラブルシューティングの手順について説明します。

テンプレートファイルの読み込み時に権限が拒否されました

gcloud CLI を使用して Google 提供のテンプレートを実行しようとすると、次のようなエラーが表示されます。

ERROR: (gcloud.dataflow.flex-template.run) PERMISSION_DENIED: Template file
failed to load: TEMPLATE_PATH. Permissions denied.
USER does not have storage.objects.get access to the Google
Cloud Storage object. Operations on resource are denied due to an IAM
Principal Access Boundary Policy.

TEMPLATE_PATH は、Google 提供のテンプレート（gs://dataflow-templates や gs://dataflow-templates-REGION_NAME など）を含む Cloud Storage バケット内のテンプレートへのパスです。

早期起動に関する問題

テンプレートの起動プロセスが初期段階で失敗した場合、通常の Flex テンプレートログを使用できない場合があります。起動の問題を調査するには、テンプレートランチャー VM でシリアルポートロギングを有効にします。

Java テンプレートのロギングを有効にするには、enableLauncherVmSerialPortLogging オプションを true に設定します。Python テンプレートと Go テンプレートのロギングを有効にするには、enable_launcher_vm_serial_port_logging オプションを true に設定します。 Google Cloud コンソールでは、このパラメータは [オプションパラメータ] に「Enable Launcher VM シリアルポート Logging」と表示されます。

テンプレートランチャー VM のシリアルポート出力ログを Cloud Logging で確認できます。特定のランチャー VM のログを検索するには、クエリ resource.type="gce_instance" "launcher-number" を使用します。ここで、number は YYYMMDD 形式の現在の日付で始まる値です。

組織のポリシーにより、シリアルポート出力のロギングを有効にすることが禁止されている場合があります。

ジョブファイルの読み取りに失敗した

Flex テンプレートからジョブを実行しようとした際に、ジョブが失敗して、次のエラーが発生する場合があります。

Failed to read the job file : gs://dataflow-staging-REGION-PROJECT_ID/staging/template_launches/TIMESTAMP/job_object...

このエラーは、必要なパイプラインの初期化オプションが上書きされた場合に発生します。Flex テンプレートを使用する場合、パイプラインの初期化時にパイプラインオプションを構成できますが、すべてを構成できるわけではありません。Flex テンプレートに必要なコマンドライン引数が上書きされると、テンプレートランチャーから渡されたパイプラインオプションがジョブによって無視、オーバーライド、または破棄される可能性があります。ジョブの起動に失敗するか、Flex テンプレートを使用していないジョブが起動する可能性があります。

この問題を回避するため、パイプラインの初期化中に、ユーザーコードまたは metadata.json ファイルで次のパイプラインオプションを変更しないでください。

Java

runner
project
jobName
templateLocation
region

Python

runner
project
job_name
template_location
region

Go

runner
project
job_name
template_location
region

結果ファイルの読み取りに失敗した

Flex テンプレートからジョブを実行しようとした際に、ジョブが失敗して、次のエラーが発生する場合があります。

Failed to read the result file : gs://BUCKET_NAME...

このエラーは、Compute Engine のデフォルトのサービスアカウントに、Flex テンプレートの実行に必要なすべての権限がない場合に発生します。

必要な権限の一覧については、Flex テンプレートを実行する権限をご覧ください。

このエラーは、次のことが原因で発生することもあります。

Flex テンプレートを root 以外のユーザーとして実行しようとしている。これは通常、サポートされていません。詳細については、root 以外のユーザーとしての実行はサポートされていませんをご覧ください。または、アカウントチームにお問い合わせください。
断続的なネットワークレイテンシまたは Cloud Storage API の問題。詳細については、断続的なネットワークエラーまたは Cloud Storage エラーをご覧ください。

リソースの権限が拒否された

Flex テンプレートからジョブを実行しようとした際に、ジョブが失敗して、次のエラーが発生する場合があります。

Permission "MISSING_PERMISSION" denied on resource "projects/PROJECT_ID/locations/REGION/repositories/REPOSITORY_NAME" (or it may not exist).

このエラーは、使用したサービスアカウントに、Flex テンプレートの実行に必要なリソースにアクセスする権限がない場合に発生します。

この問題を回避するには、サービスアカウントに必要な権限があることを確認します。必要に応じて、サービスアカウントの権限を調整します。

フラグは指定されているが定義されていない

worker_machine_type パイプラインオプションを使用して Go Flex テンプレートを実行しようとすると、パイプラインが次のエラーで失敗します。

flag provided but not defined: -machine_type

このエラーは、Apache Beam Go SDK バージョン 2.47.0 以前の既知の問題が原因で発生します。この問題を解決するには、Apache Beam Go バージョン 2.48.0 以降にアップグレードしてください。

リモートジョブサーバー JAR を取得できない

インターネットに接続していないときに Flex テンプレートからジョブを実行しようとすると、ジョブが失敗して次のエラーが発生することがあります。

Unable to fetch remote job server jar at
https://repo.maven.apache.org/maven2/org/apache/beam/beam-sdks-java-io-expansion-service/VERSION/beam-sdks-java-io-expansion-service-VERSION.jar:
\u003curlopen error [Errno 101] Network is unreachable\u003e

このエラーは、VM がインターネットから Apache Beam Java パッケージをダウンロードできないために発生します。このパッケージは、Flex テンプレートを使用して多言語ジョブを実行する場合に必要となります。

この問題を解決するには、次のいずれかの変更を行います。

インターネットに接続します。インターネットに接続すると、ジョブが必要なファイルにアクセスできます。
ジョブがローカルでアクセスできるように、Apache Beam Java パッケージをローカルディレクトリに含めます。ディレクトリ /root/.apache_beam/cache/jars/ にファイルを配置します。例: /root/.apache_beam/cache/jars/beam-sdks-java-io-expansion-service-SDK_VERSION.jar

指定されたパスからファイルシステムを取得できない

Flex テンプレートからジョブを実行しようとした際に、ジョブが失敗して、次のエラーが発生する場合があります。

ValueError: Unable to get filesystem from specified path, please use
the correct path or ensure the required dependency is installed, e.g., pip
install apache-beam[gcp]. Path specified: PATH

このエラーは、ジョブが Flex テンプレートのコンテナイメージを使用し、このコンテナイメージに Java インストールが含まれていない場合に発生します。

この問題を解決するには、Dockerfile に次の行を追加します。

sh RUN apt-get update && apt-get install -y openjdk-17-jdk

このコマンドは、コンテナ環境に Java をインストールします。

ランチャー VM のリソースの枯渇

Flex テンプレートからジョブを実行しようとした際に、ジョブが失敗して、次のエラーが発生する場合があります。

Failed to start the VM, launcher-ID, used for launching because of status code: INTERNAL, reason: Unknown error in operation 'OPERATION_ID': [ZONE_RESOURCE_POOL_EXHAUSTED_WITH_DETAILS] 'The zone 'projects/PROJECT_ID/zones/ZONE_ID' does not have enough resources available to fulfill the request.

VM 名 launcher-ID は、ランチャー VM 名を表します。ランチャー VM は、ジョブグラフをビルドして Dataflow サービスに送信して作業を開始する前に、テンプレートコードやイメージなどのジョブリソースを収集します。

launcherMachineType パラメータを指定しない場合、Dataflow はランチャー VM のデフォルトのマシンタイプ（通常は e2-standard-2）を選択します。この選択は、ワーカー machineType とは無関係です。このデフォルトのマシンタイプがジョブのリージョンまたはゾーンで使用できない場合、リソース不足エラーが発生することがあります。特定のマシンタイプを使用するには、launcherMachineType を設定します。

この問題を解決するには、次のいずれかの方法を使用します。

ランチャーのマシンタイプを別のマシンタイプに更新して、ジョブを再試行します。
- REST API: flexTemplates.launch メソッドで launchParameter.environment.launcherMachineType を設定します。
- gcloud CLI: gcloud dataflow flex-template run コマンドで --launcher-machine-type フラグを設定します。
zone パラメータを設定している場合は、Dataflow が容量のあるゾーンにランチャー VM を配置できるように、このパラメータを削除します。
別のリージョンから Flex テンプレートを起動します。

Flex テンプレートランチャーの遅延

Flex テンプレートジョブを送信すると、ジョブリクエストは Spanner キューに入ります。テンプレートランチャーは、Spanner キューからジョブを取得し、テンプレートを実行します。Spanner にメッセージバックログがある場合、ジョブを送信してからジョブが起動するまでに大幅な遅延が発生することがあります。

この問題を回避するには、別のリージョンから Flex テンプレートを起動します。

テンプレートパラメータが無効

gcloud CLI を使用して、Google 提供のテンプレートを使用するジョブを実行すると、次のエラーが発生します。

ERROR: (gcloud.beta.dataflow.flex-template.run) INVALID_ARGUMENT: The template
parameters are invalid. Details: defaultSdkHarnessLogLevel: Unrecognized
parameter defaultWorkerLogLevel: Unrecognized parameter

このエラーは、Google 提供のテンプレートの一部が defaultSdkHarnessLog オプションと defaultWorkerLog オプションをサポートしていないために発生します。

この問題を解決するには、テンプレートタイプに適した方法を使用します。

Flex テンプレート

Flex テンプレートの場合は、--additional-pipeline-options フラグを使用してパイプラインオプションを文字列として渡します。たとえば、gcloud dataflow flex-template run コマンドを使用します。

gcloud dataflow flex-template run JOB_NAME \
--template-file-gcs-location=GCS_TEMPLATE_PATH \
--additional-pipeline-options=defaultSdkHarnessLogLevel=WARN,defaultWorkerLogLevel=WARN

次の値を置き換えます。

JOB_NAME: Dataflow ジョブの名前
GCS_TEMPLATE_PATH: テンプレートファイルへの Cloud Storage パス

クラシックテンプレート

クラシックテンプレートの場合、回避策は、テンプレート仕様ファイルを Cloud Storage バケットにコピーし、次の追加パラメータをファイルに追加することです。

"metadata": {
    ...
    "parameters": [
      ...,
      {
        "name": "defaultSdkHarnessLogLevel",
        "isOptional": true,
        "paramType": "TEXT"
      },
      {
        "name": "defaultWorkerLogLevel",
        "isOptional": true,
        "paramType": "TEXT"
      }
    ]
  }

テンプレートファイルにこの変更を加えたら、テンプレートを実行するときに次のフラグを使用します。

--gcs-location=gs://BUCKET_NAME/FILENAME

次の値を置き換えます。

BUCKET_NAME: Cloud Storage バケットの名前
FILENAME: テンプレート仕様ファイルの名前

Flex テンプレートランチャーログの重大度が間違っている

カスタム Flex テンプレートの起動に失敗すると、次のメッセージが重大度 ERROR でログファイルに記録されます。

ERROR: Error occurred in the launcher container: Template launch failed. See console logs.

通常、このメッセージの前に起動失敗の根本原因が重大度 INFO でログに記録されます。Flex テンプレートランチャーには、Apache Beam アプリケーションによって生成されたログメッセージから重大度の詳細を抽出する方法がありません。このため、このログレベルが正しくない可能性があります。

ランチャーログのメッセージの正しい重大度を確認するには、ログを書式なしテキストではなく JSON 形式で生成するようにテンプレートを構成します。この構成により、テンプレートランチャーはログメッセージの正しい重大度を抽出できます。次のメッセージ構造を使用します。

{
  "message": "The original log message",
  "severity": "DEBUG/INFO/WARN/ERROR"
}

Java では、カスタム JSON アペンダー実装で Logback ロガーを使用できます。詳細については、GitHub の Logback の構成例と JSON アペンダーのコードの例をご覧ください。

この問題は、パイプラインの起動時に Flex テンプレートランチャーによって生成されたログにのみ影響します。起動に成功し、パイプラインが実行されている場合、Dataflow ワーカーによって生成されるログには適切な重大度が設定されます。

Google 提供のテンプレートは、この JSON ロギングアプローチを使用しているため、ジョブの開始時に正しい重大度が表示されます。

Flex テンプレートのトラブルシューティング コレクションでコンテンツを整理 必要に応じて、コンテンツの保存と分類を行います。

Google Cloud コンソールでテンプレート リストの読み込み中にエラーが発生する

ポーリング タイムアウト エラー

省略可: テンプレートを実行して問題をさらに診断する

Docker エントリポイントを確認する

Java

Python

サービス アカウントの権限を確認する

限定公開の Google アクセスを構成する

GCR.io のアクセスに関する問題

大きなコンテナ イメージ

ランチャー プログラムを終了できないかどうかを確認する

ランチャー VM で長時間実行されるコード

断続的なネットワーク エラーまたは Cloud Storage エラー

必要なパイプライン オプションが抑制されているかどうかを確認する

Python ユーザー: 依存関係の管理

Flex テンプレートの起動タイムアウトを延長する

gcloud CLI

REST API

Managed Airflow

ジョブ起動エラー

テンプレート ファイルの読み込み時に権限が拒否されました

早期起動に関する問題

ジョブファイルの読み取りに失敗した

Java

Python

Go

結果ファイルの読み取りに失敗した

リソースの権限が拒否された

フラグは指定されているが定義されていない

リモート ジョブ サーバー JAR を取得できない

指定されたパスからファイルシステムを取得できない

ランチャー VM のリソースの枯渇

Flex テンプレート ランチャーの遅延

テンプレート パラメータが無効

Flex テンプレート

クラシック テンプレート

Flex テンプレート ランチャー ログの重大度が間違っている

Flex テンプレートのトラブルシューティング

Google Cloud コンソールでテンプレートリストの読み込み中にエラーが発生する

ポーリングタイムアウトエラー

サービスアカウントの権限を確認する

大きなコンテナイメージ

ランチャープログラムを終了できないかどうかを確認する

断続的なネットワークエラーまたは Cloud Storage エラー

必要なパイプラインオプションが抑制されているかどうかを確認する

テンプレートファイルの読み込み時に権限が拒否されました

リモートジョブサーバー JAR を取得できない

Flex テンプレートランチャーの遅延

テンプレートパラメータが無効

クラシックテンプレート

Flex テンプレートランチャーログの重大度が間違っている