问题排查

本页面介绍了如何解决使用 Workflows 时可能遇到的问题。

如需了解详情，请参阅monitoring和调试 Workflows。

部署错误

部署工作流后，Workflows 会检查源代码是否正确无误，并符合语言语法。 如果发现错误，Workflows 会返回该错误。最常见的部署错误类型包括：

• 引用未定义的变量、步骤或子工作流
• 语法不正确
  • 缩进不正确
  • {、}、"、- 或 : 缺失或无关紧要

例如，以下源代码抛出部署错误，因为返回语句引用了未定义的变量 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

如需解决此问题，请修改工作流的源代码。在这种情况下，请参阅 varA 而不是 varC。

HTTP 403 服务帐号权限错误

当 HTTP 服务器返回错误代码 403 时，您的工作流执行将失败。例如：

Permission 'iam.serviceaccounts.actAs' denied on service
account [e-mail] (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 服务帐号相关联。如需解决此问题，您必须向服务帐号授予一个或多个 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}']

结果符合预期，结果是一个包含两个值的列表。

客户管理的加密密钥 (CMEK)

将 Cloud KMS 与 Workflows 搭配使用时可能会遇到错误。下表介绍了各种问题以及解决方法。

问题	说明
权限“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 连接器时未找到请求的实体

如果 HTTP 服务器在尝试使用连接器方法 googleapis.run.v1.namespaces.jobs.create 时返回错误代码 404，您的工作流执行将失败。

此方法要求您指定 HTTP 端点的位置。例如 us-central1 或 asia-southeast1。如果您未指定位置，则系统会使用全球端点 https://run.googleapis.com；但是，此位置仅支持 list 方法。

如需解决此问题，请确保在调用连接器时指定 location 参数。如需了解 Cloud Run Admin API 位置选项，请参阅服务端点。

资源限制

如果遇到资源限制或错误（例如 ResourceLimitError、MemoryLimitExceededError 或 ResultSizeLimitExceededError），可以通过清除变量释放内存。例如，您可能希望释放后续步骤所需的内存。或者，某些通话的结果可能与您并不在意，您可以完全忽略这些结果。

YAML 缩进

YAML 缩进有意义，每个缩进级别应至少有两个空格。缩进不足可能会导致错误，新级别应该是上一行文本开头起的至少两个空格。

例如，以下代码错误地指定一个列表项，其中包含具有 stepName 和 call 项的地图：

- stepName:
  call: sys.log

相反，您应在下一行缩进两个空格，以将 call 嵌套在 stepName 中：

- stepName:
    call: sys.log

请确保使用空格而非制表符来缩进行。

后续步骤

• Workflows 的已知问题