Authorizing an Agent

This guide explains how to install private-key service account credentials on a VM instance to authorize the Stackdriver Logging and Monitoring agents.

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

  • You know that you need to install these credentials. For example, you are using an Amazon EC2 VM instance.

  • You suspect that the existing credentials on your VM instance are invalid, and you want to replace them with something that will work.

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/logging.write
  https://www.googleapis.com/auth/logging.admin.

Adding credentials

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

Authorizing the Stackdriver Logging and Monitoring agents on a VM instance involves the following steps:

  1. Creating a service account with the required privileges and private-key credentials in the GCP project associated with your VM instance. For Amazon EC2 VM instances, you do this in the AWS Link project that Stackdriver creates on your behalf 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.

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 GCP project, as opposed to a specific user. Service accounts can be used for authentication regardless of where your code runs (locally, Compute Engine, App Engine, on premises, etc.) See Authentication overview for more information.

To create a service account, follow the instructions in Creating a service account. In the Role drop-down menu, select both of the following roles:

  • Logging > Logs Writer. This authorizes the Stackdriver Logging agent.
  • Monitoring > Monitoring Metric Writer. This authorizes the Stackdriver Monitoring agent. Adding this role lets you use this service account to run both Stackdriver agents.

For your convenience in the following instructions, set the variable CREDS to point to the credentials file on your workstation. For example:

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

Copying the private key to your instance

For the added service account credentials to be recognized, you must copy the private-key file to one of the following locations on your VM instance, using whatever file-copy tool you wish:

  • Linux only: /etc/google/auth/application_default_credentials.json
  • Windows only: C:\ProgramData\Google\Auth\application_default_credentials.json
  • Linux or Windows: Any location that you store in the variable GOOGLE_APPLICATION_CREDENTIALS. The variable must be visible to the agent process.

The following file-copy instructions assume 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 GCP 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"

Next steps

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

Send feedback about...

Stackdriver Logging