Connecting a GCP account

Overview

To onboard your GCP environment to DigiUsher, a service account with read-only access to billing, resource, and metrics data is required. This document describes exactly what permissions are requested, why each is needed, and what credentials to provide.

Summary of Access Required

DigiUsher cannot create, modify, or delete any of your GCP resources.

If your organization's policies require manual resource provisioning, follow the steps below.

Prerequisites

Information to Gather

Roles Required by the Person Performing Setup

Option A: Terraform (Recommended)

Our Terraform configuration automates the entire setup in ~5 minutes.

git clone https://github.com/digiusher/digiusher-iac.git
cd digiusher-iac/gcp

cp terraform.tfvars.org-level.example terraform.tfvars
# Edit terraform.tfvars with your Organization ID, Billing Account ID, and Project ID

terraform init
terraform plan
terraform apply

cp terraform.tfvars.limited.example terraform.tfvars
# Edit terraform.tfvars — set target_project_ids to your project list

terraform init
terraform plan
terraform apply

cp terraform.tfvars.existing-export.example terraform.tfvars
# Edit terraform.tfvars — set billing_export_dataset_id to your existing dataset

terraform init
terraform plan
terraform apply

After Terraform Apply

terraform output -raw service_account_key | base64 -d > digiusher-key.json

See the digiusher-iac README for full Terraform documentation including parameters, feature flags, and troubleshooting.

Option B: Manual Setup

Follow these steps if you prefer to set up via the GCP Console or gcloud CLI.

gcloud services enable \
  bigquery.googleapis.com \
  cloudbilling.googleapis.com \
  cloudresourcemanager.googleapis.com \
  iam.googleapis.com \
  cloudasset.googleapis.com \
  recommender.googleapis.com \
  compute.googleapis.com \
  sqladmin.googleapis.com \
  monitoring.googleapis.com \
  --project=<PROJECT_ID>

gcloud iam service-accounts create digiusher-finops \
  --display-name="DigiUsher FinOps Platform" \
  --description="Read-only service account for DigiUsher cloud cost management" \
  --project=<PROJECT_ID>

gcloud iam service-accounts keys create digiusher-key.json \
  --iam-account=digiusher-finops@<PROJECT_ID>.iam.gserviceaccount.com

bq mk --location=US --dataset <PROJECT_ID>:digiusher_billing_export

gcloud billing accounts add-iam-policy-binding <BILLING_ACCOUNT_ID> \
  --member="serviceAccount:digiusher-finops@<PROJECT_ID>.iam.gserviceaccount.com" \
  --role="roles/billing.viewer"

SA="serviceAccount:digiusher-finops@<PROJECT_ID>.iam.gserviceaccount.com"
ORG_ID="<ORGANIZATION_ID>"

for role in \
  roles/browser \
  roles/resourcemanager.tagViewer \
  roles/cloudasset.viewer \
  roles/recommender.viewer \
  roles/compute.viewer \
  roles/cloudsql.viewer \
  roles/bigquery.resourceViewer \
  roles/monitoring.viewer; do
  gcloud organizations add-iam-policy-binding "$ORG_ID" \
    --member="$SA" --role="$role"
done

SA="serviceAccount:digiusher-finops@<PROJECT_ID>.iam.gserviceaccount.com"

gcloud projects add-iam-policy-binding <PROJECT_ID> \
  --member="$SA" --role="roles/bigquery.jobUser"

gcloud projects add-iam-policy-binding <PROJECT_ID> \
  --member="$SA" --role="roles/bigquery.readSessionUser"

gcloud projects add-iam-policy-binding <PROJECT_ID> \
  --member="$SA" --role="roles/serviceusage.serviceUsageConsumer"

# Get current policy
bq show --format=prettyjson <PROJECT_ID>:digiusher_billing_export > /tmp/dataset_policy.json

# Add the access entry for the service account (role: READER) to the "access" array
# Then update:
bq update --source /tmp/dataset_policy.json <PROJECT_ID>:digiusher_billing_export

Connect in DigiUsher

After completing either Option A or B, enter the following into the DigiUsher platform to complete the connection:

Verification Checklist

• APIs enabled in the hosting project
• Service account digiusher-finops created with JSON key
• BigQuery dataset created (or existing dataset identified)
• Billing Account Viewer role assigned on billing account
• Organization-level roles assigned (Browser, Tag Viewer, Cloud Asset Viewer, Recommender Viewer, Compute Viewer, Cloud SQL Viewer, BigQuery Resource Viewer, Monitoring Viewer)
• BigQuery Job User, BigQuery Read Session User, and Service Usage Consumer assigned on the hosting project
• BigQuery Data Viewer assigned on the billing export dataset
• Detailed usage cost billing export enabled (pointing to the dataset)
• Pricing billing export enabled (pointing to the same dataset)
• Credentials entered into the DigiUsher platform
• *.digiusher.com allowlisted in network/firewall (if applicable)
• digiusher.com allowlisted for incoming email (if applicable)

Security

What DigiUsher CAN Access (Read-Only)

• Billing data and cost information via BigQuery
• Resource metadata (names, types, regions, labels, tags)
• Utilization metrics (CPU, memory, network, disk) via Cloud Monitoring
• Optimization recommendations from Google's Recommender API
• CUD and reservation information
• Organization, folder, and project hierarchy

What DigiUsher CANNOT Do

• Create, modify, or delete any GCP resources
• Access application data, databases, or storage contents
• Modify IAM policies or permissions
• Read secrets, credentials, or encryption keys
• Access network traffic or logs content
• Make purchases or modify billing settings
• Access BigQuery datasets other than the billing export dataset

Scope Controls

• Set target_project_ids (Terraform) to restrict access to specific projects instead of the entire organization
• BigQuery access is always scoped to the billing export dataset only, regardless of org-wide access
• Billing Viewer is scoped to a single billing account

Monitoring

Monitor service account activity in GCP Console > IAM & Admin > Audit Logs, filtering by principal digiusher-finops@<PROJECT_ID>.iam.gserviceaccount.com.

Credential Rotation

• Terraform: terraform apply -replace="google_service_account_key.digiusher"
• Manual: Service account > Keys > Add Key (create new), then delete the old key. Enter the new key into the DigiUsher platform.

Revocation

• Terraform: terraform destroy — removes the service account, all IAM bindings, and invalidates the key.
• Manual: Delete the digiusher-finops service account in IAM & Admin > Service Accounts. This instantly invalidates the key and all associated IAM bindings.
• APIs are intentionally not disabled on revocation to avoid breaking your existing workloads.

Troubleshooting

Cannot find Organization ID

gcloud organizations list

If empty, your GCP account may not have an organization. Organizations require Google Workspace or Cloud Identity. Contact your GCP admin.

"Permission denied" when assigning roles

You need Organization Administrator for org-level roles and Billing Account Administrator for billing roles. Verify your roles:

gcloud organizations get-iam-policy <ORG_ID> \
  --flatten="bindings[].members" \
  --filter="bindings.members:user:<YOUR_EMAIL>" \
  --format="table(bindings.role)"

BigQuery dataset already exists

Use your existing dataset — just make sure it's in a multi-region location (US or EU) and grant BigQuery Data Viewer to the service account on that dataset.

No billing data after 48 hours

1. Verify billing export shows "Enabled" in Billing > Billing export
2. Confirm dataset location is multi-region (US or EU)
3. Ensure Detailed usage cost is enabled (not just Standard)
4. Check that the correct billing account is selected

"API not enabled" errors

Ensure all APIs from Step 1 are enabled. API propagation can take a few minutes.

Need Help?

If you encounter any issues not covered above, contact us at support@digiusher.com and we'll help you get set up.