存储和查看构建日志

运行构建时，Cloud Build 会收集并存储构建日志。本页面介绍了如何存储、查看和删除构建日志。

选择将构建日志发送到何处

您可以配置 Cloud Build，以将构建日志发送到 Cloud Storage 中的存储桶、Cloud Logging 中的存储桶，或同时发送到这两个存储桶。

• 如果您想控制所存储 build 日志的保留期限，请将其发送到 Cloud Logging。Cloud Logging 还提供了更多选项，用于在存储桶中搜索特定 build 日志。

• 在某些情况下，构建日志生成和 Logging 接收构建日志之间存在延迟。将构建日志发送到 Cloud Storage 中的存储桶可能会缩短延迟时间。

Cloud Storage 和 Logging 都允许您将日志存储在 Google 创建的默认存储桶中，也可以存储在用户创建的自定义存储桶中。默认存储桶允许您查看存储在存储桶中的日志，但不允许您更改存储桶的任何内容。如果您需要完全控制用于存储构建日志的存储桶，请将日志发送到用户创建的存储桶。

将 build 日志存储在默认存储分区中

Cloud Logging 和 Cloud Storage 都有默认存储分区，您可以在其中存储构建日志。这些存储分区由 Google 创建和拥有，可以接收来自多个区域的日志。如需将 build 日志发送到上述某个存储分区，请使用以下某个值配置 build 配置文件的 LoggingMode：

• GCS_ONLY：日志存储在默认的 Cloud Storage 存储桶中。

• CLOUD_LOGGING_ONLY：日志存储在默认的 Logging 存储桶中。

• LEGACY：日志存储在两个默认存储分区中。

默认的 Logging 存储桶对存储的日志采用 30 天的保留政策。如需为存储在 Logging 中的 build 日志设置自定义保留政策，请将 build 日志存储在自定义存储桶中。

默认 Cloud Storage 存储桶没有保留政策。

将构建日志存储在用户自有且特定于区域的 Cloud Storage 存储桶中

如果您将构建日志发送到默认的 Cloud Storage 存储桶，Cloud Build 会将它们存储在 Google 指定的区域中，该区域可能与您运行构建的位置不同。不过，您也可以配置构建，以便 Cloud Build 将构建日志发送到您在运行构建的同一区域中拥有的 Cloud Storage 存储桶。此配置可让您更好地控制 build 日志数据的位置，从而帮助您遵守数据驻留要求。

授予 IAM 权限：

如果您的 Cloud Storage 存储桶与 Cloud Build 位于同一 Google Cloud 项目，并且您使用的是 Cloud Build 旧版服务账号，则该服务账号默认具有必要的 IAM 权限。您无需授予任何其他权限。否则，请执行以下操作：

如需获得在用户自有且特定于区域的存储桶中存储 build 日志所需的权限，请让您的管理员为您授予用于 build 的服务账号的 Storage Admin (roles/storage.admin) IAM 角色。 如需详细了解如何授予角色，请参阅管理对项目、文件夹和组织的访问权限。

您也可以通过自定义角色或其他预定义角色来获取所需的权限。

配置特定于区域的 Cloud Storage 存储桶：

1. 在构建配置文件中，添加 defaultLogsBucketBehavior 选项并将其值设置为 REGIONAL_USER_OWNED_BUCKET：

   YAML

   steps:
   - name: 'gcr.io/cloud-builders/docker'
     args: [ 'build', '-t', 'us-central1-docker.pkg.dev/myproject/myrepo/myimage', '.' ]
   options:
     defaultLogsBucketBehavior: REGIONAL_USER_OWNED_BUCKET
   

   JSON

   {
     "steps": [
       {
         "name": "gcr.io/cloud-builders/docker",
         "args": [
           "build",
           "-t",
           "us-central1-docker.pkg.dev/myproject/myrepo/myimage",
           "."
         ]
       }
       ],
       "options": {
         "defaultLogsBucketBehavior": "REGIONAL_USER_OWNED_BUCKET"
       }
   }
   

2. 使用构建配置文件来使用命令行，API 或触发器启动构建。

   运行构建时，Cloud Build 会在执行构建的区域中创建新存储桶，然后将构建日志存储在此存储桶中。只要 REGIONAL_USER_OWNED_BUCKET 处于有效状态，同一项目和区域中的后续 build 就会使用现有存储桶。此存储桶归用户所有，因此您可以像配置用户创建的存储桶一样配置它。

如果您设置了 REGIONAL_USER_OWNED_BUCKET 选项，然后在多个区域中创建 build，Cloud Build 会为您的 build 日志创建多个存储分区。

特定于区域的默认 Cloud Storage 存储分区没有保留政策。不过，您可以配置对象生命周期规则，以自动删除存储桶中的 build 日志。

将构建日志存储在用户创建的存储分区中

通过用户创建的存储分区，您可以更好地控制日志存储分区的管理和配置。

将构建日志存储在用户创建的 Cloud Logging 存储桶中

借助用户创建的 Logging 存储分区，您可以调整所存储构建日志的保留期限。如需将构建日志存储在 Logging 中用户创建的存储桶中，请执行以下操作：

授予 IAM 权限：

如需获得将 build 日志存储在用户创建的 Cloud Logging 存储桶中所需的权限，请让您的管理员为您授予项目的 Logs Configuration Writer (roles/logging.configWriter) IAM 角色。如需详细了解如何授予角色，请参阅管理对项目、文件夹和组织的访问权限。

您也可以通过自定义角色或其他预定义角色来获取所需的权限。

配置日志存储桶：

1. 创建存储桶，并为保留期限字段设置值。

2. 创建接收器，以将 build 日志路由到新存储桶：

   1. 为接收器的构建包含项过滤条件输入以下内容：

      logName = "projects/PROJECT_ID/logs/cloudbuild"
      

      请将 PROJECT-ID 替换为您的 Google Cloud 项目 ID。

   2. （可选）如需防止日志进入默认的 Logging 存储桶，请按照停止在日志存储桶中存储日志条目中的示例操作。

将构建日志存储在用户创建的 Cloud Storage 存储桶中

如需将构建日志存储在用户创建的 Cloud Storage 存储桶中，请执行以下操作：

授予 IAM 权限：

如果您的 Cloud Storage 存储桶与 Cloud Build 位于同一 Google Cloud 项目，并且您使用的是 Cloud Build 旧版服务账号，则默认情况下，Cloud Build 旧版服务账号具有必要的 IAM 权限。您无需授予任何其他权限。否则，请执行以下操作：

如需获得将构建日志存储在用户创建的 Cloud Storage 存储桶中所需的权限，请让您的管理员为您授予用于构建的服务账号的 Storage Admin (roles/storage.admin) IAM 角色。 如需详细了解如何授予角色，请参阅管理对项目、文件夹和组织的访问权限。

您也可以通过自定义角色或其他预定义角色来获取所需的权限。

配置 Cloud Storage 存储桶：

1. 在您的 Google Cloud 项目中，创建一个未设置保留政策的 Cloud Storage 存储桶，以存储构建日志。

2. 在构建配置文件中，添加一个 logsBucket 字段，其指向您为存储构建日志而创建的 Cloud Storage 存储分区。以下示例构建配置文件包含构建容器映像并将构建日志存储在名为 mylogsbucket 的存储桶中的说明：

   YAML

       steps:
       - name: 'gcr.io/cloud-builders/docker'
         args: [ 'build', '-t', 'us-east1-docker.pkg.dev/myproject/myimage', '.' ]
       logsBucket: 'gs://mylogsbucket'
       options:
         logging: GCS_ONLY
   

   JSON

       {
         "steps": [
          {
            "name": "gcr.io/cloud-builders/docker",
            "args": [
              "build",
              "-t",
              "us-east1-docker.pkg.dev/myproject/myimage",
              "."
            ]
          }
          ],
          "logsBucket": "gs://mylogsbucket",
          "options": {
            "logging": "GCS_ONLY"
          }
       }
   

3. 使用构建配置文件来使用命令行，API 或触发器启动构建。

构建完成后，Cloud Build 会将日志存储在您在构建配置文件中指定的 Cloud Storage 存储分区中。

日志设置之间的优先顺序

如果您在 logsBucket 中定义了用户创建的 Cloud Storage 存储桶，Cloud Build 会将构建日志发送到用户创建的存储桶，而不是默认的 Cloud Storage 存储桶。

如果您要向现有 build 配置文件添加 defaultLogsBucketBehavior 选项，并且之前已配置 logging 或 logsBucket 选项，那么我们建议您删除这些设置，以防止设置之间发生冲突。具体来说，如果您已配置以下内容，defaultLogsBucketBehavior 将无法正常运行：

• logging: CLOUD_LOGGING_ONLY，以便在 Cloud Logging 中存储构建日志。
• logging: NONE 即可关闭日志记录。

如果您运行的构建在构建配置文件中未设置任何日志记录选项，Cloud Build 会设置 logging: LEGACY 并将构建日志存储在默认的 Cloud Storage 存储桶中。将 defaultLogsBucketBehavior 设置为 REGIONAL_USER_OWNED_BUCKET 会替换 logging: LEGACY。

查看构建日志

如需查看 build 日志，请执行以下操作：

授予 IAM 权限：

如需获得在 Cloud Storage 或 Logging 中查看 build 日志所需的权限，请让您的管理员为您授予用于 build 的服务账号的以下 IAM 角色：

• 查看用户创建或拥有的 Cloud Storage 存储桶中的构建日志：
  • Storage Object Viewer (roles/storage.objectViewer) - 希望查看 build 日志的主账号
  • Logs View Accessor (roles/logging.viewAccessor) - 希望查看 build 日志的主账号
• 查看默认 Cloud Storage 存储桶中的构建日志： Viewer (roles/viewer) - 配置了构建的项目
• 在 Logging 中查看构建日志： Logs Viewer (roles/logging.viewer) - 希望查看构建日志的主账号

如需详细了解如何授予角色，请参阅管理对项目、文件夹和组织的访问权限。

您也可以通过自定义角色或其他预定义角色来获取所需的权限。

在 Google Cloud中查看 build 日志：

gcloud builds log build-id

在 GitHub 和 GitHub Enterprise 中查看 build 日志：

如果您使用 gcloud CLI 或 Cloud Build API 创建了 GitHub 或 GitHub Enterprise 触发器，并指定了 --include-logs-with-status 作为选项，那么您可以在 GitHub 和 GitHub Enterprise 中查看 build 日志。

如需在 GitHub 和 GitHub Enterprise 中查看 build 日志，请执行以下操作：

1. 前往与触发器关联的代码库。

2. 前往提交列表。

3. 找到您要查看相应提交的 build 日志的行。

4. 点击相应提交所在行中的结果图标。

   您会看到与提交关联的检查列表。

5. 点击要查看 build 日志的行对应的详情。

   您会看到与提交关联的摘要页面。 如果您已使用 --include-logs-with-status 标志创建触发器，则会在页面的详情部分下看到 build 日志。

删除 build 日志和 build 存储分区

如需获得删除 Cloud Storage 中的 build 日志和存储分区所需的权限，请让您的管理员为您授予用于 build 的服务账号的以下 IAM 角色：

• 删除用户创建或拥有的 Cloud Storage 存储桶中的构建日志： Storage Admin (roles/storage.admin) - 要删除构建日志的用户或服务账号
• 删除用户创建或用户拥有的 Cloud Storage 存储桶： Storage Admin (roles/storage.admin) - the user or 服务账号 deleting buckets
• 删除用户创建的日志记录存储桶： Logs Configuration Writer (roles/logging.configWriter) - 您的项目

如需详细了解如何授予角色，请参阅管理对项目、文件夹和组织的访问权限。

您也可以通过自定义角色或其他预定义角色来获取所需的权限。

如需删除用户创建或拥有的 Cloud Storage 存储桶中的构建日志，请按照 Cloud Storage 文档中删除对象中的说明进行操作。

如需删除用户创建或拥有的 Cloud Storage 存储桶，请按照 Cloud Storage 文档中删除存储分区中的说明进行操作。

如需删除用户创建的 Logging 存储桶，请按照 Logging 文档中删除存储桶中的说明进行操作。

后续步骤

• 了解 Cloud Build 创建的审核日志。
• 了解如何查看构建结果。
• 详细了解 Cloud Build IAM 权限。