Google Cloud setup guide

This guide walks you through creating a Service Account with read-only access for CLARITY and adding it to your instance.

Prerequisites

A GCP project with Owner or IAM Admin role
gcloud CLI installed and authenticated, or access to the GCP Console
A billing account linked to the project

Option 1: gcloud cLI (Recommended)

Create a dedicated Service Account, assign roles, enable APIs, and download the key:

bash

# Set your project iD
export PROJECT_ID="your-project-id"
gcloud config set project $PROJECT_ID

# Create the service account
gcloud iam service-accounts create clarity-finops \
  --display-name="CLARITY FinOps" \
  --description="Read-only access for CLARITY cost management"

# Assign required roles
SA="serviceAccount:clarity-finops@${PROJECT_ID}.iam.gserviceaccount.com"

for ROLE in \
  roles/viewer \
  roles/bigquery.dataViewer \
  roles/bigquery.jobUser \
  roles/monitoring.viewer \
  roles/serviceusage.serviceUsageConsumer; do
  gcloud projects add-iam-policy-binding $PROJECT_ID \
    --member="$SA" --role="$ROLE" --quiet
done

# Assign optional roles (recommended — enable for services you use)
for ROLE in \
  roles/recommender.viewer \
  roles/logging.viewer \
  roles/cloudasset.viewer \
  roles/container.clusterViewer \
  roles/cloudsql.viewer \
  roles/storage.objectViewer \
  roles/cloudfunctions.viewer \
  roles/spanner.viewer \
  roles/bigtable.viewer \
  roles/run.viewer; do
  gcloud projects add-iam-policy-binding $PROJECT_ID \
    --member="$SA" --role="$ROLE" --quiet
done

Enable the required APIs:

bash

# Enable all required + optional APIs (17 total)
gcloud services enable \
  bigquery.googleapis.com \
  compute.googleapis.com \
  monitoring.googleapis.com \
  cloudresourcemanager.googleapis.com \
  serviceusage.googleapis.com \
  container.googleapis.com \
  sqladmin.googleapis.com \
  cloudfunctions.googleapis.com \
  recommender.googleapis.com \
  cloudbilling.googleapis.com \
  billingbudgets.googleapis.com \
  cloudasset.googleapis.com \
  spanner.googleapis.com \
  bigtableadmin.googleapis.com \
  run.googleapis.com \
  storage-api.googleapis.com \
  logging.googleapis.com

Create and download the Service Account key:

bash

# Create the JSON key file
gcloud iam service-accounts keys create clarity-key.json \
  --iam-account=clarity-finops@${PROJECT_ID}.iam.gserviceaccount.com

# Verify the key was created
cat clarity-key.json | python3 -c "import sys,json; d=json.load(sys.stdin); print(f'Project: {d[\"project_id\"]}\nEmail: {d[\"client_email\"]}')"

Protect Your Key File

The clarity-key.json file contains private credentials. Store it securely, do not commit it to version control, and delete it from your local machine after adding it to CLARITY.

Option 2: GCP console

Step 1: create a service account

Go to IAM & Admin > Service Accounts in the GCP Console
Click Create Service Account
Enter:
- Name: clarity-finops
- Description: Read-only access for CLARITY cost management
Click Create and Continue

Step 2: assign roles

On the Grant this service account access to project step, add the following roles:

Click Add Another Role for each:
- Viewer (Basic) — resource discovery across all services
- BigQuery Data Viewer — billing export queries
- BigQuery Job User — executes billing queries
- Monitoring Viewer — CPU/memory/disk metrics
- Service Usage Consumer — pre-flight API validation
Optionally add (for full feature coverage):
- Recommender Viewer — optimization recommendations
- Logs Viewer — audit log correlation
- Cloud Asset Viewer — universal resource discovery
- Cloud Spanner Viewer — if using Spanner
- Cloud Bigtable Viewer — if using Bigtable
- Cloud Run Viewer — if using Cloud Run
Click Continue, then Done

Billing Account Viewer must be assigned separately at the billing account level (not the project). See Billing Account Access below.

Step 3: create a key

Click on the newly created clarity-finops service account
Go to the Keys tab
Click Add Key > Create new key
Select JSON format
Click Create — the key file downloads automatically

Step 4: enable APIs

Go to APIs & Services > Library
Search for and enable each API listed in the Required APIs section below

Required roles

Role	Purpose	Required
roles/viewer	Resource discovery — Compute Engine, Cloud SQL, GKE, Cloud Storage, Cloud Functions, and all other services	Yes
roles/bigquery.dataViewer	Billing export queries — reads cost data from BigQuery billing export tables	Yes
roles/bigquery.jobUser	Runs BigQuery queries — required to execute billing export queries	Yes
roles/billing.viewer	Billing account access — billing account metadata, pricing catalog, and budget information	Yes
roles/monitoring.viewer	Performance metrics — CPU, memory, network, and disk utilization from Cloud Monitoring	Yes
roles/serviceusage.serviceUsageConsumer	Pre-flight validation — checks which APIs are enabled at credential setup	Yes
roles/recommender.viewer	GCP recommendations — right-sizing, idle resource, and commitment recommendations	Optional
roles/logging.viewer	Audit logs — Cloud Audit Log activity for event correlation	Optional
roles/cloudasset.viewer	Universal resource discovery — cross-service inventory via Cloud Asset API	Optional
roles/container.clusterViewer	GKE cluster and workload details (if using `roles/viewer`, already covered)	Optional
roles/cloudsql.viewer	Cloud SQL instance details (if using `roles/viewer`, already covered)	Optional
roles/storage.objectViewer	GCS bucket and object listing	Optional
roles/cloudfunctions.viewer	Cloud Functions inventory	Optional
roles/spanner.viewer	Cloud Spanner instances and databases	Optional
roles/bigtable.viewer	Cloud Bigtable clusters and instances	Optional
roles/run.viewer	Cloud Run services and revisions	Optional

Why roles/viewer?

roles/viewer is a broad GCP basic role that grants read access across all services in the project. CLARITY uses this to discover all resources that may generate costs — GCE instances, Cloud SQL databases, GKE clusters, Cloud Storage buckets, Cloud Functions, VPC networks, firewall rules, and more. This ensures complete visibility into idle, oversized, and underutilized resources.

Required APIs

CLARITY needs the following APIs enabled in your project. The pre-flight validation checks all of these when you add credentials.

Required (sync will fail without these)

API	Service	Purpose
`bigquery.googleapis.com`	BigQuery	Billing export data queries
`compute.googleapis.com`	Compute Engine	VM instance discovery and metrics
`monitoring.googleapis.com`	Cloud Monitoring	CPU, memory, network utilization
`cloudresourcemanager.googleapis.com`	Cloud Resource Manager	Project metadata and IAM
`serviceusage.googleapis.com`	Service Usage	Pre-flight validation — checks which APIs are enabled

Optional (features degrade gracefully without these)

API	Service	Purpose
`container.googleapis.com`	Kubernetes Engine	GKE cluster and workload discovery
`sqladmin.googleapis.com`	Cloud SQL Admin	Cloud SQL instance discovery
`cloudfunctions.googleapis.com`	Cloud Functions	Serverless function discovery
`recommender.googleapis.com`	Recommender	Right-sizing and idle resource recommendations
`cloudbilling.googleapis.com`	Cloud Billing	Billing account details and pricing catalog
`billingbudgets.googleapis.com`	Cloud Billing Budget	Budget monitoring and alerts
`cloudasset.googleapis.com`	Cloud Asset	Cross-service resource inventory
`spanner.googleapis.com`	Cloud Spanner	Spanner instance and database discovery
`bigtableadmin.googleapis.com`	Cloud Bigtable Admin	Bigtable cluster and instance discovery
`run.googleapis.com`	Cloud Run Admin	Cloud Run service and revision discovery
`storage-api.googleapis.com`	Cloud Storage JSON API	GCS bucket and object discovery
`logging.googleapis.com`	Cloud Logging	Audit log activity and event correlation

Bigtable API Naming

bigtableadmin.googleapis.com (Cloud Bigtable Admin API) is NOT the same as bigtabletableadmin.googleapis.com (Cloud Bigtable Table Admin API). CLARITY uses the Admin API for instance and cluster discovery. Enabling the wrong one will cause Bigtable resources to not appear.

Total: 5 required + 12 optional = 17 APIs. CLARITY validates all 17 at credential setup.

Enable all at once via CLI:

bash

gcloud services enable \
  bigquery.googleapis.com \
  compute.googleapis.com \
  monitoring.googleapis.com \
  cloudresourcemanager.googleapis.com \
  serviceusage.googleapis.com \
  container.googleapis.com \
  sqladmin.googleapis.com \
  cloudfunctions.googleapis.com \
  recommender.googleapis.com \
  cloudbilling.googleapis.com \
  billingbudgets.googleapis.com \
  cloudasset.googleapis.com \
  spanner.googleapis.com \
  bigtableadmin.googleapis.com \
  run.googleapis.com \
  storage-api.googleapis.com \
  logging.googleapis.com

BigQuery billing export

GCP billing data is accessed through BigQuery billing export. This must be configured manually by a Billing Account Administrator.

Setting up billing export

Go to the GCP Console > Billing > Billing export
Select the Standard usage cost tab
Click Edit Settings
Choose the project where the export dataset should live (use the same project as your CLARITY service account)
Create a new dataset or select an existing one (e.g., billing_export)
Click Save

What to expect

Billing export data backfills approximately 24-48 hours after initial configuration
New cost records appear daily, typically with a 1-day delay
The export contains resource-level cost data broken down by service, SKU, project, and region

Auto-Discovery

CLARITY automatically discovers your BigQuery billing export dataset and table name during the pre-flight validation. You do not need to configure the dataset name manually — CLARITY scans all datasets in the project for billing export tables.

Billing Account Admin Required

Enabling billing export requires the Billing Account Administrator role at the billing account level (not the project level). If your service account or user does not have this role, ask your billing admin to enable the export. The CLARITY service account itself does not need this role — it only needs roles/bigquery.dataViewer to read the exported data.

Adding to CLARITY

Log in to CLARITY and navigate to Provider Setup
Click Add Account and select GCP
Enter the following:
- Project ID — your GCP project ID
- Service Account Email — clarity-finops@YOUR_PROJECT_ID.iam.gserviceaccount.com
- Service Account Key — upload the JSON key file or paste its contents
Click Save

CLARITY runs a pre-flight validation that automatically:

Authenticates with the service account credentials
Checks all required and optional APIs for enablement status
Scans for BigQuery billing export configuration
Reports any missing permissions or disabled APIs before starting the sync

Pre-flight Validation

If any required APIs are disabled, CLARITY will flag them immediately with specific instructions on what to enable. You can fix the issues and re-validate without re-entering credentials.

Verification

After the initial sync completes (typically 2-5 minutes), verify that data is flowing:

Dashboard — Cost breakdown by GCP service (Compute Engine, Cloud SQL, GKE, Cloud Storage, etc.)
Resources — Your GCE instances, Cloud SQL databases, GKE clusters, and other resources with cost attribution
Insights — Optimization recommendations from the Recommender API and utilization-based analysis
Forecast — Cost projections based on your BigQuery billing export history

If resources appear but costs show as zero, check that:

BigQuery billing export is enabled and has had time to backfill (24-48 hours)
The roles/bigquery.dataViewer role is assigned to the service account
The billing export dataset is in the same project as the service account

Cleanup

To remove CLARITY access from your GCP project:

bash

export PROJECT_ID="your-project-id"

# Remove IAM role bindings
for ROLE in \
  roles/viewer roles/bigquery.dataViewer roles/bigquery.jobUser \
  roles/billing.viewer roles/monitoring.viewer \
  roles/serviceusage.serviceUsageConsumer roles/recommender.viewer \
  roles/logging.viewer roles/cloudasset.viewer \
  roles/container.clusterViewer roles/cloudsql.viewer \
  roles/storage.objectViewer roles/cloudfunctions.viewer \
  roles/spanner.viewer roles/bigtable.viewer roles/run.viewer; do
  gcloud projects remove-iam-policy-binding $PROJECT_ID \
    --member="serviceAccount:clarity-finops@${PROJECT_ID}.iam.gserviceaccount.com" \
    --role="$ROLE" 2>/dev/null
done

# Delete all keys for the service account
gcloud iam service-accounts keys list \
  --iam-account=clarity-finops@${PROJECT_ID}.iam.gserviceaccount.com \
  --format="value(name)" | while read KEY_ID; do
  gcloud iam service-accounts keys delete $KEY_ID \
    --iam-account=clarity-finops@${PROJECT_ID}.iam.gserviceaccount.com --quiet
done

# Delete the service account
gcloud iam service-accounts delete \
  clarity-finops@${PROJECT_ID}.iam.gserviceaccount.com --quiet

Google Cloud setup guide ​

Prerequisites ​

Option 1: gcloud cLI (Recommended) ​

Option 2: GCP console ​

Step 1: create a service account ​

Step 2: assign roles ​

Step 3: create a key ​

Step 4: enable APIs ​

Required roles ​

Required APIs ​

Required (sync will fail without these) ​

Optional (features degrade gracefully without these) ​

BigQuery billing export ​

Setting up billing export ​

What to expect ​

Adding to CLARITY ​

Verification ​

Cleanup ​

Google Cloud setup guide

Prerequisites

Option 1: gcloud cLI (Recommended)

Option 2: GCP console

Step 1: create a service account

Step 2: assign roles

Step 3: create a key

Step 4: enable APIs

Required roles

Required APIs

Required (sync will fail without these)

Optional (features degrade gracefully without these)

BigQuery billing export

Setting up billing export

What to expect

Adding to CLARITY

Verification

Cleanup