Note: Skip this guide and return toInstall the Logging agent if you are using aCompute Engine VM instance, and you have not yet attempted to install theagent. Compute Engine instances should be pre-authorized to run the agent.

This guide explains how to ensure that the Logging agent , which you installon your virtual machine (VM) instance, is authorized to send telemetry data toLogging.

Authorization overview

Authorization refers to the process of determining what permissions anauthenticated client has for a set of resources. Google Cloud authorizesthe Logging agent on a Compute Engine VM instance by usingapplication default credentials(ADC).

The Logging agent supports ADCthat authenticate either a VM's attached service account,or a service account key.

• Anattached service account refers to a service account that's specificto agiven resource, such as a VM. The service account has its own uniquecredentials. ADC uses the VM'smetadata serverto obtain credentials for a service.
• Aservice account key refers to a private key used toauthorize thekey pair on a service account in a project, which lets you create an accesstoken. You use the token to provide an identity so that you can interactwith Google Cloud APIs on behalf of the service account.

We recommend that you configure ADC to authenticate by usingan attached service accountwhenever possible, as the private key requires local storage, and that storagecan be compromised. For more information about service account keys, seeBest practices for managing service account keys.

Before you begin

Read this guide if any of the following applies to you:

• If you're running very old Compute Engine instances or if you havemodified the access scopes or service account settings for yourCompute Engine instances, then you must complete the steps in thisguide before installing the agent. These VMs might not have the requiredservice account key file. For information about how to verify the accessscopes and service account settings of your instances, seeVerify Compute Engine credentials.

  On newly created Compute Engine VM instances, the access scopes andservice account settings are sufficient to run the agents.

To verify your access scopes, do the following:

1. Query the access scopes by running the following command on your Compute Engine instance:

   curl --silent --connect-timeout 1 -f -H "Metadata-Flavor: Google" http://169.254.169.254/computeMetadata/v1/instance/service-accounts/default/scopes

2. In the command output, if the access scopehttps://www.googleapis.com/auth/cloud-platform is listed, then you have sufficient authorization.

   Ifhttps://www.googleapis.com/auth/cloud-platform isn't listed, then you require two access scopes, one from each of the following "logging" and "monitoring" pairs:

   • https://www.googleapis.com/auth/logging.write or
     https://www.googleapis.com/auth/logging.admin
   • https://www.googleapis.com/auth/monitoring.write or
     https://www.googleapis.com/auth/monitoring.admin

To modify your access scopes, do the following:

1. In the Google Cloud console, go to theVM instances page:

   Go toVM instances

   If you use the search bar to find this page, then select the result whose subheading isCompute Engine.

2. If necessary, click the drop-down list of Google Cloud projects and select the name of your project.
3. SelectVM instances from the navigation menu, select theInstances tab, and the select the name of your VM.
4. Shut down the VM by clickingstop Stop.
5. After the VM stops, clickedit Edit.
6. Locate theAccess scopes in theIdentity and API access section of the page, and then selectSet access for each API.
7. ForStackdriver Logging API andStackdriver Monitoring API entries, select theWrite Only.
8. ClickSave, and then restart the VM by clickingplay_arrow Start/Resume.

Use a service account

Authentication refers to the process of determining a client's identity.For authentication, we recommend using aservice account, a special kindof account that is typically used by an application or a workload,rather than a person. For more information, seeService accounts overview.

You can use service accounts for authentication regardless of where your coderuns: on Compute Engine, App Engine, or on-premise.For more information, seeAuthentication at Google.

This section describes how to create a new service account and grant itthe necessary roles, and how to update an existing service account if itdoesn't have the necessary roles.

Create a service account

To create a service account, complete theCreating a service accountprocedures with the following information:

• Select the Google Cloud project in which to create the service account.

  • For Compute Engine instances, choose the project in which youcreated the instance.

• In theRole drop-down menu, select the following roles:

  • Logging >Logs Writer. This authorizes the Loggingagent to ingest logs.
  • Monitoring >Monitoring Metric Writer. This authorizes theLogging agent to ingest its own health metrics.

• If you plan to authenticate using a service account key,then selectJSON as theKey type and clickCreate.

  When you clickCreate, a file that contains a service account key isdownloaded to your local system. For more information, seeCreate and delete service account keys.

  Note: After you download a key, you cannot download that key again.

Next, configure your service account and settings based on whether you authorizeby using attached service accounts or by using service account private keys.

Verify and modify roles of an existing service account

You can use the Google Cloud console to determine which roles an existing serviceaccount has, and to add any necessary roles that are missing:

1. In the Google Cloud console, go to theIAM page:

   Go toIAM

   If you use the search bar to find this page, then select the result whose subheading isIAM & Admin.

2. If necessary, click the drop-down list of Google Cloud projectsand select the name of your project.

3. If you don't see a list of IAM principals(users and service accounts), then select thePermissions tab.

4. In theView by Principals list, locate the entry for theservice account. TheRole column lists the roles granted tothe service account.

5. If your service account does not have the necessary roles for the Logging agent , then use the following steps to add the roles described inCreate a service account:

   1. Clickedit Edit in the entry for the service account.
   2. ClickAdd Another Role to add any missing roles.
   3. ClickSave.

Authorize with an attached service account

To authorize the Logging agent installed on a Compute Engine VM instancethat has an attached service account, do the following:

1. Ensure that youverified the access scopes of your VM.

2. Grant your service account theleast privilegedIAM roles possible. For the required roles, see theCreate a service account section of this page.

3. Attach the service accountto the VM where the agent is running.

4. If you haven't already installed the agent, then install it.For information about how to install the agent, seeInstalling the agent.

Authorize with a service account key

To authorize the Logging agent installed on a VM instance by usingservice account private keys, do the following:

1. Transfer the service account key file from your local system to your VM instance:

   1. Create an environment variable to point to the service account key fileon yourlocal system. The following example creates a variable calledCREDS:

      CREDS=~/Downloads/PROJECT-NAME-KEY-ID.json

   2. In the Google Cloud console, go to theVM instances page:

      Go toVM instances

      If you use the search bar to find this page, then select the result whose subheading isCompute Engine.

      Identify theINSTANCE_NAME andINSTANCE_ZONE for your VM.

   3. On your local system, run aGoogle Cloud CLIcommand to copy the key file from your local system to your VM instance:

      REMOTE_USER="$USER"INSTANCE="INSTANCE_NAME"ZONE="INSTANCE_ZONE"gcloudcomputescp"$CREDS""$REMOTE_USER@$INSTANCE:~/temp.json"--zone"$ZONE"

   4. On your Compute Engine instance, move the service account key filefrom the temporary location to a permanent location,and for Linux, ensure that the service account key file is readable onlybyroot.

      Warning: If you already have a service account key file, ensure that your newkey file doesn't overwrite the key file for your current applications.

      These are the locations where the agent expects your key file:

      • Linux VMs:/etc/google/auth/application_default_credentials.json
      • Windows VMs:C:\ProgramData\Google\Auth\application_default_credentials.json
      • Linux and Windows VMs:Any location you store in the environmentvariableGOOGLE_APPLICATION_CREDENTIALS, which must be visible tothe agent's process. For configuration information, seeSetGOOGLE_APPLICATION_CREDENTIALS.

      For example, on Linux you can run the following script which moves theservice account key file to the default location, and then sets the appropriatepermissions:

      CREDENTIALS_FILE_LOCATION="/etc/google/auth/application_default_credentials.json"sudomkdir-p/etc/google/authsudomv"$HOME/temp.json""$CREDENTIALS_FILE_LOCATION"sudochownroot:root"$CREDENTIALS_FILE_LOCATION"sudochmod0400"$CREDENTIALS_FILE_LOCATION"

2. Your VM instance now has the service account key file that the agent needs.Next, install or restart the agent:

   • For information about how to install the agent, seeInstalling the agent.

   • For information about how to restart the agent, seeRestarting the agent.

   • If you would like to double-check the service account key file, seeVerifying private-key credentials.

SetGOOGLE_APPLICATION_CREDENTIALS

This section shows how to set the environment variableGOOGLE_APPLICATION_CREDENTIALS so that it is visible to the agent's process.

Note: The Logging agent isn't the only service that uses the environmentvariableGOOGLE_APPLICATION_CREDENTIALS. If you change the value of thisvariable as described in this section,then that change affects all system services that rely on that variable.

Linux

1. Edit the following configuration file, or create the file if it doesn'texist:

   /etc/default/google-fluentd

2. Add the following to the configuration file:

   GOOGLE_APPLICATION_CREDENTIALS=PATH_TO_CREDENTIAL_FILE

3. Restart the agent by running the following command on your VM instance:

   sudoservicegoogle-fluentdrestart

Windows

1. In PowerShell, run the following commands as administrator to set theGOOGLE_APPLICATION_CREDENTIALS system environment variable for theOps Agent to use:

   [Environment]::SetEnvironmentVariable("GOOGLE_APPLICATION_CREDENTIALS","PATH_TO_CREDENTIAL_FILE","Machine")

2. Restart the agent by running the following command on your VM instance:

   Restart-Service-NameStackdriverLogging