Google Cloud Recommender

Common errors

• google.auth.exceptions.DefaultCredentialsError: Could not automatically determine credentials. Please set GOOGLE_APPLICATION_CREDENTIALS or provide a project explicitly.

  cause The Python client library could not find valid Google Cloud credentials in the environment.
  fix Ensure you have authenticated with Google Cloud (e.g., `gcloud auth application-default login`) or set the `GOOGLE_APPLICATION_CREDENTIALS` environment variable to the path of a service account key file.

• google.api_core.exceptions.PermissionDenied: 403 The caller does not have permission

  cause The authenticated identity lacks the necessary IAM permissions to perform the requested Recommender API operation.
  fix Verify that the service account or user principal has the `recommender.recommendations.list` permission (or `recommender.recommendations.get`) on the project or resource you are querying. The `roles/recommender.viewer` role typically provides this.

• google.api_core.exceptions.InvalidArgument: 400 Request contains an invalid argument.

  cause A resource name (e.g., for `parent`, `name`) passed to an API method does not conform to the expected format.
  fix Double-check the format of the resource names against the official Recommender API documentation. For instance, a recommender name might be `projects/PROJECT_ID/locations/LOCATION/recommenders/RECOMMENDER_ID`.

Warnings

• breaking Older Python versions (e.g., 3.8 and below) are no longer supported. The library now requires Python 3.9 or newer. Ensure your development and deployment environments meet this requirement to avoid installation failures or runtime errors.
  Fix: Upgrade your Python environment to 3.9 or higher (e.g., `python3.9 -m pip install google-cloud-recommender`).
• gotcha Resource names for Google Cloud Recommender API calls (e.g., `parent`, `name`) must follow a strict, fully-qualified format (e.g., `projects/project-id/locations/location/recommenders/recommender-id`). Incorrect formatting will lead to `InvalidArgument` errors.
  Fix: Always construct resource names carefully following the documentation's prescribed format, using f-strings or `RecommenderClient.common_location_path` helpers.
• gotcha The Recommender API requires specific IAM permissions to list or get recommendations (e.g., `recommender.recommendations.list` for the target resource type). Lacking these permissions will result in a 403 Permission Denied error.
  Fix: Ensure the service account or user invoking the API has the necessary `roles/recommender.viewer` or custom roles with appropriate permissions granted at the project or resource level.
• gotcha The `google-cloud-recommender` library provides both synchronous (`RecommenderClient`) and asynchronous (`RecommenderAsyncClient`) clients. Mixing methods or attempting to `await` on synchronous client calls will result in `TypeError` or unexpected behavior.
  Fix: Use `RecommenderClient` for blocking calls and `RecommenderAsyncClient` with `await` in an `async` context for non-blocking I/O. Do not interchange them without proper understanding.

Install

• pip install google-cloud-recommender Install stable version

Imports

• RecommenderClient
  wrong:

  from google.cloud.recommender import RecommenderClient

  correct:

  from google.cloud import recommender_v1
  client = recommender_v1.RecommenderClient()

  Google Cloud client libraries typically version their top-level imports (e.g., _v1) rather than exposing the client directly under the top-level package.
• RecommenderAsyncClient

  from google.cloud import recommender_v1
  async_client = recommender_v1.RecommenderAsyncClient()

  Use this for asynchronous operations with `asyncio`.

Quickstart

This quickstart demonstrates how to initialize the `RecommenderClient` and list recommendations for a specific recommender (e.g., IAM policy recommendations) within a Google Cloud project. It uses environment variables for project ID, which is a best practice for authentication. Remember to enable the Recommender API and set up appropriate IAM permissions (e.g., `recommender.recommendations.list`).

import os
from google.cloud import recommender_v1

# Set your Google Cloud Project ID and a specific location
project_id = os.environ.get('GCP_PROJECT_ID', 'your-project-id')
location = 'global' # Recommender often uses 'global' or a specific region

# Initialize the client
client = recommender_v1.RecommenderClient()

# Define the recommender name (e.g., for IAM policy recommendations)
# Common recommenders: google.iam.policy.Recommender, google.compute.instance.MachineTypeRecommender
recommender_name = f"projects/{project_id}/locations/{location}/recommenders/google.iam.policy.Recommender"

# List recommendations for a given recommender
try:
    # Iterate through the paginated results
    for recommendation in client.list_recommendations(parent=recommender_name):
        print(f"Recommendation ID: {recommendation.name.split('/')[-1]}")
        print(f"Description: {recommendation.description}")
        print(f"State: {recommendation.state_info.state.name}")
        if recommendation.primary_impact:
            print(f"Primary Impact: {recommendation.primary_impact.category.name}")
        print('---\n')
except Exception as e:
    print(f"An error occurred: {e}")
    print("Ensure you have `recommender.recommendations.list` permission and `GCP_PROJECT_ID` is set correctly.")