Note: Skip this guide and return toInstall theOps Agent unless you are using very oldCompute Engine VMs or have to use acustom serviceaccount instead ofthedefault serviceaccount.Compute Engine instances are pre-authorized to run the agent.

This guide explains how to ensure that the Ops 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 Ops Agent on a Compute Engine VM instance by usingapplication default credentials(ADC).

The Ops 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.

• The Ops Agent doesn't support authorization usinggcloud auth.To prevent unwanted behavior, you mustrevokeany credentials created by usinggcloud auth.

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.

Verify your access scopes

Compute Engine VM instances are assigned access scopes when you createthem. New Compute Engine VMs have adequate access scopes for theOps Agent, but old VMs or those on which scopes have been modifiedmight not. For more information about access scopes and service accounts, seeAuthorizationin the Compute Engine documentation.

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:

  • Monitoring >Monitoring Metric Writer.

  • Logging >Logs Writer.

• 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 theOps 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 Ops 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 Ops 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.

      You must also set the environment variableGOOGLE_APPLICATION_CREDENTIALSto point to the location of the service account key file, and the variablemust be visible to the agent's process. For configuration information, seeSetGOOGLE_APPLICATION_CREDENTIALS.

      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.

      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 Ops 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/systemd/system.conf

2. Add the following to the configuration file:

   DefaultEnvironment="GOOGLE_APPLICATION_CREDENTIALS=PATH_TO_CREDENTIAL_FILE"

3. Reload the environment variables:

   sudosystemctldaemon-reload

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

   sudosystemctlrestartgoogle-cloud-ops-agent

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-Namegoogle-cloud-ops-agent-Force