Configure a metrics scope by using the API

This document describes how to use the metrics scope methods in the Cloud Monitoring API to configure the metrics scope of a Google Cloud project. This page is intended for developers and system administrators.

To connect an AWS account to the metrics scope of a Google Cloud project, you must use the Google Cloud console. For more information, see View metrics for AWS accounts.

Before you begin

If you aren't familiar with the terms metrics scope and scoping project, then see Metrics scopes.
Ensure that your Identity and Access Management (IAM) roles on the scoping project and on each project that you want to add as a monitored project include all permissions in the Monitoring Admin (roles/monitoring.admin) role. For more information, see Metrics scope configurations.
The metrics scope methods of the Cloud Monitoring API that retrieve information are synchronous; however, those APIs that change state are asynchronous. For information about how to determine when an asynchronous method is complete and how to determine its status, see Asynchronous API methods.
For information about using Google Cloud with Terraform, see the following resources:
- Terraform with Google Cloud
- Terraform registry for google_monitoring_monitored_project

`curl` command parameters

You can invoke the metrics scopes APIs directly. This page provides sample commands that use curl. Each curl command includes a set of arguments followed by the URL of an API resource:

curl -H "Authorization: Bearer ${TOKEN}" <other_args> \
https://monitoring.googleapis.com/v1/locations/global/metricsScopes/<resource>

The examples on this page rely on the following environment variables:

TOKEN: Stores the authentication token.
SCOPING_PROJECT_ID_OR_NUMBER: Stores the project ID or number for a scoping project of a metrics scope.
MONITORED_PROJECT_ID_OR_NUMBER: Stores the project ID or number of a project that is to be added to, or removed from, a metrics scope.

You might also have to specify other arguments, for example, to specify the type of the HTTP request (for example, -X DELETE). The default request is GET, so the examples don't specify it.

For information about the setup required for the examples, see curl command setup.

Get a metrics scope

To get information about a metrics scope, send a GET request to the locations.global.metricsScopes.get endpoint:

curl -H "Authorization: Bearer ${TOKEN}" \
https://monitoring.googleapis.com/v1/locations/global/metricsScopes/${SCOPING_PROJECT_ID_OR_NUMBER}

When successful, the response is a MetricsScope object.

This method doesn't result in an entry being written to the audit logs of the scoping project. To have these actions recorded in the audit log, enable Data Read for the Cloud Resource Manager API. For more information, see Configuring Data Access audit logs.

List all metrics scopes that include a project

To get a list of metrics scopes that can view the metrics for a project, send a GET request to the locations.global.metricsScopes.listMetricsScopesByMonitoredProject endpoint and include the query parameter that specifies the project.

curl -H "Authorization: Bearer ${TOKEN}" \
https://monitoring.googleapis.com/v1/locations/global/metricsScopes:listMetricsScopesByMonitoredProject?monitored_resource_container=projects/${PROJECT_ID_OR_NUMBER}

When successful, the response is an array of MetricsScope objects.

Add a project to a metrics scope

To add a Google Cloud project to a metrics scope, send a POST request to the locations.global.metricsScopes.projects.create endpoint. In the following example, the project identified by the environment variable MONITORED_PROJECT_ID_OR_NUMBER is added as monitored project:

curl -H "Authorization: Bearer ${TOKEN}" \
-H "Content-Type: application/json" -X POST \
-d "{'name': 'locations/global/metricsScopes/${SCOPING_PROJECT_ID_OR_NUMBER}/projects/${MONITORED_PROJECT_ID_OR_NUMBER}'}" \
https://monitoring.googleapis.com/v1/locations/global/metricsScopes/${SCOPING_PROJECT_ID_OR_NUMBER}/projects

The response of this asynchronous method is an Operation object.

Applications calling this method should poll the operation.get endpoint until the value of the Operation.done field is true. When the Operation.done field is set to false, that indicates the operation is in progress. For more information, see Asynchronous API commands.

The following is an example of the response when adding a monitored project is successful:

{
  "name": "operations/6915efde-1915-400a-ad49-7b62041d9bd2",
  "metadata": {
    "@type": "type.googleapis.com/google.monitoring.metricsscope.v1.OperationMetadata",
    "state": "DONE",
    ...
  },
  "done": true,
  "response": {
    "@type": "type.googleapis.com/google.monitoring.metricsscope.v1.MonitoredProject",
    "name": "locations/global/metricsScopes/012012012012/projects/678678678678",
    "provider": "GCP",
    "providerAccountId": "...",
    ...
  }
}

In the previous response, the Operation.done field is set to true. This value indicates that the command is complete. Because the command completed successfully, the Operation.response field is set and its value is a MonitoredProject object. The response.name field includes the identifier of the scoping project and the monitored project. The providerAccountId field lists the name of the monitored project.

Invoking this method results in an entry in the audit logs of the scoping project. The Google Cloud console doesn't invoke this API method. Therefore, modifications made to a metrics scope when using the Google Cloud console aren't recorded in the audit logs.

Remove a project from a metrics scope

To remove a Google Cloud project from a metrics scope, send a DELETE request to the locations.global.metricsScopes.projects.delete endpoint:

curl -H "Authorization: Bearer ${TOKEN}" -X DELETE \
https://monitoring.googleapis.com/v1/locations/global/metricsScopes/${SCOPING_PROJECT_ID_OR_NUMBER}/projects/${MONITORED_PROJECT_ID_OR_NUMBER}

The response to this asynchronous method is an Operation object.

The following is an example of the response when removal of a monitored project is successful:

{
  "name": "operations/4367ff34-0ff0-4767-b8d3-0638e30f077c",
  "metadata": {
    "@type": "type.googleapis.com/google.monitoring.metricsscope.v1.OperationMetadata",
    "state": "DONE",
    ...
  },
  "done": true,
  "response": {
    "@type": "type.googleapis.com/google.protobuf.Empty"
  }
}

Asynchronous API methods

All metrics scope methods of the Cloud Monitoring API that change the state of the system, for example, the command to add a monitored project a metrics scope, are asynchronous. For these commands, the command response is an Operation object.

Applications that call an asynchronous API method should poll the operation.get endpoint until the value of the Operation.done field is true:

When done is false, the operation is in progress.

To refresh the status information, send a GET request to the operation.get endpoint:
```
curl -H "Authorization: Bearer ${TOKEN}" \
https://monitoring.googleapis.com/v1/${OPERATION_NAME}
```
In the previous command, OPERATION_NAME is an environment variable that stores the value of the Operation.name field.
When done is true, the operation is complete and either the error or response field is set:
- error: When set, the asynchronous operation failed. The value of this field is a Status object that contains a gRPC error code and an error message.
- response: When set, the asynchronous operation completed successfully, and the value reflects the result.

`curl` command setup

This section describes the setup used to create the curl commands in this document.

Set these environment variables to simplify creation of the curl commands:

Create the environment variable to store the scoping project ID or number:
```
SCOPING_PROJECT_ID_OR_NUMBER=a-sample-project
```
Optional. If you plan to add or remove monitored projects, then configure the environment variable with the monitored project ID or number:
```
MONITORED_PROJECT_ID_OR_NUMBER=a-monitored-project
```
Authenticate to the Google Cloud CLI:
```
gcloud auth login
```
Optional. To avoid having to specify your project ID with each gcloud command, set your project ID as the default by using gcloud CLI:
```
gcloud config set project ${SCOPING_PROJECT_ID_OR_NUMBER}
```
Create an authorization token and capture it in an environment variable:
```
TOKEN=`gcloud auth print-access-token`
```
Tokens are valid for a limited time. If commands that worked suddenly report that you are unauthenticated, then reissue this command.
To verify that you got an access token, echo the TOKEN variable:
```
echo ${TOKEN}
ya29.GluiBj8o....
```