Integrate GCP Data

​

What Cloud Capital accesses

​

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 — Use the Standard usage cost billing export to BigQuery, not the detailed / resource-level export.
• Two required exports — Cloud Capital needs both the Standard usage cost export 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.

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. Standard usage cost export. Its table is named like gcp_billing_export_v1_XXXXXX, in the dataset configured for the export.
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 six values, split into two groups.Billing export — find these in the BigQuery Console: expand your billing project in the explorer, select the export dataset, and copy the export table’s name.

Field	What it is	Example
GCP Project ID	The project containing your billing export dataset	my-billing-project
BigQuery Dataset ID	The dataset where the billing export lives	billing_export
Billing Export Table	The specific export table (not the dataset)	gcp_billing_export_v1_018ECB_B18E18_C07590

Commitment information — find the billing account ID under Billing and the organization ID under IAM & Admin → Settings in the Google Cloud Console.

Field	What it is	Example
Billing Account ID	The billing account paying for the projects you want analyzed	XXXXXX-XXXXXX-XXXXXX
Organization ID	Your GCP organization’s numeric ID	123456789012
CUD Subscriptions Dataset	The dataset created by the CUD subscriptions export	billing_export_cud

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 the service account email to grant to:

cloud-capital-forecasting@cloudcapital-production.iam.gserviceaccount.com

Copy it from the app rather than from this page — it is specific to your Cloud Capital environment, and a mismatch is the most common cause of a failed connection test.

The commands below contain placeholders. Every <PROJECT>, <BILLING_ACCOUNT_ID>, <ORGANIZATION_ID>, <FOLDER_ID>, and <CLOUD_CAPITAL_SERVICE_ACCOUNT_EMAIL> 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.

• Permissions (recommended)
• All-in-one script

These four grants need administrator access in three different places — your billing account, your organization, and BigQuery. Each grant is independent and can be applied in any order, so if the access is spread across your team you can route each command to whoever holds it.

Billing account access — roles/billing.viewer

Granted by Billing Account Administrator, on your billing account.Gives Cloud Capital your contract pricing, commitment insights, anomalies, and credits.

gcloud billing accounts add-iam-policy-binding <BILLING_ACCOUNT_ID> \
  --member="serviceAccount:<CLOUD_CAPITAL_SERVICE_ACCOUNT_EMAIL>" \
  --role="roles/billing.viewer"

Compute commitment visibility — roles/compute.viewer

Granted by Organization Administrator, on your organization.Gives Cloud Capital your resource-based Compute commitments. Grant this at the organization if you possibly can — it covers your whole estate, including projects you create later, and it’s the only version of this grant that keeps working without maintenance.

gcloud organizations add-iam-policy-binding <ORGANIZATION_ID> \
  --member="serviceAccount:<CLOUD_CAPITAL_SERVICE_ACCOUNT_EMAIL>" \
  --role="roles/compute.viewer" \
  --condition=None

Genuinely can’t get Organization Administrator? Granting on folders is the next best thing — IAM inherits downward, so a folder grant still covers projects created in it later. Failing that, you can grant per project. See If you can’t grant at the organization, below this tab group.

Billing export table access — roles/bigquery.dataViewer

Granted by BigQuery Data Owner on the dataset, scoped to the single export table.Gives Cloud Capital your cost data.

bq add-iam-policy-binding \
  --member="serviceAccount:<CLOUD_CAPITAL_SERVICE_ACCOUNT_EMAIL>" \
  --role="roles/bigquery.dataViewer" \
  <PROJECT>:<DATASET>.<TABLE>

CUD subscriptions dataset access — READER (dataset ACL)

Granted by BigQuery Data Owner on the dataset.Gives Cloud Capital your spend-based commitments.The CUD subscriptions export is an Analytics Hub linked dataset, where per-table IAM is structurally unavailable — bq add-iam-policy-binding against a table in it fails. Access is granted through the legacy dataset ACL instead, by reading the dataset resource, appending an access entry, and writing it back. READER is the ACL equivalent of roles/bigquery.dataViewer.

bq show --format=prettyjson <PROJECT>:<CUD_DATASET> \
  | jq --arg e "<CLOUD_CAPITAL_SERVICE_ACCOUNT_EMAIL>" \
      'if any(.access[]; .userByEmail == $e)
       then . else .access += [{"role":"READER","userByEmail":$e}] end' \
  > /tmp/cc-cud-dataset.json
bq update --source /tmp/cc-cud-dataset.json <PROJECT>:<CUD_DATASET>

bq update --source replaces the entire dataset resource. Use the command as given — the jq expression preserves existing access entries and no-ops if Cloud Capital is already present. Don’t hand-edit the file to contain only the new entry.

If you hold all three — Billing Account Administrator, Organization Administrator, and BigQuery Data Owner — the app’s All-in-one script tab bundles all four grants into one block, which is the fastest path. Requires the gcloud, bq, and jq CLIs; jq is preinstalled in GCP Cloud Shell.Copy it from the app rather than reconstructing it here — it is generated from your entered coordinates and the service account email for your environment.

​

If you can’t grant at the organization

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.

# Repeat for each folder containing billed projects.
gcloud resource-manager folders add-iam-policy-binding <FOLDER_ID> \
  --member="serviceAccount:<CLOUD_CAPITAL_SERVICE_ACCOUNT_EMAIL>" \
  --role="roles/compute.viewer" \
  --condition=None

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.

# Grants on every project currently billed to this account.
for project in $(gcloud billing projects list \
    --billing-account=<BILLING_ACCOUNT_ID> \
    --format="value(projectId)"); do
  gcloud projects add-iam-policy-binding "$project" \
    --member="serviceAccount:<CLOUD_CAPITAL_SERVICE_ACCOUNT_EMAIL>" \
    --role="roles/compute.viewer" \
    --condition=None
done

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 all six values from Step 3. 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. You can test before saving.
4. A new integration starts with status Draft. A successful test switches it to Enabled automatically.
5. Click Save.

The test has three possible outcomes:

Result	What it means
Connection successful	Cloud Capital can read your billing export, your CUD subscriptions export, your billing account, and Compute commitments across every project on the billing account.
Cost data is connected, but some commitment access is missing	The billing export reads fine, so the integration works and can be saved. Each missing piece is listed by name so you know which command from Step 4 to re-run.
Connection failed	Cloud Capital cannot read your billing export. This is the one blocking failure — the integration cannot ingest cost data until it’s resolved.

The connection test confirms access. It does not validate the exports’ contents or confirm that data has been ingested yet.

​

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. Both commitment sources are needed for a complete picture: the Compute API supplies resource-based commitments and the CUD subscriptions export supplies spend-based ones. Neither is a superset of the other, so a missing grant on either side leaves a blind spot rather than a partial view.

​

Troubleshooting