Recommender BigQuery Export

Recommender BigQuery Export

Module flag: recommender_export Enabled by default: no

---

Overview

gcp_export_recommendations_to_bq snapshots active Cloud Recommender findings into BigQuery through streaming inserts. It currently collects Cloud Run idle, Cloud SQL idle, and Cloud SQL over-provisioned recommendations across all locations.

This is a mutation: it may create the destination table and insert rows. It is registered only after explicit configuration and always uses the same two-step confirmation gate as GKE scaling and Cloud Run traffic changes.

This export is independent from Cost Reasoning. Cost reasoning reads the detailed Cloud Billing export; recommendation export writes operational recommendation records.

---

Enable the Tool

Environment variables:

GCP_PROJECT_ID=my-project \
RECOMMENDER_ENABLED=true \
RECOMMENDER_BQ_EXPORT_ENABLED=true \
RECOMMENDER_BQ_EXPORT_DATASET=operations \
./aura-tracker-gcp

Or ~/.aura-tracker.yaml:

recommender_export:
  enabled: true
  dataset: operations

If --modules is present, include the opt-in module explicitly:

./aura-tracker-gcp --modules recommender_export

RECOMMENDER_ENABLED=false disables the Recommender client and is incompatible with executing this export.

---

APIs and IAM

Enable Recommender and BigQuery APIs. The runtime identity needs permission to list the supported recommendations and, on the destination dataset, create a table and write rows. Prefer dataset-scoped BigQuery write access instead of a project-wide role.

The destination dataset must already exist. The tool creates the requested table when absent; it does not create datasets.

---

Tool: gcp_export_recommendations_to_bq

Parameter	Required	Description
project_id	no	Environment alias or configured project ID; default environment when omitted
dataset	conditional	Existing BigQuery dataset; optional when a configured default is present
table	no	Destination table; defaults to gcp_recommendations
dry_run	Step 1	Set true to collect active recommendations and return a confirmation plan without creating a table or inserting rows
confirm_plan_id	Step 2	Plan ID from the preview; executes the stored export request

The preview returns the fully qualified table, rows_planned, plan_id, and ten-minute expiry. Confirmation returns rows_inserted and exported_at.

Rows contain:

• target resource name;
• recommender ID and classified subtype;
• recommendation description and priority;
• estimated monthly savings in USD;
• export timestamp.

---

Retry and Duplicate Behavior

Dry-run performs Recommender reads only: it does not create the table or insert rows. Before any reads, the export checks every required recommender's process-local quota gate. It then gathers the complete recommendation set before creating the table or inserting rows. If a known block exists—even for the last recommender—or a quota response arrives partway through collection, no BigQuery mutation occurs.

Quota errors return a retriable structured MCP error with the quota window and RFC3339 retry_at; clients must not retry before that deadline. Gates reopen automatically. During confirmed execution, streaming insert IDs are deterministically derived from the confirmation plan and recommendation identity. If a non-quota API failure releases a still-valid plan for retry, BigQuery can de-duplicate repeated rows from that execution.

A successful plan is consumed and cannot be replayed. Plans are operation-typed, so a plan generated by one mutation tool cannot be consumed by another. Under authenticated SSE, ownership uses the immutable token issuer/subject plus the MCP session; a refreshed token whose email changed can still confirm, while another identity or session cannot.

---

Example

"Preview an export of all active recommendations to the operations.gcp_recommendations table. Do not write anything until I confirm."

Review the returned row count and destination, then explicitly approve the plan_id if they are correct.

---

Related Pages

• Safety & Cost Safeguards
• Security and Safety
• Managing GCP Costs
• Configure Your Environment