排查 Cloud Scheduler 问题

Cloud Scheduler 会在每次作业执行的开始和结束时发布日志,以便您诊断和解决作业问题。您可以检索、查看和分析特定作业的执行和审核日志。如需了解详情,请参阅查看日志。

默认情况下,当 Cloud Scheduler 作业未收到来自其目标服务(作业请求处理程序)的确认时,Cloud Scheduler 会认为作业失败,并根据您配置的指数退避算法重试该作业。

如需了解影响 Google Cloud 服务的突发事件,请参阅 Google Cloud Service Health 信息中心和为 Cloud Scheduler 报告的所有突发事件。

作业因下游服务问题而失败

作业失败可能是由于 Cloud Scheduler 目标下游服务(例如 Cloud Run)中的问题,而不是 Cloud Scheduler 本身的问题。如果满足以下条件,则可能是下游服务问题:

  • 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 Service Agent (roles/cloudscheduler.serviceAgent) 角色。如果没有此角色,Cloud Scheduler 作业会失败。您可以手动向 Cloud Scheduler 服务代理授予该角色。仅当您在 2019 年 3 月 19 日之前启用了 Cloud Scheduler API,或者您移除了 Cloud Scheduler Service Agent 角色时,才需要手动授予。如需了解详情,请参阅授予 Cloud Scheduler Service Agent 角色。

  • 验证服务账号权限:确保附加到作业的服务账号具有调用目标服务的正确权限和范围。这包括目标位于其他项目或目标是中介服务的最终目标的情况。如果目标位于 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 控制台中,前往 Logs Explorer 页面:

      前往 Logs Explorer

      如果您使用搜索栏查找此页面,请选择子标题为 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 只能调用受支持的私有端点,例如 VPC Service Controls 边界内的 Cloud Run、Cloud Run functions 和 Google Cloud API。检查目标服务的入站流量设置(例如,请参阅限制 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 密钥,请确保标头名称与目标服务预期的名称(例如 x-api-key 或 X-Goog-Api-Key,而不是 api_key)一致。如需了解详情,请参阅向 Cloud Scheduler 进行身份验证和对 HTTP 目标使用身份验证。

  • URL_ERROR-ERROR_DNS:表示网址提取失败,因为无法使用域名系统 (DNS) 解析主机名,例如,主机名不存在或没有关联的 IP 地址。出错提示可能包含文本 Original HTTP response code number = 0。检查主机名的有效性,并在调用专用端点时,确保 Cloud Scheduler 支持该端点并检查其入站流量设置。

  • URL_ERROR-ERROR_NOT_FOUND:Web 服务器返回 HTTP 404 Not Found 错误。请检查目标网址是否正确以及资源是否存在。

  • 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:表示网络连接错误。检查目标网址是否正确,以及是否有任何防火墙规则阻止访问。

使用安全边界时不支持的目标

当 Cloud Scheduler 是 VPC Service Controls 边界中的受限服务时,任何尝试创建或更新具有不受支持的目标的作业都会失败,并显示 TARGET_TYPE_NOT_PERMITTED_FOR_VPC 错误代码。如需了解详情,请参阅使用 VPC Service Controls 保护 cron 作业。

作业执行问题

Cloud Scheduler 作业会在指定时间或按固定时间间隔执行。作业执行期间可能会出现以下问题。

之前可正常运行的作业停止执行

当之前成功运行的 Cloud Scheduler 作业因 Cloud Scheduler API 被停用而停止执行时,就会出现此问题。您可以通过查询审核日志来确认 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) 更改而导致其执行变得不规律,就会出现此问题。这是预期行为。

如果您的作业需要精确的节奏,请选择不采用夏令时的时区。为完全避免此问题,请将作业时间表配置为使用世界协调时间 (UTC) 时区。

如需了解详情,请参阅 Cron 作业格式和时区。

CMEK 问题

您可以使用客户管理的加密密钥 (CMEK) 来保护 Cloud Scheduler。密钥通过 Cloud Key Management Service (Cloud KMS) 创建和管理。

将 Cloud KMS 与 Cloud Scheduler 搭配使用时,您可能会遇到错误。下表介绍了不同的问题以及如何解决这些问题。

问题 说明
权限 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. 查看并修复项目中的任何权限或作业配置问题:
    • 验证 Cloud Scheduler 服务代理是否具有项目的 Cloud Scheduler Service Agent (roles/cloudscheduler.serviceAgent) 角色。此角色包含项目中 Pub/Sub 主题的 pubsub.topics.publish 权限。如需查看相关说明,请参阅授予 Cloud Scheduler Service Agent 角色。
    • 如果未在项目上授予 roles/cloudscheduler.serviceAgent 或该角色受到限制,请验证服务代理在每个目标主题上是否具有 Pub/Sub Publisher (roles/pubsub.publisher) 角色。
    • 检查是否存在主题名称无效的旧版 Pub/Sub 目标作业,并更新或删除这些作业。主题名称必须在与作业相同的项目中使用 projects/PROJECT_ID/topics/TOPIC_ID 格式。如需了解主题命名规则,请参阅主题、订阅、架构或快照命名指南。
  2. 解决所有权限或作业配置问题后,请在 Google Cloud 控制台中提交支持请求以完成迁移,以便为项目启用 CMEK。在迁移完成之前,仅修复权限或作业配置无法清除错误。

后续步骤

如果您在 Cloud Scheduler 文档中找不到问题的解决方案,请考虑以下选项:

如需了解详情,请参阅 Cloud Scheduler 支持。