Connect Google Cloud
CloudQuell reads your Google Cloud spend from your Detailed usage cost export in BigQuery — the same invoice-grade data Google bills you from. The connection is keyless: you grant a CloudQuell service-account email two read-only BigQuery roles, and access works through Google’s Workload Identity Federation. No key, secret, or password ever changes hands, so there is nothing to store, rotate, or leak — revoking the IAM grants revokes CloudQuell.
Once connected, GCP spend flows into the same ledger, dashboards, reports, budgets, and allocation views as your other providers. Projects appear as their own sub-accounts — the GCP analog of AWS linked accounts — and resource + project labels arrive as tags for allocation rules and tag coverage.
Prerequisites
Section titled “Prerequisites”- A CloudQuell admin — creating integrations requires the
super_adminoradminrole. See roles. - The Google Cloud integration enabled for your CloudQuell organization (see the note above).
- A Google Cloud administrator who can edit Billing export settings and grant IAM roles on the export project and dataset.
How far back does history go?
Section titled “How far back does history go?”Unlike AWS (12 months on day one), Google only backfills the current and previous month when a billing export is first enabled, and a new export takes 24–48 hours to populate. Your CloudQuell history starts where your export starts and grows forward from there — if you’ve been exporting billing to BigQuery for a year, you get that year.
The three steps
Section titled “The three steps”1. Enable the Detailed usage cost export
Section titled “1. Enable the Detailed usage cost export”If you already export billing data to BigQuery, skip to step 2.
- In the Google Cloud console, open Billing → Billing export. You’ll see three BigQuery export types — FOCUS usage cost (preview), Standard usage cost, and Detailed usage cost. CloudQuell reads the Detailed export (FOCUS support is on our roadmap; note Google applies a 2-year TTL to FOCUS export data).
- Under Detailed usage cost, click Enable detailed export.
- Pick the project to host the export — the picker only lists projects linked
to an active billing account. If the project has no datasets yet, create one
right from the Dataset dropdown: any dataset name works (letters, numbers,
underscores), but Data location must be the US or EU multi-region —
billing exports don’t support single regions like
us-central1. - Select the dataset and Save. The Detailed usage cost section should now show Enabled, with your project and dataset names listed.
- Note the project id and dataset name; you’ll enter them in step 3.
2. Grant the CloudQuell service account read access
Section titled “2. Grant the CloudQuell service account read access”In CloudQuell, open Integrations → Google Cloud → Connect. The wizard shows the service-account email to grant (also available from your admin — it’s the same one for your whole organization). Grant it exactly two roles:
| Role | Where | Why |
|---|---|---|
BigQuery Job User (roles/bigquery.jobUser) |
The export project (IAM & Admin → IAM → Grant access) | Lets CloudQuell run the daily export queries. |
BigQuery Data Viewer (roles/bigquery.dataViewer) |
The export dataset (BigQuery → dataset → Sharing → Permissions) | Lets CloudQuell read the billing export tables — and nothing else. |
Both roles are read-only, scoped to the export, and grant no access to any other dataset or resource in your project.
Google may warn that the principal is outside your organization when you add it — that’s expected (the service account lives in CloudQuell’s GCP project); confirm through the warning. The grants take effect within a minute or two.
3. Enter the export coordinates and verify
Section titled “3. Enter the export coordinates and verify”Back in the wizard, enter:
- Billing account id — format
XXXXXX-XXXXXX-XXXXXX, shown at Billing → Settings. - Export project id — the project hosting the dataset.
- Dataset name — the BigQuery dataset the export writes into.
Click Verify & Connect. CloudQuell runs a BigQuery dry-run against your export table — it scans no data and costs nothing — to confirm the export exists and the grants work, then starts pulling your history. Costs typically appear within minutes.
If you enabled the export moments ago, the wizard completes with “Setup complete — Google is preparing your export” instead: your access is verified, and Google just hasn’t written the export’s first table yet (up to 24–48 hours for new exports). No action needed — CloudQuell starts syncing automatically as soon as the data appears.
What syncs, and when
Section titled “What syncs, and when”- Daily sync — every day CloudQuell re-pulls the current and previous invoice months, absorbing Google’s 24–48 hour restatement window. The newest days firm up as Google finalizes them.
- Query costs — the daily pull runs as a partition-pruned, aggregated BigQuery query in your project. For typical accounts this stays comfortably inside BigQuery’s free monthly query tier.
- Committed Use Discounts — CUD-covered usage lands with its commitment identity, so commitment coverage and effective-coverage metrics include GCP. (CUD expiry dates aren’t part of Google’s export, so expiring-commitment alerts don’t cover GCP yet.)
- Labels as tags — resource labels and project labels merge into CloudQuell tags (resource labels win on conflicts) for allocation and tag coverage.
Disconnecting
Section titled “Disconnecting”Delete the integration from Integrations — CloudQuell removes the stored export coordinates and all ingested GCP cost data. Because the connection is keyless there is no credential to clean up on your side; optionally remove the two IAM grants in Google Cloud to revoke access permanently.