{"id":9784,"library":"google-cloud-recommender","title":"Google Cloud Recommender","description":"The `google-cloud-recommender` client library provides a Python interface for the Google Cloud Recommender API. This service delivers proactive recommendations and insights to help users optimize costs, improve performance, enhance security, and achieve operational excellence across their Google Cloud resources. The library is currently at version 2.21.0 and follows Google's frequent release cadence, often receiving updates multiple times a month as part of the broader `google-cloud-python` monorepo.","status":"active","version":"2.21.0","language":"en","source_language":"en","source_url":"https://github.com/googleapis/google-cloud-python/tree/main/packages/google-cloud-recommender","tags":["google-cloud","gcp","recommender","api-client","optimization","cloud-management"],"install":[{"cmd":"pip install google-cloud-recommender","lang":"bash","label":"Install stable version"}],"dependencies":[],"imports":[{"note":"Google Cloud client libraries typically version their top-level imports (e.g., _v1) rather than exposing the client directly under the top-level package.","wrong":"from google.cloud.recommender import RecommenderClient","symbol":"RecommenderClient","correct":"from google.cloud import recommender_v1\nclient = recommender_v1.RecommenderClient()"},{"note":"Use this for asynchronous operations with `asyncio`.","symbol":"RecommenderAsyncClient","correct":"from google.cloud import recommender_v1\nasync_client = recommender_v1.RecommenderAsyncClient()"}],"quickstart":{"code":"import os\nfrom google.cloud import recommender_v1\n\n# Set your Google Cloud Project ID and a specific location\nproject_id = os.environ.get('GCP_PROJECT_ID', 'your-project-id')\nlocation = 'global' # Recommender often uses 'global' or a specific region\n\n# Initialize the client\nclient = recommender_v1.RecommenderClient()\n\n# Define the recommender name (e.g., for IAM policy recommendations)\n# Common recommenders: google.iam.policy.Recommender, google.compute.instance.MachineTypeRecommender\nrecommender_name = f\"projects/{project_id}/locations/{location}/recommenders/google.iam.policy.Recommender\"\n\n# List recommendations for a given recommender\ntry:\n    # Iterate through the paginated results\n    for recommendation in client.list_recommendations(parent=recommender_name):\n        print(f\"Recommendation ID: {recommendation.name.split('/')[-1]}\")\n        print(f\"Description: {recommendation.description}\")\n        print(f\"State: {recommendation.state_info.state.name}\")\n        if recommendation.primary_impact:\n            print(f\"Primary Impact: {recommendation.primary_impact.category.name}\")\n        print('---\\n')\nexcept Exception as e:\n    print(f\"An error occurred: {e}\")\n    print(\"Ensure you have `recommender.recommendations.list` permission and `GCP_PROJECT_ID` is set correctly.\")\n","lang":"python","description":"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`)."},"warnings":[{"fix":"Upgrade your Python environment to 3.9 or higher (e.g., `python3.9 -m pip install google-cloud-recommender`).","message":"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.","severity":"breaking","affected_versions":"<=2.0.0 (older versions), >=2.1.0 (requires >=3.9)"},{"fix":"Always construct resource names carefully following the documentation's prescribed format, using f-strings or `RecommenderClient.common_location_path` helpers.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-17T00:00:00.000Z","next_check":"2026-07-16T00:00:00.000Z","problems":[{"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.","cause":"The Python client library could not find valid Google Cloud credentials in the environment.","error":"google.auth.exceptions.DefaultCredentialsError: Could not automatically determine credentials. Please set GOOGLE_APPLICATION_CREDENTIALS or provide a project explicitly."},{"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.","cause":"The authenticated identity lacks the necessary IAM permissions to perform the requested Recommender API operation.","error":"google.api_core.exceptions.PermissionDenied: 403 The caller does not have permission"},{"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`.","cause":"A resource name (e.g., for `parent`, `name`) passed to an API method does not conform to the expected format.","error":"google.api_core.exceptions.InvalidArgument: 400 Request contains an invalid argument."}]}