Authorize the Ops Agent

Stay organized with collections Save and categorize content based on your preferences.

This guide explains how to install private-key service account credentials on a VM instance to authorize the Ops Agent. Before installing the agent, check that your VM instance has the credentials that the agent needs. The agent must have permission to send information to Logging. Permission is given by using service account credentials that are stored on your VM instance and serve as Application Default Credentials for the agent.

Before you begin

Verify your authorization scopes:

  1. Run the following command on a 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 authorization scopes output, if https://www.googleapis.com/auth/cloud-platform is listed, then you have sufficient authorization.

    If https://www.googleapis.com/auth/cloud-platform isn't listed, then you require two authorization scopes, one from each of the following 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

Authorization overview

Authorization refers to the process of determining what permissions an authenticated client has for a set of resources. Google Cloud authorizes the Ops Agent on a Compute Engine VM instance by using application default credentials (ADC).

The Ops Agent supports ADC that authenticate either a VM's attached service account, or a private key from a service account.

  • An attached service account refers to a service account that's specific to a given resource, such as a VM. The service account has its own unique credentials. ADC uses the VM's metadata server to obtain credentials for a service.
  • A private key from a service account refers to a private key used to authorize the key pair on a service account in a project, which lets you create an access token. You use the token to provide an identity so that you can interact with Google Cloud APIs on behalf of the service account.

We recommend that you configure the ADC to authenticate an attached service account whenever possible, as the private key requires local storage, and that storage can be compromised. For more information about service account keys, see Best practices for managing service account keys.

Create a service account

Authentication refers to the process of determining a client's identity. For authentication, we recommend using a service account, a Google account that is associated with your Google Cloud project, rather than with a specific user. You can use service accounts for authentication regardless of where your code runs: on Compute Engine, App Engine, or on-premise. For more information, see Authentication at Google.

To create a service account, complete the Creating a service account procedures 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 you created the instance.

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

    • Monitoring > Monitoring Metric Writer.

    • Logging > Logs Writer.

  • If you plan to use private key authentication, select JSON as the Key type.

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

Authorize with an attached service account

To authorize the Ops Agent installed on a VM instance that has an attached service account, do the following:

  1. Grant your service account the least privileged IAM roles possible.

  2. Attach the service account to the resource where your code is running.

  3. Install or restart the agent.

Authorize a service account with a private key

To authorize the Ops Agent by using service account private keys, do the following:

  1. Copy the private-key file to one of the following locations on your VM instance so that the agent can recognize the credentials. You can use any file-copy tool you wish.

    • Linux only: /etc/google/auth/application_default_credentials.json

    • Windows only: C:\ProgramData\Google\Auth\application_default_credentials.json

    • For both Linux and Windows: Any location you store in the variable, GOOGLE_APPLICATION_CREDENTIALS. The variable must be visible to the agent's process.

  2. Create an environment variable to point to the credentials file on your workstation. The following example creates a variable called CREDS:

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

  3. Complete the steps shown in the following table:

    Compute Engine

    On your local system, use the gcloud command-line tool. You can find INSTANCE_NAME and INSTANCE_ZONE in the Google Cloud Console in the VM Instances page:

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

    On your Compute Engine instance, run these commands:

    GOOGLE_APPLICATION_CREDENTIALS="/etc/google/auth/application_default_credentials.json"
sudo mkdir -p /etc/google/auth
sudo mv "$HOME/temp.json" "$GOOGLE_APPLICATION_CREDENTIALS"
sudo chown root:root "$GOOGLE_APPLICATION_CREDENTIALS"
sudo chmod 0400 "$GOOGLE_APPLICATION_CREDENTIALS"

    If your credential file is not in the previously listed default location, then in addition to the commands in the preceding examples, ensure that GOOGLE_APPLICATION_CREDENTIALS is defined and visible to the agent process.

  4. Install or restart the agent.

Authorize the Ops Agent

Linux

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

     /etc/systemd/system.conf

  2. Add the following to the file:

     DefaultEnvironment="GOOGLE_APPLICATION_CREDENTIALS=path_to_credentials_file"

  3. Reload the environment variables:

     sudo systemctl daemon-reload

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

     sudo service google-cloud-ops-agent restart

Windows

In PowerShell, run the following commands as administrator to set the GOOGLE_APPLICATION_CREDENTIALS system environment variable for the Ops Agent to use.

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

Next steps

Your VM instance now has the credentials that the agent needs.