使用用户代管式服务账号配置日志接收器

本页面介绍如何通过创建配置了用户代管式服务帐号的接收器来路由日志。默认情况下，Logging 将 Logging 服务帐号用于资源中的所有接收器。但是，如果您的日志接收器位于不同的项目中，则您可以创建和管理自己的用户代管式服务帐号，从而从包含您的用户管理的服务帐号的项目集中管理 Identity and Access Management 权限。

仅当接收器目标位置是日志存储桶或 Google Cloud 项目时，您才能创建使用用户代管式服务帐号的接收器。本文档中的示例说明了如何设置使用用户代管式服务帐号（其中目标位置为日志存储桶）的接收器。

准备工作

如需使用本指南中的命令行示例，请安装并配置 Google Cloud CLI。
确保您拥有用户代管式服务帐号。如需了解如何创建服务帐号，请参阅创建服务帐号。
如需使用本文档中的命令，请确定以下值：
- DESTINATION_PROJECT_ID：包含日志存储桶的项目的 ID。
- CUSTOM_SA_PROJECT_ID：包含您的用户代管式服务帐号的项目的 ID。
- SINK_PROJECT_ID：您计划在其中创建日志接收器的项目的 ID。
- CUSTOM_SA：用户代管式服务帐号。如需了解如何创建服务帐号，请参阅创建服务帐号。
  
  用户代管式服务帐号的格式如下所示：
  
  SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com
- LOGGING_SA：默认的 Logging 服务帐号。如需获取此电子邮件，请运行以下命令：
```
   gcloud logging settings describe --project=SINK_PROJECT_ID
```
  输出结果包含有关您的服务帐号的以下信息：
  
  loggingServiceAccountId: serviceAccount:service-123456789012@gcp-sa-logging.iam.gserviceaccount.com
- BUCKET_NAME：日志存储桶的名称。
  
  日志存储桶的接收器目标位置路径如下所示：
  
  logging.googleapis.com/projects/DESTINATION_PROJECT_ID/locations/LOCATION/buckets/BUCKET_NAME
在包含用户代管式服务帐号的项目中，确保未强制执行组织政策布尔值限制条件 iam.disableCrossProjectServiceAccountUsage。默认情况下，系统会强制执行此限制条件。如需停用此限制条件以便将服务帐号附加到另一个项目中的资源，请运行以下命令：
```
  gcloud resource-manager org-policies disable-enforce \
  iam.disableCrossProjectServiceAccountUsage \
  --project=CUSTOM_SA_PROJECT_ID
```
如需详细了解如何跨项目启用服务帐号，请参阅启用跨项目关联服务帐号。

授予 IAM 角色

本部分介绍创建使用用户代管式服务帐号的接收器的前提条件。

在包含日志存储桶（日志接收器目标位置）的项目中，执行以下操作：

向用户代管式服务帐号授予 Logs Bucket Writer 角色 (roles/logging.bucketWriter)。此角色允许用户代管式服务帐号将日志写入日志存储桶：
```
 gcloud projects add-iam-policy-binding DESTINATION_PROJECT_ID \
 --member="serviceAccount:CUSTOM_SA" \
 --role="roles/logging.bucketWriter"
```

在您要创建使用用户代管式服务帐号的日志接收器的 Google Cloud 项目中，执行以下操作：

向用户代管式服务帐号上的 Cloud Logging 服务帐号授予 Service Account Token Creator 角色 (roles/iam.serviceAccountTokenCreator)：
```
  gcloud iam service-accounts add-iam-policy-binding CUSTOM_SA \
  --project=CUSTOM_SA_PROJECT_ID \
  --member="serviceAccount:LOGGING_SA" \
  --role="roles/iam.serviceAccountTokenCreator"
```
上面的命令允许 Logging 服务帐号使用 Service Account Token Creator 角色 (roles/iam.serviceAccountTokenCreator) 模拟用户代管式服务帐号。

服务帐号模拟涉及两个主帐号：一个是无权访问资源的服务帐号，另一个是有权访问资源的具有权限的服务帐号。在这种情况下，用户代管式服务帐号是具有权限的帐号，因为它可以将日志写入目标项目中的日志存储桶。Logging 服务帐号有权路由日志。

如需详细了解 Service Account Token Creator 角色，请参阅管理和模拟服务帐号的角色：Service Account Token Creator 角色。

如需详细了解服务帐号模拟，请参阅服务帐号模拟简介。
将 Service Account User 角色 (roles/iam.serviceAccountUser) 授予创建日志接收器的主帐号。具体来说，主帐号需要服务帐号的 iam.serviceAccounts.actAs 权限：
```
 gcloud iam service-accounts add-iam-policy-binding CUSTOM_SA \
 --member 'user:user@example.com' \
 --role "roles/iam.serviceAccountUser"
```
上一个命令允许用户以用户管理的服务帐号的身份执行操作。

如需详细了解 Service Account User 角色，请参阅用于管理和模拟服务帐号的角色：Service Account User 角色。

创建使用用户代管式服务账号的日志接收器

gcloud

如需使用用户代管式服务帐号创建接收器，请将变量替换为您自己的信息，然后运行带有 --custom-writer-identity 标志的 gcloud logging sinks create 命令：

    gcloud logging sinks create SINK_NAME logging.googleapis.com/projects/DESTINATION_PROJECT_ID/locations/LOCATION/buckets/BUCKET_NAME \
    --custom-writer-identity=serviceAccount:CUSTOM_SA \
    --project=SINK_PROJECT_ID

API

如需在 Google Cloud 项目中创建日志接收器，请在 Logging API 中使用 projects.sinks.create。在 LogSink 对象中，传递 customWriterIdentity 参数，并在方法请求正文中提供相应的必需值：
- name：接收器的标识符。请注意，创建接收器后，您无法重命名接收器，但可以删除它并创建新的接收器。
- destination：您希望将日志路由到的日志存储桶。目标路径采用以下格式：
```
logging.googleapis.com/projects/DESTINATION_PROJECT_ID/locations/LOCATION/buckets/BUCKET_NAME
```
调用 projects.sinks.create 以创建接收器。

如需详细了解如何使用 Logging API 创建接收器，请参阅 LogSink 参考文档。

验证接收器是否正在路由日志

在本部分中，您将使用 gcloud CLI 写入和读取日志条目，以验证接收器是否正确路由日志。

如需验证您的接收器是否正确路由日志，请执行以下操作：

将变量替换为您自己的信息，并使用 gcloud logging write 命令编写示例日志条目：
```
gcloud logging write LOG_NAME "Test log entry" --project=SINK_PROJECT_ID
```
上述命令会返回以下消息：

Created log entry.

如需读取您刚刚编写的日志条目，请运行以下命令：

gcloud logging read 'textPayload="Test log entry"' \
--bucket=BUCKET_NAME --location=LOCATION \
--view=_AllLogs --project=SINK_PROJECT_ID

后续步骤

如需了解如何将日志路由到支持的目标位置，请参阅将日志路由到支持的目标位置。
如需简要了解 Logging 如何路由和存储日志，请参阅路由和存储概览。
如果您在使用接收器路由日志时遇到问题，请参阅路由日志问题排查。
如需了解如何在目标位置查看路由日志，以及日志的格式和整理方式，请参阅查看接收器目标位置中的日志。