GCP Accounts

CostLens reads your Google Cloud cost data from your BigQuery billing export and your recommendations from the Recommender API, using a dedicated service account with read-only roles. The guided Add Account wizard connects with a Google sign-in — CostLens provisions the service account, binds the roles, and (where your org policy allows it) mints its own key automatically. No script to run, no key to paste.

How it works#

Connect a new GCP project#

Step 1 — Add Account → GCP → choose access level#

From the Accounts page, click Add Account, choose GCP, then choose Read-Only or Read/Write:

Step 2 — Authorize (Google sign-in)#

Click Authorize. This redirects your browser to Google's own sign-in/consent page — sign in as a user with IAM Admin rights on the project(s) you want to connect (able to create service accounts and grant roles), and allow access.

Step 3 — CostLens provisions access automatically#

Google redirects you back into CostLens. From here everything is automatic — CostLens uses your one-time sign-in to:

1. List every project and billing account visible to your signed-in identity, and auto-detect the BigQuery billing-export dataset if one exists.
2. Create (or reuse, if reconnecting) a dedicated costlens-cost-reader service account in the project.
3. Bind it the read-only roles for your chosen access level.
4. Attempt to generate a service-account key for it automatically.
5. If your organization's policy blocks service-account key creation, automatically fall back to keyless instead — granting CostLens's own dedicated service account the same roles, so no key exists anywhere.

As soon as provisioning succeeds, the project connects and its first sync starts. IAM changes can take a few seconds to propagate — the wizard keeps checking automatically during that window.

Connect a whole org or folder#

To grant CostLens access to every project under a GCP folder or organization in one step instead of one at a time, use the Connect an organization flow from the Accounts page: pick an already-connected GCP account whose service account is bound at the org/folder level, optionally run the generated grant script once, then Discover & connect — CostLens enumerates and connects every project it can now see.

Reconnecting a removed project#

If a project was previously connected and later removed, reconnecting it (Authorize again, sign in the same way) reuses the existing costlens-cost-reader service account rather than creating a duplicate.

If you connect a project that turns out to already be active in your CostLens organization, you'll see "This account already exists — it's already connected. Nothing was added again" on the success screen.

Alternative: run the setup script yourself#

If Authorize isn't available in your environment, or your organization prefers to review and run IAM changes itself, use the manual path instead. It offers the same two outcomes Authorize would have tried automatically — a dedicated service account with a key, or a keyless grant to CostLens's own service account — just run by hand.

Keyless (recommended when available)#

If CostLens's own service account is configured for keyless access, the manual step offers a "Use keyless (recommended)" toggle. Choosing it generates a script that grants CostLens's own service-account email the required roles in your project — no key is ever created, downloaded, or pasted:

#!/usr/bin/env bash
# CostLens — GCP keyless grant (no service-account key created)
set -euo pipefail
 
PROJECT_ID="<PROJECT_ID>"
COSTLENS_SA="<shown in the wizard>"
 
gcloud projects add-iam-policy-binding "$PROJECT_ID" \
  --member="serviceAccount:${COSTLENS_SA}" --role="roles/bigquery.dataViewer"
# ...plus the other read-only roles listed in Step 1 above, all bound to $COSTLENS_SA

The wizard generates the exact script (with your project/billing/dataset IDs filled in) and phones home automatically once it's run — no need to return to CostLens or paste anything back.

Key-based (dedicated service account)#

If you'd rather create your own dedicated service account and key:

#!/usr/bin/env bash
# CostLens — GCP connection setup (BigQuery billing-export viewer, least privilege)
set -euo pipefail
 
PROJECT_ID="<PROJECT_ID>"
BILLING_ACCOUNT_ID="<BILLING_ACCOUNT_ID>"
BQ_DATASET="<BQ_DATASET>"   # dataset holding the BigQuery billing export
SA_NAME="costlens-cost-reader"
 
gcloud config set project "$PROJECT_ID"
 
# 1. Create a dedicated service account
gcloud iam service-accounts create "$SA_NAME" --display-name "CostLens cost reader"
SA_EMAIL="${SA_NAME}@${PROJECT_ID}.iam.gserviceaccount.com"
 
# 2. Grant read-only roles
#    - BigQuery Data Viewer on the billing-export dataset
bq add-iam-policy-binding \
  --member="serviceAccount:${SA_EMAIL}" \
  --role="roles/bigquery.dataViewer" \
  "${PROJECT_ID}:${BQ_DATASET}"
#    - Run queries + view billing + view recommendations
gcloud projects add-iam-policy-binding "$PROJECT_ID" \
  --member="serviceAccount:${SA_EMAIL}" --role="roles/bigquery.jobUser"
gcloud billing accounts add-iam-policy-binding "$BILLING_ACCOUNT_ID" \
  --member="serviceAccount:${SA_EMAIL}" --role="roles/billing.viewer"
gcloud projects add-iam-policy-binding "$PROJECT_ID" \
  --member="serviceAccount:${SA_EMAIL}" --role="roles/recommender.viewer"
#    - View the resource inventory (Cloud Asset Inventory) — for the Cloud Inventory page
gcloud projects add-iam-policy-binding "$PROJECT_ID" \
  --member="serviceAccount:${SA_EMAIL}" --role="roles/cloudasset.viewer"
#    - Read compute resources + monitoring metrics — required for the compute & GKE
#      optimization checks (idle / right-sizing / Spot node pools, MIG autoscaling)
gcloud projects add-iam-policy-binding "$PROJECT_ID" \
  --member="serviceAccount:${SA_EMAIL}" --role="roles/compute.viewer"
gcloud projects add-iam-policy-binding "$PROJECT_ID" \
  --member="serviceAccount:${SA_EMAIL}" --role="roles/monitoring.viewer"
 
# 3. Create a service-account key — paste the JSON into CostLens
gcloud iam service-accounts keys create costlens-key.json --iam-account="$SA_EMAIL"

Paste the contents of costlens-key.json (plus Project ID, Billing account ID, and dataset) into the CostLens manual-entry step and click Connect account.

Recommendations#

GCP recommendations come from the Recommender API (read-only), surfaced as individual checks:

• Idle VM Instance, VM Right-sizing, Idle Cloud SQL, Unattached Persistent Disk, Idle Static IP, and Committed Use Discounts.
• A CostLens custom check for Orphaned Disk Snapshots covers a Recommender gap.

The roles/recommender.viewer, roles/compute.viewer, and roles/monitoring.viewer scopes granted at Read-Only cover all of these.

Kubernetes (GKE) cost & optimization#

The roles granted at Read-Only already give CostLens everything it needs to discover your GKE clusters and recommend node-pool savings (idle / right-sizing / Spot). One capability needs a one-time switch flipped on the cluster:

Applying fixes (optional)#

Choosing Read/Write during onboarding already grants what Auto-Fix needs. Scanning itself is always read-only regardless of access level. Today's GCP remediations:

If you connected with Read-Only and want Auto-Fix later, reconnect with Read/Write — Authorize again and choose Read/Write; CostLens adds the missing roles to the existing service account rather than creating a new one.

Enabling automatic Auto-Fix with your own service account (least privilege)#

If you used the manual/own-service-account path, create a custom role with only VM power control:

gcloud iam roles create costlens_autofix --project="<PROJECT_ID>" \
  --title="CostLens Auto-Fix (VM power)" \
  --permissions=compute.instances.get,compute.instances.start,compute.instances.stop \
  --stage=GA
gcloud projects add-iam-policy-binding "<PROJECT_ID>" \
  --member="serviceAccount:costlens-cost-reader@<PROJECT_ID>.iam.gserviceaccount.com" \
  --role="projects/<PROJECT_ID>/roles/costlens_autofix"

Common errors and fixes#