問題のトラブルシューティング

このページでは、Workflows の使用時に発生する可能性のある問題を解決する方法について説明します。

詳細については、Workflows のモニタリングとデバッグをご覧ください。

デプロイエラー

ワークフローがデプロイされると、Workflows により、ソースコードにエラーがなく、言語構文と一致することが確認されます。 Workflows によりエラーが検出された場合は、エラーが返されます。最も一般的な種類のデプロイエラーは、次のとおりです。

  • 未定義の変数、ステップ、サブワークフローの参照
  • 不適切な構文
    • 不適切なインデント
    • {、}、"、-、: の欠落、または無関係なものがある

たとえば、次のソースコードはデプロイ エラーをスローします。これは、return 文で未定義の変数 varC が参照されるためです。

- step1:
    assign:
    - varA: "Hello"
    - varB: "World"
- step2:
    return: ${varC + varB}

この間違ったソースコードは、次の Google Cloud コンソールと gcloud CLI の例で使用されています。

Console

デプロイエラーが発生した場合、Workflows の [ワークフローの編集] ページのバナーにエラー メッセージが表示されます。 デプロイエラー エラー メッセージは、ソースコードの問題を報告します。可能であれば、エラーの原因を指定します。

Could not deploy workflow: failed to build: error in step step2: error
evaluating return value: symbol 'varC' is neither a variable nor a
sub-workflow name (Code: 3)

gcloud

gcloud workflows deploy コマンドを実行すると、デプロイが失敗した場合、Workflows はコマンドラインにエラー メッセージを返します。エラー メッセージは、可能であればエラーの原因を指定して、ソースコードの問題を報告します。

ERROR: (gcloud.workflows.deploy) [INVALID_ARGUMENT] failed to build:
error in step step2: error evaluating return value: symbol 'varC' is neither
a variable nor a sub-workflow name

この問題を解決するには、ワークフローのソースコードを編集します。この場合、varC ではなく varA を参照します。

HTTP 403 サービス アカウントの権限に関するエラー

HTTP サーバーがエラーコード 403 で応答した場合、ワークフローの実行が失敗しています。次に例を示します。

Permission 'iam.serviceaccounts.actAs' denied on service
account PROJECT_NUMBER-compute@developer.gserviceaccount.com (or it may not exist).

または

SERVICE_ACCOUNT does not have storage.objects.create access to the Google Cloud
Storage object. Permission 'storage.objects.create' denied on resource (or it may not exist).

すべてのワークフローは、ワークフローの作成時に IAM サービス アカウントに関連付けられます。この問題を解決するには、ワークフローの管理に必要な最小限の権限を含む 1 つ以上の IAM ロールをサービス アカウントに付与する必要があります。たとえば、ワークフローによって Cloud Logging にログが送信されるようにするには、ワークフローを実行するサービス アカウントに logging.logEntries.create 権限を含むロールが付与されていることを確認します。詳細については、Google Cloud リソースにアクセスする権限をワークフローに付与するをご覧ください。

HTTP 404 No such object エラーまたは Not found エラー

Cloud Storage コネクタを使用している場合、HTTP サーバーが 404 エラーコードで応答すると、ワークフローの実行が失敗します。次に例を示します。

HTTP server responded with error code 404
in step "read_input_file", routine "main", line: 13
{
  "body": "Not Found",
  "code": 404,
  ...
}

オブジェクト名は、パスで安全に使用できるように URL エンコードする必要があります。url_encode 関数と url_encode_plus 関数を使用すると、リクエスト URL のオブジェクト名またはクエリ文字列に該当する文字が含まれている場合に、その文字をエンコードできます。次に例を示します。

- init:
    assign:
        - source_bucket: "my-bucket"
        - file_name: "my-folder/my-file.json"
- list_objects:
    call: googleapis.storage.v1.objects.get
    args:
        bucket: ${source_bucket}
        object: ${text.url_encode(file_name)}
        alt: media
    result: r
- returnStep:
    return: ${r}

オブジェクト名を URL エンコードせず、ストレージ バケットにフォルダがある場合、リクエストは失敗します。詳細については、URL パス部分のエンコードと Cloud Storage の命名に関する考慮事項をご覧ください。

HTTP 429 Too many requests エラー

同時に実行できるアクティブなワークフロー実行には最大数があります。この割り当てが使い果たされ、実行バックログが無効になっている場合、またはバックログ実行の割り当てに達した場合、新しい実行は HTTP 429 Too many requests ステータス コードで失敗します。

実行バックログを使用すると、同時実行割り当てに達したとき、ワークフロー実行をキューに入れることができます。デフォルトでは、実行バックログは、次の例外を除いて、すべてのリクエスト（Cloud Tasks によってトリガーされたリクエストを含む）に対して有効になっています。

  • ワークフローで executions.run コネクタまたは executions.create コネクタを使用して実行を作成する場合、実行バックログはデフォルトで無効になります。実行の disableConcurrencyQuotaOverflowBuffering フィールドを明示的に false に設定することで構成できます。
  • Pub/Sub によってトリガーされる実行の場合、実行バックログは無効になり、構成できません。

詳細については、実行バックログを管理するをご覧ください。

定義したレートで Cloud Tasks キューが子ワークフローを実行できるようにして、実行速度を向上させることもできます。その場合は、明示的に実行バックログを無効にすることをおすすめします。

プロジェクト間のサービス アカウントの権限に関するエラー

プロジェクト間のサービス アカウントを使用してワークフローをデプロイするときに PERMISSION_DENIED エラーが発生した場合は、プロジェクトに iam.disableCrossProjectServiceAccountUsage ブール型制約が適用されていないことと、サービス アカウントが正しく設定されていることを確認してください。詳細については、プロジェクト間のサービス アカウントを使用してワークフローをデプロイするをご覧ください。

リソース名は RFC 1123 に準拠している必要がある

HTTP サーバーがエラーコード 400 で応答した場合、ワークフローの実行が失敗しています。次に例を示します。

"description": "must conform to RFC 1123: only lowercase, digits, hyphens,
and periods are allowed, must begin and end with letter or digit, and less
than 64 characters."

この問題を解決するには、リソース名が RFC 1123 で定義された DNS ラベル標準に従っていることと、変数を割り当てるときに文字列と式が正しく連結されていることを確認します。

たとえば、- string: hello-${world} のような変数を割り当てることはできません。代わりに、次のようにします。

YAML

  - assign_vars:
      assign:
          - string: "hello"
          - string: ${string+" "+"world"}

JSON

  [
    {
      "assign_vars": {
        "assign": [
          {
            "string": "hello"
          },
          {
            "string": "${string+" "+"world"}"
          },
        ]
      }
    }
  ]

コロンを含む式

YAML でコロンを含む式を使用すると、コロンがマッピングの定義と解釈されたときに予期しない動作が発生する可能性があります。ワークフローをデプロイして実行することはできますが、出力は想定どおりではありません。

Google Cloud コンソールを使用してワークフローを作成すると、ワークフローを Google Cloud コンソールで視覚的にレンダリングできず、次のような警告が表示される場合があります。

ワークフロー作成に関する警告

この問題を解決するには、YAML 式を単一引用符で囲みます。

推奨: '${"a: " +string(a)}'

おすすめしません ${"a: " +string(a)}

英数字以外の文字を含むマップキー

英数字以外の文字（"special!key": value の感嘆符など）を含むマップキーにアクセスする場合は、キーの名前を引用符で囲む必要があります。キーの名前が引用符で囲まれていないと、ワークフローをデプロイできません。たとえば、次のソースコードをデプロイしようとすると、token recognition error がスローされます。

- init:
    assign:
    - var:
        key:
            "special!key": bar
- returnOutput:
    return: '${"foo" + var.key[special!key]}'

この問題を解決するには、代わりに次のコードを使用して出力を返します。

'${"foo" + var.key["special!key"]}'

リスト内の複数の式

次の反復処理の範囲の例のようなリスト内で複数の式を使用することは、有効な YAML ではありません。

[${rangeStart}, ${rangeEnd}])

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

  • 式内にリストを配置します。

    ${[rangeStart, rangeEnd]}

  • 各式を単一引用符で囲みます。

    ['${rangeStart}', '${rangeEnd}']

結果は、想定されるとおり 2 つの値のリストです。

顧客管理の暗号鍵（CMEK）

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

問題 説明
権限 cloudkms.cryptoKeyVersions.useToEncrypt が拒否されました 指定された Cloud KMS 鍵が存在しないか、権限が適切に構成されていません。

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

解決方法: Cloud KMS 鍵バージョンを再度有効にします。
キーリングのリージョンが保護対象のリソースと一致しない 指定された KMS キーリング リージョンがワークフローのリージョンとは異なります。

解決方法: Cloud KMS キーリングと同じリージョンの保護されたワークフローを使用します（異なるプロジェクトに存在することもあります）。詳細については、Cloud KMS のロケーションと Workflows のロケーションをご覧ください。
Cloud KMS の割り当て上限を超えている Cloud KMS リクエストの割り当て上限に達しました。

解決方法: Cloud KMS の呼び出し数を制限するか、割り当ての上限を増やします。詳細については、Cloud KMS の割り当てをご覧ください。

Cloud Run コネクタを使用しているときに、リクエストされたエンティティが見つからない

コネクタ メソッド googleapis.run.v1.namespaces.jobs.create を使用しようとしたときに HTTP サーバーがエラーコード 404 で応答した場合、ワークフローの実行が失敗しています。

この方法では、HTTP エンドポイントの場所を指定する必要があります。たとえば、us-central1 や、asia-southeast1 です。ロケーションを指定しない場合は、グローバル エンドポイント https://run.googleapis.com が使用されます。ただし、このロケーションでは list メソッドのみがサポートされます。

この問題を解決するには、コネクタを呼び出すときに location 引数を指定してください。Cloud Run Admin API のロケーション オプションについては、サービス エンドポイントをご覧ください。

リソースの上限

リソース上限、または ResourceLimitError、MemoryLimitExceededError、ResultSizeLimitExceededError などのエラーが発生した場合は、変数をクリアしてメモリを開放できます。 たとえば、後続のステップに必要なメモリを解放できます。また、懸念する点がない結果で呼び出しを行い、それらの結果をすべて省略することもできます。

YAML インデント

YAML のインデントには意味があります。インデント レベルごとに少なくとも 2 つのスペースが必要です。インデントの不足でエラーが発生する可能性があります。新しいレベルの場合は、前の行のテキストの先頭から 2 個以上のスペースを挿入する必要があります。

たとえば、次の例では、stepName アイテムと call アイテムを持つマップを含むリストアイテムが誤って指定されています。

- stepName:
  call: sys.log

代わりに、次の行を 2 つのスペースでインデントして、call を stepName 内にネストする必要があります。

- stepName:
    call: sys.log

行のインデントには、タブ文字ではなくスペースを使用してください。

次のステップ