Configure log sinks with user-managed service accounts

This page describes how to route logs by creating sinks that are configured with user-managed service accounts. By default, Logging uses a Logging service account for all sinks in a resource. However, if your log sinks are in different projects, then you can create and manage your own user-managed service account, which lets you centrally manage Identity and Access Management permissions from the project that contains your user-managed service account.

You can only create a sink that uses a user-managed service account when the sink destination is a log bucket or a Google Cloud project. The example in this document illustrates how to set up a sink that uses a user-managed service account where the destination is a log bucket.

Before you begin

To use the command-line examples in this guide, install and configure the Google Cloud CLI.
Ensure that you have a user-managed service account. For information about how to create a service account, see Create service accounts.
To use the commands in this document, identify the following values:
- DESTINATION_PROJECT_ID: The project ID of the project that contains your log bucket.
- CUSTOM_SA_PROJECT_ID: The project ID of the project that contains your user-managed service account.
- SINK_PROJECT_ID: The project ID of the project where you plan to create the log sink.
- CUSTOM_SA: Your user-managed service account. For information about how to create service accounts, see Create service accounts.
  
  The format for a user-managed service account looks like the following:
  
  SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com
- LOGGING_SA: The default Logging service account. To get this email, run the following command:
```
   gcloud logging settings describe --project=SINK_PROJECT_ID
```
  The output includes the following information about your service account:
  
  loggingServiceAccountId: serviceAccount:service-123456789012@gcp-sa-logging.iam.gserviceaccount.com
- BUCKET_NAME: The name of your log bucket.
  
  The sink destination path for a log bucket looks like the following:
  
  logging.googleapis.com/projects/DESTINATION_PROJECT_ID/locations/LOCATION/buckets/BUCKET_NAME
In the project that contains your user-managed service account, ensure the organization policy boolean constraint iam.disableCrossProjectServiceAccountUsage isn't enforced. By default, this constraint is enforced. To disable this constraint so that you can attach a service account to a resource in another project, run the following command:
```
  gcloud resource-manager org-policies disable-enforce \
  iam.disableCrossProjectServiceAccountUsage \
  --project=CUSTOM_SA_PROJECT_ID
```
For more information about enabling service accounts across projects, see Enable service accounts to be attached across projects.

Grant IAM roles

This section describes the prerequisites for creating a sink that uses a user-managed service account.

In the project that contains the log bucket that is the destination of the log sinks, do the following:

Grant the Logs Bucket Writer role (roles/logging.bucketWriter) to the user-managed service account. This role lets the user-managed service account write logs to the log bucket:
```
 gcloud projects add-iam-policy-binding DESTINATION_PROJECT_ID \
 --member="serviceAccount:CUSTOM_SA" \
 --role="roles/logging.bucketWriter"
```

In the Google Cloud project that you want to create log sinks that use the user-managed service account, do the following:

Grant the Service Account Token Creator role (roles/iam.serviceAccountTokenCreator) to the Cloud Logging service account on the user-managed service account:
```
  gcloud iam service-accounts add-iam-policy-binding CUSTOM_SA \
  --project=CUSTOM_SA_PROJECT_ID \
  --member="serviceAccount:LOGGING_SA" \
  --role="roles/iam.serviceAccountTokenCreator"
```
The previous command lets the Logging service account impersonate the user-managed service account by using the Service Account Token Creator role (roles/iam.serviceAccountTokenCreator).

Service account impersonation involves two principals: the service account that lacks permissions to access a resource, and the privilege-bearing service account that has the permissions to access a resource. In this case, the user-managed service account is the privilege-bearing account because it has the ability to write logs to a log bucket in the destination project. The Logging service account has the privileges to route logs.

For more information about the Service Account Token Creator role, see Roles for managing and impersonating service accounts: Service Account Token Creator Role.

For more information about service account impersonation, see About service account impersonation.
Grant the Service Account User role (roles/iam.serviceAccountUser) to the principal that is creating the log sinks. Specifically, a principal needs the iam.serviceAccounts.actAs permission on the service account:
```
 gcloud iam service-accounts add-iam-policy-binding CUSTOM_SA \
 --member 'user:user@example.com' \
 --role "roles/iam.serviceAccountUser"
```
The previous command lets a user run operations as the user-managed service account.

For more information about the Service Account User role, see Roles for managing and impersonating service accounts: Service Account User role.

Create a log sink that uses a user-managed service account

gcloud

To create a sink with a user-managed service account, replace the variables with your own information, and run the gcloud logging sinks create command with the --custom-writer-identity flag:

    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

To create a log sink in your Google Cloud project, use projects.sinks.create in the Logging API. In the LogSink object, pass the customWriterIdentity parameter, and provide the appropriate required values in the method request body:
- name: An identifier for the sink. Note that after you create the sink, you can't rename the sink, but you can delete it and create a new sink.
- destination: The log bucket where you want your logs routed. The destination path has the following format:
```
logging.googleapis.com/projects/DESTINATION_PROJECT_ID/locations/LOCATION/buckets/BUCKET_NAME
```
Call projects.sinks.create to create the sink.

For more information about creating sinks using the Logging API, see the LogSink reference documentation.

Verify that your sink is routing logs

In this section, you use the gcloud CLI to write and read a log entry to verify that your sink is routing logs correctly.

To verify that your sink is routing logs correctly, do the following:

Replace the variables with your own information and write a sample log entry by using the gcloud logging write command:
```
gcloud logging write LOG_NAME "Test log entry" --project=SINK_PROJECT_ID
```
The previous command returns the following message:

Created log entry.

To read the log entry you just wrote, run the following command:

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

What's next

To learn about routing your logs to supported destinations, see Route logs to supported destinations.
For an overview about how Logging routes and stores your logs, see Routing and storage overview.
If you encounter issues as you use sinks to route logs, see Troubleshoot routing logs.
To learn how to view your routed logs in their destinations, as well as how the logs are formatted and organized, see View logs in sink destinations.