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:

# 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
gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:clarity-finops@${PROJECT_ID}.iam.gserviceaccount.com" \
  --role="roles/viewer"

gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:clarity-finops@${PROJECT_ID}.iam.gserviceaccount.com" \
  --role="roles/bigquery.dataViewer"

gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:clarity-finops@${PROJECT_ID}.iam.gserviceaccount.com" \
  --role="roles/billing.viewer"

# Assign optional roles (recommended)
gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:clarity-finops@${PROJECT_ID}.iam.gserviceaccount.com" \
  --role="roles/monitoring.viewer"

gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:clarity-finops@${PROJECT_ID}.iam.gserviceaccount.com" \
  --role="roles/recommender.viewer"

gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:clarity-finops@${PROJECT_ID}.iam.gserviceaccount.com" \
  --role="roles/logging.viewer"

Enable the required APIs:

# Enable all required APIs
gcloud services enable \
  compute.googleapis.com \
  sqladmin.googleapis.com \
  container.googleapis.com \
  storage.googleapis.com \
  cloudresourcemanager.googleapis.com \
  cloudbilling.googleapis.com \
  bigquery.googleapis.com \
  monitoring.googleapis.com \
  logging.googleapis.com \
  recommender.googleapis.com \
  cloudfunctions.googleapis.com \
  cloudasset.googleapis.com

Create and download the Service Account key:

# 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

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

Step 2: Assign Roles

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

1. Click Add Another Role for each:
   • Viewer (Basic)
   • BigQuery Data Viewer
   • Billing Account Viewer
   • Monitoring Viewer (optional)
   • Recommender Viewer (optional)
   • Logs Viewer (optional)
2. Click Continue, then Done

Step 3: Create a Key

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

Step 4: Enable APIs

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

Required Roles

Role	Purpose	Required
roles/viewer	Resource discovery — Compute Engine instances, Cloud SQL, GKE clusters, Cloud Storage, Cloud Functions	Yes
roles/bigquery.dataViewer	Billing export queries — reads cost data from BigQuery billing export tables	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	Optional
roles/recommender.viewer	GCP recommendations — right-sizing, idle resource, and commitment recommendations from Recommender API	Optional
roles/logging.viewer	Audit logs — Cloud Audit Log activity for event correlation and change tracking	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

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
storage.googleapis.com	Cloud Storage	Bucket discovery
cloudasset.googleapis.com	Cloud Asset	Cross-service resource inventory
logging.googleapis.com	Cloud Logging	Audit log activity and event correlation

Enable all at once via CLI:

gcloud services enable \
  bigquery.googleapis.com \
  compute.googleapis.com \
  monitoring.googleapis.com \
  cloudresourcemanager.googleapis.com \
  container.googleapis.com \
  sqladmin.googleapis.com \
  cloudfunctions.googleapis.com \
  recommender.googleapis.com \
  cloudbilling.googleapis.com \
  billingbudgets.googleapis.com \
  storage.googleapis.com \
  cloudasset.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

1. Go to the GCP Console > Billing > Billing export
2. Select the Standard usage cost tab
3. Click Edit Settings
4. Choose the project where the export dataset should live (use the same project as your CLARITY service account)
5. Create a new dataset or select an existing one (e.g., billing_export)
6. 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

1. Log in to CLARITY and navigate to Provider Setup
2. Click Add Account and select GCP
3. 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
4. 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:

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

Cleanup

To remove CLARITY access from your GCP project:

export PROJECT_ID="your-project-id"

# Remove IAM role bindings
for ROLE in roles/viewer roles/bigquery.dataViewer roles/billing.viewer roles/monitoring.viewer roles/recommender.viewer roles/logging.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