Skip to content
Guides

Connect Google Cloud

Google Cloud and Firebase costs come from your billing export in BigQuery. ShipVitals reads it as your workspace's own Google principal, a service account made for this workspace alone, so you grant it read access instead of handing over a key. Usage (Cloud Monitoring) and deploy history (Hosting and Cloud Run) come the same way.

Only the owner and admins can do this (see Connect a service). It takes about 3 minutes once the billing export exists.

Open the setup

In Connections, press Set up Google Cloud on the first visit, or find Google Cloud in All services, or press Connect Google Cloud in Suggested. The page says Connect Google Cloud ("Costs, usage and deploys · …") with three numbered steps: Billing export, Grant read access and Check access ("Step 1 of 3").

Your place is saved on every step: the header then says Saved · continues on any device.

Step 1: Billing export

The step asks Where is your billing export?

  1. In Billing export dataset, type the dataset as project.dataset, for example my-project.billing_export (datasets used before in the workspace are offered as you type). You can also paste what you have: the export table's name as BigQuery shows it (project.dataset.table), a BigQuery address from the Cloud Console, or the Project ID and Dataset name copied from Billing export. ShipVitals reads the dataset from it, and the table when it names one.
  2. Leave Also read usage (Cloud Monitoring) and Also read deploy history (Hosting and Cloud Run) ticked to get those too. Each says which roles it adds.
  3. If one dataset holds several billing accounts, open One dataset holding several billing accounts? and type the Export table to read. A pasted table name fills it for you.
  4. Press Continue (or Enter).

Find your billing export

Open Billing export in the Cloud Console, under the field, opens the page where Google shows it: under the export that is enabled, the Project ID and Dataset name together are project.dataset.

With several billing accounts, or when you aren't sure which project holds it, open Where do I find it?. It has a command, Find my billing exports, that lists every dataset a billing export writes to, one project.dataset a line. Copy it, press Open Cloud Shell, run it there, and paste a line into the field.

No billing export yet

Open Not set up yet? and follow its steps:

  1. Press Open Billing export in the Cloud Console and choose the billing account that pays for your projects.
  2. Under Detailed usage cost, press Enable detailed export. (Standard usage cost works too; with both on, ShipVitals reads the account once.)
  3. Choose a project to hold it, create a dataset there (billing_export is a good name) and save.
  4. Come back and write it in the field as that project, a dot, then the dataset.

Google writes the first rows a few hours after you turn the export on. Until then Check access says "ShipVitals can read … but there's no billing export table in it yet."; your place is kept, so check again later. Google exports cost only from that day (plus about a month back).

If the dataset isn't in the right shape, the field says "Write it as project.dataset, for example …".

Step 2: Grant read access

The step shows "Grant read access to …'s own Google principal:" with its address and Copy the principal.

  1. Choose how to run the grant: gcloud, Terraform or Console steps (numbered clicks in the Cloud Console).
  2. Copy the snippet (focus it and press ⌘C / Ctrl C, or press Copy snippet). Open Cloud Shell opens a Cloud Shell in a new tab to paste it into.
  3. Run it. Under the snippet, a note says what it allows and how to take it back.
  4. Press Continue to Check access (or Enter).

The bar at the bottom says "Waiting for access. The hub shows this as “Waiting for access · Google Cloud” until Check access passes." You can leave now and come back later (see Come back later).

Someone else owns billing

Press Copy for a colleague. ShipVitals copies a plain message with the snippet, what it grants and how to remove it: "Copied. Paste it into your own chat or email." ShipVitals sends nothing to them. The message also appears below the button; if copying is blocked ("Copying was blocked. Select the message below and copy it."), select and copy it yourself.

On a phone

A phone also shows Email me this snippet. It's sent to your own address: "Sent to …. Run it on a desktop; Check access works here once it has run." Then run it on a desktop and come back to the phone for step 3.

Step 3: Check access

  1. Press Check access (or ⌘Enter / Ctrl Enter, from step 2 or 3).
  2. ShipVitals checks each grant one at a time: the dataset, the export table, its newest row, the scan size, the projects, then usage and deploys on each. The checks appear as they finish.
  3. The result:
    • When everything passed: "Billing, usage and deploys work for all …." Press Done (or Enter). You land on Connected, with a connection for each part you chose: Google Cloud billing, and Google Cloud usage and Firebase Hosting and Cloud Run releases (deploys) when chosen. On your plan they count as one connection.
    • When only part of it works: billing works, but some projects are missing usage or deploys ("Billing works for all …. Usage is missing on …."). This is normal, and what works is saved. Press Copy the fix beside the lines that grant the access still missing to copy just those lines, run them, then press Check again. Or press Done for now and fix it later from the connection's Copy the fix (see Connection health).
    • When it failed: the line says what to do, with the missing lines to copy too. Fix it and press Check again.

Other ways to connect: a JSON key

If you'd rather use a service account you made yourself:

Give the account the same read roles the snippet grants. With a key, ShipVitals' queries run in the account's own project, not in ShipVitals', so it also needs to run BigQuery jobs there: grant it BigQuery Job User on its own project (and enable the BigQuery API there). That is the only permission beyond reading the check accepts, and only in that project; the queries are billed to it.

  1. On step 3, open Other ways to connect.
  2. Drop the key on Choose the JSON key, or press it and choose the file. It says "… is ready. It's sent once, to check and store it, and never kept in your saved place."
  3. Press Connect with this key (Remove the key lets it go).

ShipVitals accepts the key only if its account can do no more than read:

  • Connected with the key. Press Done.
  • "Billing is connected. This key couldn't read usage; grant it and connect again to add them." Billing is saved; grant the rest and connect again.
  • Refused because the account can do more: "Remove these permissions, or the roles that hold them:" with the list, and "ShipVitals needs only …." Remove them in Google Cloud and try again, or use the snippet instead.

Come back later

The wizard keeps its place (the dataset, the options, the snippet format and the step, never a key) for 14 days, for you, on any device.

  1. Open Connections. The line under the heading says Waiting for access · Google Cloud while the wizard waits at step 2 or 3, and Suggested shows "Continue Google Cloud · step 2 of 3" under Resume.
  2. Press either. The wizard opens at the same step, with the same snippet.

When it doesn't work

  • The page says
    "Write it as project.dataset, for example …"
    What to do
    Type the dataset as the project, a dot, then the dataset's name.
  • The page says
    "Use the table's name as BigQuery shows it: letters, digits, _ and -."
    What to do
    Fix the Export table, or leave it empty.
  • The page says
    "The snippet didn't load."
    What to do
    Reload the page. Your place is kept.
  • The page says
    "The check didn't finish. Try again in a minute."
    What to do
    Wait a minute and press Check again.
  • The page says
    "You've run many checks in the last hour. Try again at …."
    What to do
    Wait until then.
  • The page says
    "You've emailed this snippet several times in the last hour. Try again later."
    What to do
    Copy it instead, or wait.
  • The page says
    "Saved, but paused: your plan has no room for another connection. …"
    What to do
    Remove a connection or change plan; it starts syncing then.
  • The page says
    "Google Cloud can't be connected on this server yet."
    What to do
    This ShipVitals server isn't set up for Google Cloud. Ask its operator.