Cloud Scheduler の問題をトラブルシューティングする

Cloud Scheduler は、各ジョブの実行の開始時と終了時にログを公開します。これにより、ジョブの問題を診断して解決できます。特定のジョブの実行ログと監査ログを取得、表示、分析できます。詳細については、ログの表示をご覧ください。

デフォルトでは、Cloud Scheduler ジョブがターゲット サービス(ジョブリクエスト ハンドラ)から確認応答を受信しない場合、Cloud Scheduler はジョブが失敗したと見なし、構成した指数バックオフに従って再試行します。

Google Cloud サービスに影響するインシデントについては、Google Cloud Service Health ダッシュボードと Cloud Scheduler に関して報告されているすべてのインシデントをご覧ください。

ダウンストリーム サービスの問題によりジョブが失敗する

ジョブの失敗は、Cloud Scheduler 自体ではなく、Cloud Scheduler がターゲットとしているダウンストリーム サービス(Cloud Run など)の問題が原因である可能性があります。次の条件が適用される場合、ダウンストリーム サービスの問題が発生する可能性があります。

  • Cloud Scheduler の権限が正しく設定されている。
  • Cloud Scheduler がターゲット サービスに正常にアクセスできる。
  • Cloud Scheduler の実行ログのエラー メッセージは、ダウンストリーム サービスから送信されます。

この問題を解決するには、次の操作を行います。

  1. ダウンストリーム サービスを直接呼び出す: Cloud Scheduler を使用せずにダウンストリーム サービスを呼び出せることを確認します。呼び出しが成功した場合は、Cloud Scheduler が問題の原因となっている可能性があります。失敗した場合は、ダウンストリーム サービスをさらにデバッグする必要があります。
  2. 宛先サービスログを調べる: 宛先サービスのログを調べて、出力されているエラーを特定し、それに応じてトリアージします。
  3. 長時間実行オペレーションを探す: Cloud Scheduler が長時間実行オペレーション(30 分以上)に対して HTTP 504 エラーを返す場合は、宛先サービスログを調べて、実行が成功したか失敗したかを確認します。宛先サービスのリクエスト タイムアウトが長い可能性があります。このシナリオでは、Cloud Scheduler がタイムアウトし、宛先サービスがまだ実行されている間にジョブを再試行することがあります。再試行時に重複実行を防止するには、ジョブリクエストの重複除去をご覧ください。

ジョブが権限エラーで失敗する

権限は、リソースにアクセスできるプリンシパルと、許可されるオペレーションを制御します。権限の構成が誤っていると、ジョブの実行が中断され、権限拒否エラーが発生する可能性があります。監査ログには、すべての権限変更の詳細な記録が記録されるため、これらの問題の原因を特定できます。

Cloud Scheduler ジョブが権限エラーで失敗すると、実行ログに "debugInfo":"URL_ERROR-ERROR_OTHER. Original HTTP response code number = 403" のようなメッセージが表示されることがあります。

この問題を解決するには、次のいずれかの確認を完了してください。

  • サービス エージェントに付与されている Identity and Access Management(IAM)ロールを確認する: Cloud Scheduler サービス エージェントには、Cloud Scheduler サービス エージェント(roles/cloudscheduler.serviceAgent)ロールが必要です。このロールがないと、Cloud Scheduler ジョブは失敗します。このロールは、Cloud Scheduler サービス エージェントに手動で付与できます。手動での付与が必要になるのは、2019 年 3 月 19 日より前に Cloud Scheduler API を有効にした場合、または Cloud Scheduler サービス エージェントのロールを削除した場合のみです。詳細については、Cloud Scheduler サービス エージェントのロールを付与するをご覧ください。

  • サービス アカウントの権限を確認する: ジョブに接続されているサービス アカウントに、宛先サービスを呼び出すための正しい権限とスコープがあることを確認します。これには、ターゲットが別のプロジェクトにある場合や、仲介サービスの最終ターゲットである場合も含まれます。ターゲットが Google Cloud内にある場合は、サービス アカウントに必要なロールが付与されていることを確認します。 Google Cloud 内の各サービスには特定のロールが必要です。生成されたトークンは受信側のサービスによって自動的に検証されます。たとえば、Cloud Run と Cloud Run functions の場合は、Cloud Run Invoker ロール(roles/run.invoker)を付与する必要があります。ターゲットが Google Cloudの外部にある場合、受信サービスはトークンを手動で確認する必要があります。詳細については、Cloud Scheduler の認証と HTTP ターゲットで認証を使用するをご覧ください。

  • VPC Service Controls の違反を確認する: VPC Service Controls は、データの引き出しを防ぐセキュアな境界を設定できるGoogle Cloud の機能です。VPC Service Controls に起因するエラーかどうかを特定するには、VPC Service Controls が有効で、使用するプロジェクトとサービスに適用されているかどうかを確認します。プロジェクトとサービスが VPC Service Controls で保護されているかどうかを確認するには、そのリソース階層レベルで VPC Service Controls ポリシーを確認します。

    問題の範囲を把握するには、監査ログから VPC Service Controls のエラーを取得します。

    1. Google Cloud コンソールで、 [ログ エクスプローラ] ページに移動します。

      [ログ エクスプローラ] に移動

      検索バーを使用してこのページを検索する場合は、小見出しが [Logging] の結果を選択します。

    2. 次の条件で監査ログをクエリします。

      severity="ERROR" AND protoPayload.status.details.violations.type="VPC_SERVICE_CONTROLS"

      具体的には、エラー メッセージに次のテキストが含まれる場合があります。

      • Request is prohibited by organization's policy
      • Request violates VPC Service Controls

    VPC Service Controls の構成時に発生する可能性のある問題の詳細については、一般的な問題のトラブルシューティングをご覧ください。

  • プライベート エンドポイントを確認する: Cloud Scheduler は、Cloud Run、Cloud Run functions、 Google Cloud API などのサポートされているプライベート エンドポイントのみを VPC Service Controls の境界内で呼び出すことができます。宛先サービスの上り(内向き)設定(Cloud Run のネットワーク上り(内向き)を制限するなど)と、接続されているサービス アカウントの権限を確認します。URL_ERROR-ERROR_DNS エラー メッセージが表示されることがあります。詳細については、このドキュメントの宛先ターゲットに到達できないためジョブが失敗するをご覧ください。

宛先ターゲットに到達できないためジョブが失敗する

この問題は、宛先ターゲットに到達できないために Cloud Scheduler ジョブが失敗した場合に発生します。実行ログに、URL_ERROR または URL_UNREACHABLE で始まるエラーが表示される。

この問題を解決するには、受信したエラー メッセージに応じて、次のいずれかのチェックを行います。

  • URL_ERROR-ERROR_AUTHENTICATION: HTTP 401 (Unauthorized) または HTTP 407 (Proxy Authentication Required) エラーが返されます。宛先ターゲットには認証が必要ですが、Cloud Scheduler リクエストに有効な認証トークンが含まれていません。たとえば、リクエストに認証ヘッダーがないか、認証情報が無効です。ジョブの認証設定を確認します。ターゲット エンドポイントのリクエスト ヘッダーに API キーが必要な場合は、ヘッダー名が api_key ではなく、ターゲット サービスが想定している名前(x-api-key や X-Goog-Api-Key など)と一致していることを確認します。詳細については、Cloud Scheduler に対する認証と HTTP ターゲットで認証を使用するをご覧ください。

  • URL_ERROR-ERROR_DNS: ドメイン ネーム システム(DNS)を使用してホスト名を解決できなかったため、URL の取得に失敗したことを示します。たとえば、ホスト名が存在しないか、関連付けられた IP アドレスがない場合です。エラー メッセージに、Original HTTP response code number = 0 というテキストが含まれる場合があります。ホスト名の有効性を確認します。プライベート エンドポイントを呼び出す場合は、Cloud Scheduler でサポートされていることを確認し、上り(内向き)設定を確認します。

  • URL_ERROR-ERROR_NOT_FOUND: ウェブサーバーが HTTP 404 Not Found エラーを返します。ターゲット URL が正しく、リソースが存在するかどうかを確認します。

  • URL_ERROR-ERROR_OTHER: 以前に詳細が説明されていない一般的な HTTP 4xx エラーを指します。ログを調べて、元の HTTP レスポンス コードを取得します。HTTP 403 エラーが発生した場合は、このドキュメントのジョブが権限エラーで失敗するをご覧ください。

  • URL_UNREACHABLE-UNREACHABLE_5xx: 宛先ターゲットが HTTP 5xx または 429 エラーを返します。これは、サーバーの過負荷など、一時的な状態である可能性があります。宛先ターゲットのログを確認して、問題をデバッグします。

  • URL_UNREACHABLE-UNREACHABLE_CONNECTION_RESET: 接続がピアによってリセットされました。外部サーバー側で問題がないか確認します。

  • URL_UNREACHABLE-UNREACHABLE_ERROR: ネットワーク エラーを示します。ターゲット URL が正しいかどうか、ファイアウォール ルールがアクセスをブロックしていないかどうかを確認します。

セキュアな境界を使用する場合にサポートされないターゲット

Cloud Scheduler が VPC Service Controls 境界の制限付きサービスである場合、サポートされていないターゲットを含むジョブを作成または更新しようとすると、TARGET_TYPE_NOT_PERMITTED_FOR_VPC エラーコードで失敗します。詳細については、VPC Service Controls で cron ジョブを保護するをご覧ください。

ジョブ実行の問題

Cloud Scheduler ジョブは、指定した時刻または一定間隔で実行されます。ジョブの実行中に次の問題が発生することがあります。

以前に動作していたジョブが実行を停止する

この問題は、Cloud Scheduler API が無効になっているために、以前に正常に実行された Cloud Scheduler ジョブが実行を停止した場合に発生します。API が無効になった時刻を確認するには、次の条件で監査ログをクエリします。

resource.type="audited_resource" AND
protoPayload.serviceName="cloudscheduler.googleapis.com" AND
operation.producer="serviceusage.googleapis.com" AND
protoPayload.authorizationInfo.permission="serviceusage.services.disable"

この問題を解決するには、Cloud Scheduler API を有効にします。

後続のジョブ実行が開始されない

この問題は、ジョブがまだ実行中であるか、ターゲットからのレスポンスを待機している場合に発生します。ジョブの他のスケジュールされた実行は、現在の実行が終了するかタイムアウトするまでスキップされます。

ログエントリで、最新の type.googleapis.com/google.cloud.scheduler.logging.AttemptStarted エントリと、それに対応する type.googleapis.com/google.cloud.scheduler.logging.AttemptFinished エントリを見つけます。AttemptFinished エントリがない場合、またはジョブの次のスケジュールされた実行後に表示される場合、他の保留中の実行はブロックされ、開始されません。ジョブのスケジュールによっては、複数のジョブ実行が開始されないことがあります。さらに調査するには、ジョブの宛先ターゲットのタイムアウトを確認し、ターゲットで問題が発生していないかどうかを確認します。

夏時間によりジョブの実行が不規則になる

Google Cloud コンソールを使用して Cloud Scheduler ジョブを作成する場合は、タイムゾーンを指定する必要があります。Google Cloud CLI を使用する場合は、--time-zone フラグを使用してタイムゾーンを指定できます。指定しない場合、デフォルトのタイムゾーンは協定世界時(UTC)になります。

この問題は、ジョブが UTC 以外のタイムゾーンで構成され、夏時間(DST)の変更により実行が不規則になる場合に発生します。これは想定された挙動です。

ジョブで正確な周期が必要な場合は、DST を使用しないタイムゾーンを選択します。この問題を完全に回避するには、UTC タイムゾーンを使用するようにジョブ スケジュールを構成します。

詳細については、cron ジョブの形式とタイムゾーンをご覧ください。

CMEK に関する問題

顧客管理の暗号鍵(CMEK)を使用して Cloud Scheduler を保護できます。鍵は Cloud Key Management Service(Cloud KMS)で作成され、管理されます。

Cloud Scheduler で Cloud KMS を使用すると、エラーが発生する可能性があります。次の表にさまざまな問題とその解決方法を示します。

問題 説明
権限 cloudkms.cryptoKeyVersions.useToEncrypt が拒否されました

指定された Cloud KMS 鍵が存在しないか、権限が適切に構成されていません。

解決方法:

鍵バージョンが有効になっていない

指定された Cloud KMS 鍵バージョンが無効になっています。

解決方法: Cloud KMS 鍵バージョンを再度有効にします。

キーリングのリージョンが、保護対象のリソースと一致しません

指定された Cloud KMS キーリング リージョンが、保護された Cloud Scheduler リージョンと異なります。

解決方法: Cloud Scheduler リージョンと同じリージョンの Cloud KMS キーリングを使用します。キーリングは別のプロジェクトに配置できます。詳細については、Cloud KMS のロケーションと Cloud Scheduler のロケーションをご覧ください。

プロジェクトが Cloud Scheduler の CMEK と互換性がない

CMEK を有効にすると、FAILED_PRECONDITION エラーが発生し、Your project is currently not compatible with CMEK in Cloud Scheduler というメッセージが表示されます。このエラーは、プロジェクト内の既存の Cloud Scheduler ジョブが CMEK をサポートするように移行されていない場合に発生します。たとえば、サービス エージェントの権限がない場合や、無効な Pub/Sub トピック名を持つレガシージョブがある場合、移行が妨げられる可能性があります。

解決方法:

  1. プロジェクトの権限またはジョブ構成の問題を確認して修正します。
  2. 権限またはジョブ構成の問題を解決したら、 Google Cloud コンソールでサポート リクエストを開き、移行を完了して、プロジェクトで CMEK を有効にできるようにします。権限またはジョブ構成を修正するだけでは、移行が完了するまでエラーは解消されません。

次のステップ

Cloud Scheduler のドキュメントで問題の解決策が見つからない場合は、次のオプションを検討してください。

詳細については、Cloud Scheduler のサポートをご覧ください。