Using the API - Insights

This page explains how to view and manage insights in Recommender using gcloud commands or the REST API.

A typical insight interaction with the Recommender API is:

  • List insights currently available for a specific insight type
  • Mark an insight that you intend to take action on as accepted

For information about changing the state of insights in the Google Cloud Console, refer to the documentation for the Recommendation Hub or for the appropriate insight type.

Set the default project

Set the default project if you haven't done so already:

gcloud config set project PROJECT_ID

where PROJECT_ID is the ID of your project.

Set environment variables

Set environment variables for Recommender interactions:

PROJECT=TARGET_PROJECT_ID
LOCATION=LOCATION_ID
INSIGHT_TYPE=INSIGHT_TYPE_ID

where:

  • TARGET_PROJECT_ID is the project whose insights you want to list. This can be a different project than your current project.

    • For gcloud commands, you must use the project ID
    • For API requests, you can use the project number or project ID. Project number is recommended.

    The project number is returned in responses from both the API and gcloud commands.

  • LOCATION_ID is the Google Cloud location where resources associated with the insights are located (for example, global or us-central1-a).

  • INSIGHT_TYPE_ID is the fully-qualified insight type ID (for example, google.iam.policy.Insight).

See Insight types for a table of links to information about each insight type, including supported locations and insight type IDs.

Set permissions

You must have permissions to access insights in the target project. These permissions vary by insight type. See Insight types for a table of links to information about each insight type, including the required permissions.

List insights

To list insights in the target project:

gcloud

Enter the following:

gcloud recommender insights list \
    --project=${PROJECT} \
    --location=${LOCATION} \
    --insight-type=${INSIGHT_TYPE} \
    --format=FORMAT

where FORMAT is a supported gcloud output format (for example, json).

For example:

gcloud recommender insights list \
    --project=example-project \
    --location=global \
    --insight-type=google.iam.policy.Insight \
    --format=json

REST

Enter the following:

curl \
    -H "Authorization: Bearer $(gcloud auth print-access-token)"  \
    -H "x-goog-user-project: ${PROJECT}" \
    "https://recommender.googleapis.com/v1/projects/${PROJECT}/locations/${LOCATION}/insightTypes/${INSIGHT_TYPE}/insights"

For example:

curl \
    -H "Authorization: Bearer $(gcloud auth print-access-token)"  \
    -H "x-goog-user-project: example-project" \
    "https://recommender.googleapis.com/v1/projects/example-project/locations/us-central1-a/insightTypes/google.iam.policy.Insight/insights"

This operation outputs the current IAM policy insights in the target project as a list of Insight entities in the specified format.

The output is similar to the following:

[
  {
    "category": "SECURITY",
    "content": {
      "condition": {
        "description": "",
        "expression": "",
        "location": "",
        "title": ""
      },
      "exercisedPermissions": [],
      "inferredPermissions": [],
      "member": "user:my-service-account@example-project.iam.gserviceaccount.com",
      "role": "roles/iam.securityReviewer"
    },
    "description": "0 permission checks were authorized by this policy binding tuple.",
    "etag": "\"45f4e2c63f6952e8\"",
    "insightSubtype": "PERMISSIONS_USAGE",
    "lastRefreshTime": "2020-03-06T08:00:00Z",
    "name": "projects/32428390823/locations/global/insightTypes/google.iam.policy.Insight/insights/a523ff7e-ed03-4143-a3a5-5b396b99cba9",
    "observationPeriod": "7776000s",
    "stateInfo": {
      "state": "ACTIVE",
    },
    "targetResources": [
      "//cloudresourcemanager.googleapis.com/projects/32428390823"
    ],
  }
]

Note that the returned insights include the following fields:

  • A name field in the following format:

    projects/PROJECT_ID/locations/LOCATION/insightTypes/INSIGHT_TYPE_ID/insights/INSIGHT_ID

    where INSIGHT_ID uniquely identifies the insight

  • An etag field that is associated with the current insight state.

When you reference an insight using subsequent gcloud commands or REST API calls, you reference both the insight ID and etag, which makes sure that any operations are performed only if the insight has not been modified since you last retrieved it.

Mark an insight as accepted

You can mark an insight as accepted to indicate that you intend to take or have taken an action on an associated resource based on the information provided in the insight. When an insight is accepted, your user name is assigned as the actor for the insight, and Recommender will not update the insight with newer content.

To mark an insight as accepted:

gcloud

Enter the following:

gcloud recommender insights mark-accepted \
    INSIGHT_ID \
    --project=${PROJECT} \
    --location=${LOCATION} \
    --insight-type=${INSIGHT_TYPE} \
    --etag=etag \
    --state-metadata=STATE_METADATA
    --format=FORMAT

where:

  • INSIGHT_ID is the ID of an insight retrieved from a previous call to list insights
  • etag is the returned etag representing the insight state
  • STATE_METADATA is an optional metadata about the operation. Specify the metadata as a comma-separated list of KEY=VALUE pairs.

For example:

gcloud recommender insights mark-accepted \
    a523ff7e-ed03-4143-a3a5-5b396b99cba9 \
    --project=example-project \
    --location=global \
    --insight-type=google.iam.policy.Insight \
    --etag='"280b34810bba8a1a"' \
    --state-metadata=priority=high,tracking_number=12345
    --format=json

REST

Enter the following:

curl -X POST \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer $(gcloud auth print-access-token)"  \
    -H "x-goog-user-project: ${PROJECT}" \
    --data-binary @- \
    https://recommender.googleapis.com/v1/projects/${PROJECT}/locations/${LOCATION}/insightTypes/${INSIGHT_TYPE}/insights/INSIGHT_ID:markAccepted \
<< EOM
{
  "etag": "etag",
  "stateMetadata": STATE_METADATA
}
EOM

where:

  • INSIGHT_ID is the ID of an insight retrieved from a previous call to list insights
  • etag is the returned etag representing the insight state
  • STATE_METADATA is an optional field with additional metadata about the operation. Specify the metadata as key:value pairs.

For example:

curl -X POST \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer $(gcloud auth print-access-token)"  \
    -H "x-goog-user-project: example-project" \
    --data-binary @- \
    https://recommender.googleapis.com/v1/projects/example-project/locations/global/insightTypes/google.iam.policy.Insight/insights/a523ff7e-ed03-4143-a3a5-5b396b99cba9:markAccepted \
<< EOM
{
  "etag": "\"280b34810bba8a1a\""
  "stateMetadata": {
    "priority" : "high",
    "tracking_number": "12345"
  }
}
EOM

This operation returns the Insight entity in the specified format after the operation has taken place.

The output is similar to the following:

{
  "category": "SECURITY",
  "content": { ...  },
  "description": "0 permission checks were authorized by this policy binding tuple.",
  "etag": "\"356ae51165729f38\"",
  "insightSubtype": "PERMISSIONS_USAGE",
  "lastModifiedUser": "admin123@example-project.iam.gserviceaccount.com",
  "lastRefreshTime": "2020-03-06T08:00:00Z",
  "name": "projects/32428390823/locations/global/insightTypes/google.iam.policy.Insight/insights/a523ff7e-ed03-4143-a3a5-5b396b99cba9",
  "observationPeriod": "7776000s",
  "stateInfo": {
    "state": "ACCEPTED",
    "stateMetadata": {
      "priority" : "high",
      "tracking_number": "12345"
    }
  },
  "targetResources": [
    "//cloudresourcemanager.googleapis.com/projects/32428390823"
  ],
  "userLastUpdateTime": "2020-03-31T20:57:50.509855Z"
}

Note that the value of the state field has changed to ACCEPTED.