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

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

Before you begin

1. In the Google Cloud console, activate Cloud Shell.

   Activate Cloud Shell

   At the bottom of the Google Cloud console, aCloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.

2. Ensure that you have a user-managed service account and then set thefollowing variables to appropriate values for youruser-managed service account:

   • CUSTOM_SA_PROJECT_ID:The project ID of the project that contains your user-managed serviceaccount.

   • CUSTOM_SA: The emailaddress of your user-managed service account.

   For information abouthow to create a service account, seeCreate service accounts.

3. Ensure that you have a log bucket that can serve as the destination ofa log sink, and then set the following variables to valuesthat are appropriate for your log bucket.If necessary,create a log bucket:

   • LOG_BUCKET_PROJECT_ID:The project ID of the project containing your log bucket.

   • LOCATION: The locationof your log bucket.

   • BUCKET_NAME: The nameof your log bucket.

4. Identify the name of the Logging service account whichexists in the project in which you plan to create the log sink, and thenset the following variables to their appropriate values:

   • SINK_PROJECT_ID:The project ID of the project where you plan to create the log sink.

   • LOGGING_SA: The emailaddress of the default Logging service account.To get this address, run the following command:

     gcloudloggingsettingsdescribe--project=SINK_PROJECT_ID

     In the response, the line beginning withloggingServiceAccountId liststhe email address of your service account.

5. In the project containing your user-managed service account, ensure theorganization policy boolean constraintiam.disableCrossProjectServiceAccountUsage isn't enforced. By default,this constraint is enforced. To disable this constraint so that you canattach a service account to aresource in another project, run the following command:

   gcloudresource-managerorg-policiesdisable-enforce\iam.disableCrossProjectServiceAccountUsage\--project=CUSTOM_SA_PROJECT_ID

   For more information about enabling service accounts across projects, seeEnable service accounts to be attached across projects.

Grant IAM roles

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

Let user-managed service account write log entries to the sink destination

Give the user-managed service account the permissions it needs towrite log entries to the destination of the sink that you will create ina subsequent step. The destination of the sink will be a log bucketstored in the project namedLOG_BUCKET_PROJECT_ID.

To give the required permissions to the user-managed service account, grantit the Logs Bucket Writer role (roles/logging.bucketWriter) on the projectcontaining the log bucket:

gcloudprojectsadd-iam-policy-bindingLOG_BUCKET_PROJECT_ID\--member='serviceAccount:CUSTOM_SA'\--role='roles/logging.bucketWriter'

For more information about the previous command, seegcloud projects add-iam-policy-binding.

Configure service account impersonation

Configure the default Cloud Logging service account,LOGGING_SA,so that it can impersonate the user-managed service account,CUSTOM_SA. The default Cloud Logging service accountexists in the Google Cloud project that youwant to create log sinks that use the user-managed service account.

To configure service account impersonation, grant theService Account Token Creator role(roles/iam.serviceAccountTokenCreator) to the Cloud Logging serviceaccount on the user-managed service account:

gcloudiamservice-accountsadd-iam-policy-bindingCUSTOM_SA\--project=CUSTOM_SA_PROJECT_ID\--member='serviceAccount:LOGGING_SA'\--role='roles/iam.serviceAccountTokenCreator'

Service account impersonation involves two principals: the service accountthat lacks permissions to access a resource, and the privilege-bearingservice account that has the permissions to access a resource. In thiscase, the user-managed service account is the privilege-bearing accountbecause it has the ability to write log entries to the sink destination,which is a log bucket in the project namedLOG_BUCKET_PROJECT_ID.The Logging service account has theprivileges to route log entries.

For more information about the Service Account Token Creator role,seeService Account Token Creator Role.

For more information about service account impersonation, seeAbout service accountimpersonation.

Let principal run operations as the user-managed service account

Give the principal who will create the sink the permissions they need torun operations as the user-managed service account.

To give the required permissions, grant the principal theService Account User role (roles/iam.serviceAccountUser)on the Google Cloud project that stores theuser-managed service account,CUSTOM_SA_PROJECT_ID.

Before you run the following command, make the following replacements:

• PRINCIPAL: An identifier for the principal that you want to grant the role to. Principal identifiers usually have the following form:PRINCIPAL-TYPE:ID. For example,user:my-user@example.com. For a full list of the formats thatPRINCIPAL can have, seePrincipal identifiers.

Execute thegcloud iam service-accounts add-iam-policy-bindingcommand:

gcloudiamservice-accountsadd-iam-policy-bindingCUSTOM_SA\--project=CUSTOM_SA_PROJECT_ID\--member='PRINCIPAL'\--role='roles/iam.serviceAccountUser'

If you use custom roles, then the principal needs theiam.serviceAccounts.actAs permission.

For more information about the Service Account User role,seeService Account User role.

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

To create a sink with a user-managed service account, run thegcloud logging sinks createcommand and include the--custom-writer-identity option.

Before you run the following command, make the following replacements:

• SINK_NAME: The name of the log sink.

Execute thegcloud logging sinks createcommand:

gcloudloggingsinkscreateSINK_NAME\logging.googleapis.com/projects/LOG_BUCKET_PROJECT_ID/locations/LOCATION/buckets/BUCKET_NAME\--custom-writer-identity=serviceAccount:CUSTOM_SA\--project=SINK_PROJECT_ID

Verify that your sink is routing log entries

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

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

1. Run thegcloud logging write command:

   Before you run the following command, make the following replacements:

   • LOG_NAME: The name of the log. For example, you mightset this field tomylog.

   Execute thegcloud logging writecommand:

   gcloudloggingwriteLOG_NAME"Test log entry"--project=SINK_PROJECT_ID

   The previous command returns the following message:Created log entry.

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

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

What's next

• To learn about routing log entries to supported destinations, seeRoute logs to supported destinations.

• For an overview about how Logging routes and stores yourlog entries, seeRouting and storage overview.

• If you encounter issues as you use sinks to route log entries, seeTroubleshoot routing logs.

• To learn how to view your log entries in their destinations, as well as howthe log entries are formatted and organized, seeView logs in sink destinations.