Skip to main content
GCP support is in Beta. To enroll, request access from your Cloud Capital Customer Success Manager. Once your account is enabled, GCP appears as an option on the New Integration page. If you don’t see it yet, reach out to your Customer Success Manager.
Cloud Capital reads your Google Cloud cost and commitment data from resources you own — a BigQuery billing export table, a CUD subscriptions export dataset, your billing account, and your Compute and BigQuery commitments. You provide the coordinates for each, then grant your integration’s own Cloud Capital identity read-only access. Setup takes about 30 minutes, plus time for GCP to populate the exports if you’re enabling them for the first time. The five grants need administrator access in three different places — your billing account, your organization, and BigQuery. One person may well hold all three; if not, the grants are independent, so each can be handed to whoever holds that access.

What Cloud Capital accesses

Cloud Capital reads as an identity that belongs to your integration alone: what you grant it is readable by that integration and nothing else. Five grants are required:
All five grants are strictly read-only. Cloud Capital cannot create, modify, or delete any resources in your Google Cloud environment.
roles/billing.viewer includes visibility into your negotiated contract pricing, billing account credits and anomalies, Google’s own commitment recommendations, and billing account payment metadata. Cloud Capital uses these to price your usage at your actual rates rather than list rates. If your security review needs a narrower discussion of any specific permission, raise it with your Customer Success Manager. Cloud Capital runs its BigQuery queries in its own project rather than yours, so the query cost is ours, not yours. The grants above only need to let us read your data — no query or compute permissions are required on your project.

What’s available with GCP today


Before you begin

  • GCP permissions — Between you and your colleagues, you need Billing Account Administrator, Organization Administrator, and BigQuery Data Owner. The grants are independent, so they can be applied in any order by different people. Organization Administrator is the one most likely to sit outside your team. If you can’t get it, Step 4 covers granting on folders instead.
  • Export type — Cloud Capital reads either the Standard usage cost export or the Detailed usage cost (resource-level) export, whichever you run, and gives the same numbers from both. Standard is the default. If you run both, connect one of them; the integration reads one export, never both.
  • Two required exports — Cloud Capital needs a cost export (standard or detailed) and the Committed use discount (CUD) subscriptions export. Both are enabled from the same BigQuery export tab in Google Cloud. The CUD dataset does not exist until that export is switched on, so enable both before running the grants.
  • Check for existing exports first — GCP only exports data from the point an export is enabled, so an export that has been running for a while is worth finding. Check whether either export already exists in your billing project before creating a new one; connecting to an existing export gives Cloud Capital history from its start date rather than from today.
  • CLI tools — The grant commands use gcloud, bq, and jq. All three are preinstalled in GCP Cloud Shell.

Setup

1

Create a new integration in Cloud Capital

In Cloud Capital, go to the Integrations page — from Cost Allocation, use Manage Cloud Providers. Click Create New Integration and choose GCP.The new integration opens on the Integration Settings page named Untitled GCP Integration. Replace that with something descriptive — you can add multiple integrations per cloud provider, so the name is how you’ll tell them apart. You’ll enter your coordinates and grant access on this same page in the steps below.GCP Integration Settings showing the integration name field and the Billing Export and Commitment Information field groups
2

Enable both BigQuery exports in GCP

In the Google Cloud Console, go to Billing → Billing export → BigQuery export. Cloud Capital needs both of these:
  1. A cost export: Standard usage cost (its table is named like gcp_billing_export_v1_XXXXXX) or Detailed usage cost (named like gcp_billing_export_resource_v1_XXXXXX), in the dataset configured for the export. Either works; if you are enabling one now, choose Standard usage cost.
  2. Committed use discount (CUD) subscriptions export. This lives in a separate dataset and contains a cud_subscriptions_export table.
If either is already enabled, use it — its history goes back to the day it was switched on, which is history Cloud Capital can use. Enable whichever is missing, then note the project and datasets for both.
See Google’s billing export setup documentation for the setup steps. A newly enabled export starts empty and fills going forward — GCP does not backfill it.
The CUD subscriptions dataset does not exist until that export is enabled. Skipping it makes the grant command in Step 4 fail with a “not found” error.
3

Find your coordinates

The Cloud Capital integration form asks for five values and which cost export you run, split into two groups. You never type the export table’s name: Cloud Capital works it out from the billing account and the export you choose.Billing export — find the project and dataset in the BigQuery Console (expand your billing project in the explorer and find the export dataset), and the billing account ID under Billing in the Google Cloud Console.Commitment information — find the organization ID under IAM & Admin → Settings in the Google Cloud Console.
The CUD Subscriptions Dataset is the dataset, not the table. Cloud Capital reads the cud_subscriptions_export table inside it.
4

Grant Cloud Capital access

On the Integration Settings page, the Grant Access step shows your integration’s Cloud Capital identity, a principal of this form:
Copy it from the app rather than from this page — it is made from your integration’s ID, and a mismatch is the most common cause of a failed connection test. Save the integration first: until it has an ID there is no identity to grant.
Integrations set up before per-integration identities read through Cloud Capital’s shared service account, and keep working. Their setup page asks you to grant the integration’s own identity as well, and lists what it still lacks. Once a Test Connection shows it can read everything the shared account does, the integration moves over and the old grants can be removed.
Grant Access step showing the integration's identity, the Permissions and All-in-one script tabs, and the five collapsible grants
The commands below contain placeholders. Every <PROJECT>, <BILLING_ACCOUNT_ID>, <ORGANIZATION_ID>, <FOLDER_ID>, and <CLOUD_CAPITAL_PRINCIPAL> on this page must be replaced with your real values before the command will work.You don’t have to do that by hand. Fill in all six fields in the app first, and the Grant Access step populates every command with your own values, ready to copy. Until you do, the app shows the same <YOUR_PROJECT>-style placeholders and warns you they aren’t populated yet.
Run the commands in your terminal or in GCP Cloud Shell. Every grant is idempotent and safe to re-run.

If you can’t grant at the organization

This section covers the Compute commitment visibility grant only. The BigQuery one has no narrower form at all. See the note in its accordion above.The organization-level grant is strongly preferred, and it’s worth a conversation with whoever holds Organization Administrator before falling back. If that grant genuinely isn’t available to you, there are two narrower options — and IAM inherits down the resource hierarchy, so granting at a folder is much closer to the organization grant than granting per project.Grant on folders (preferred fallback). If your projects are organized under folders, a grant on a folder covers every project inside it — including sub-folders and projects created in it later. That preserves the property that actually matters: new projects are covered automatically, without anyone remembering to do anything. It needs Folder IAM Admin rather than Organization Administrator, which is far more commonly delegated.
List your folders with gcloud resource-manager folders list --organization=<ORGANIZATION_ID>, or find them under IAM & Admin → Manage Resources in the Google Cloud Console. If your estate is organized so that every billed project sits under a folder you can grant on, this is effectively as durable as the organization grant. Projects created outside those folders are still uncovered, so it’s worth checking whether that can happen in your setup.Grant per project (last resort). If there’s no usable folder structure, granting roles/compute.viewer on every project the billing account pays for gets you the same commitment visibility today. It needs Project IAM Admin on each project.
Per-project grants are ongoing work. Every project you create from now on is invisible to Cloud Capital until someone remembers to grant on it too, and a missed project means missing commitments rather than an obvious error. Cloud Capital names any project it can’t read in the connection test result, but that only helps if someone re-tests. If you have folders, grant on those instead — and move to the organization grant when you can.
Whichever level you grant at, Cloud Capital reads commitments project by project and reports any it can’t reach, so the connection test tells you whether your chosen scope actually covers the estate. Re-test after adding projects or restructuring folders.
5

Test the connection and save

Back on the Integration Settings page:
  1. Enter the values from Step 3 and choose your billing export. Test Connection stays disabled until the BigQuery coordinates are filled in.
  2. Grant access as described in Step 4, if you haven’t already.
  3. Click Test Connection. The test saves the values first and then checks them, including that the table is the export you chose, so what it reports on is what you entered. It does not change the integration’s status.
  4. A new integration starts with status Draft. A successful test sets the status dropdown to Enabled.
  5. Click Save to apply the status. Test Connection step with the Test Connection button and the Set integration status dropdown showing Draft
The test has three possible outcomes:
The connection test confirms access. It does not validate the exports’ contents or confirm that data has been ingested yet.

Move billing to Cloud Capital (optional)

Moving GCP billing under Cloud Capital’s management is offered to selected customers. You grant the permissions below and Cloud Capital links the projects to the payer billing account for you; linking them yourself instead is also an option. Both are explained in Onboarding GCP billing to Cloud Capital. The Move billing to Cloud Capital (optional) step appears only after Cloud Capital has enabled it for your organization.
Only if you are moving your GCP billing under Cloud Capital’s management. In the Move billing to Cloud Capital (optional) step, turn on Let Cloud Capital change project billing to see the grants and their status. These grants go to a different identity from the forecasting grants above: the identity Cloud Capital uses to change billing for this integration. The step shows it in full, and its commands already use it. It looks like this, ending in your integration’s ID:
The principal is unique to your integration, so your grants let Cloud Capital move projects for your integration and no other. Both need an Organization Administrator. Grant them on your organization, so projects you create later are covered too. Granting on specific folders is supported, but projects outside the granted folders are not moved, now or later. Test Connection reports how many of the projects Cloud Capital can see are ready to move.

What to expect after setup

  • Data timing — Cost data is ingested on a scheduled nightly cycle, not instantly on save. Expect your first data in dashboards within about 24 hours of a successful connection, provided the billing export table already contains data.
  • Empty at first is normal — If you just enabled the exports, GCP may not have written rows yet. Cloud Capital will pick them up on the next nightly cycle.
  • Commitments — GCP commitments appear on the Commitments page once the inventory refresh runs. Three sources are needed for a complete picture: the Compute API supplies resource-based commitments, the CUD subscriptions export supplies spend-based ones, and the BigQuery Reservation API supplies capacity commitments. None is a superset of another, so a missing grant on any one of them leaves a blind spot rather than a partial view.

Troubleshooting


Security

For a full overview of how Cloud Capital handles data access, encryption, audit logging, and compliance, see the Security page.