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

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

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

デプロイエラー

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

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

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

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

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

コンソール

デプロイエラーが発生した場合、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 リソースにアクセスする権限をワークフローに付与するをご覧ください。

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

プロジェクト間のサービスアカウントを使用してワークフローをデプロイするときに 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 鍵が存在することを確認します。指定したキーリングの鍵を一覧表示し、使用状況を確認します。 Workflows サービスエージェントに鍵へのアクセス権があり、`cloudkms.cryptoKeyEncrypterDecrypter` ロールが付与されていることを確認します。
鍵バージョンが有効になっていません	指定された 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 スペース分インデントして、stepName 内に call をネストする必要があります。

- stepName:
    call: sys.log

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

次のステップ

Workflows の既知の問題