Authorizing the agent

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

This guide explains how to install private-key service account credentials on a VM instance to authorize the Stackdriver Monitoring 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 Monitoring. 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

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

• If you're running very old Compute Engine instances or Compute Engine instances created without the default credentials, then you must complete the steps in this guide before installing the agent. These VMs might not have the required private-key credentials. To verify your credentials, complete the Verifying Compute Engine credentials procedures. On newly created Compute Engine VM instances, the default service account on your instance has the credentials that the agents needs.

• If you're running AWS EC2 VM instances, you must complete the steps in this guide before installing the agent. Amazon EC2 VM instance don't have the required service account. Instead, you must manually obtain private-key credentials from a service account of the AWS connector project. If you think your instance already has private-key credentials, then complete the Verifying private-key credentials procedures to check them. To add private-key credentials, skip ahead to Adding credentials.

You can check your authorization scopes on Compute Engine using the following command:

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

Look for one or more of the following authorization scopes in the output:

https://www.googleapis.com/auth/monitoring.write
https://www.googleapis.com/auth/monitoring.admin
https://www.googleapis.com/auth/cloud-platform

Adding credentials

Authorization refers to the process of determining what permissions an authenticated client has for a set of resources.

Authorizing the Monitoring agent on a VM instance involves the following steps:

1. Creating a service account with the required privileges and private-key credentials in the Google Cloud project associated with your VM instance. For Amazon EC2 VM instances, you do this in the AWS Link project that Stackdriver creates when you connect your AWS account.

2. Copying the private-key credentials to your VM instance, where they serve as Application Default Credentials for software running on your instance.

3. Installing or restarting the agent.

Warning: The new credentials might overwrite your existing credentials, so check that your current applications still have the proper credentials when you complete these procedures.

Creating 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, as opposed to a specific user. You can use service accounts for authentication regardless of where your code runs: on Compute Engine, App Engine, or on-premise. Read Authentication overview for more information.

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. If you created your instance in the Workspace hosting project, then choose the Workspace.

  • For Amazon EC2 instances, choose the AWS connector project created when you connected Monitoring your AWS account. The connector project's name typically begins with AWS Link. Don't create your service account in the Workspace project.

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

  • Monitoring > Monitoring Metric Writer. This authorizes the Monitoring agent.

  If you will also install the Logging agent, then add the following role for that agent:

  • Logging > Logs Writer. This authorizes the Logging agent.

• When creating the key, select JSON as the Key type.

For your convenience, you can create the variable CREDS to point to the credentials file on your workstation. For example:

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

The rest of these procedures refer to that variable.

Copying the private key to your instance

After creating the service account, you must 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.

The following file-copy instructions assume that you have a Linux environment on both your workstation and your instance. If you are using a different environment, consult the documentation from your cloud provider for how to copy the private-key file. In the previous step, Creating a service account, your private-key credentials should have been stored on your workstation at a location you saved in the variable CREDS:

Compute Engine

On your workstation, use the gcloud command-line tool. You can find [YOUR-INSTANCE-NAME] and [YOUR-INSTANCE-ZONE] in the Google Cloud Console in the VM Instances page:

REMOTE_USER="$USER"
INSTANCE="[YOUR-INSTANCE-NAME]"
ZONE="[YOUR-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"

Amazon EC2

On your workstation, use scp:

KEY="[YOUR-SSH-KEY-PAIR-FILE]"
INSTANCE="ec2-[YOUR-INSTANCE'S-PUBLIC-ID.[YOUR-ZONE].compute.amazonaws.com"
# The remote user depends on the installed OS: ec2-user, ubuntu, root, etc.
REMOTE_USER="ec2-user"
scp -i "$KEY" "$CREDS" "$REMOTE_USER@$INSTANCE:~/temp.json"

On your EC2 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"

Note: If your credential file is not in the previously listed default location, then in addition to the commands in the preceding examples, you must be sure that GOOGLE_APPLICATION_CREDENTIALS is defined and visible to the agent process.

Next steps

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

• If you have not yet installed the agent, go to the agent installation page and install the agent. See Installing the agent for instructions.

• If you have already installed the agent, restart it to use the new credentials. See Restarting the agent for instructions.

• If you would like to double-check the credentials, see Verifying private-key credentials.