GCP Guide

Connect CloudOpt to Google Cloud and collect data for analysis.

CloudOpt reads GCP through Application Default Credentials. No write APIs. No automatic service enablement.

Prerequisites

  • Application Default Credentials on the host running CloudOpt (gcloud auth application-default login, or a workload identity in CI)
  • Read-only IAM roles for the projects you plan to scan (roles below)
  • For billing collection: a Cloud Billing export to BigQuery
  • Optional: --impersonate-service-account for cross-project access without storing keys

Full workflow

cloudopt init

cloudopt collect gcp inventory \
  --projects my-app-project,shared-vpc-project \
  --regions us-central1 \
  --zones us-central1-a

cloudopt collect gcp cost \
  --lookback-days 30 \
  --billing-export-project billing-project \
  --bigquery-dataset billing_export \
  --bigquery-table gcp_billing_export_v1_XXXXXX

cloudopt collect gcp metrics --lookback-days 14

cloudopt analyze
cloudopt report --format html

Run --dry-run first to confirm permissions and scope without pulling data.

What each collect step pulls

Inventory

  • Compute Engine instances, machine types, persistent disks, images, and snapshots
  • Cloud SQL instances
  • VPC networks, subnets, routes, forwarding rules, external IP addresses, and Cloud NAT
  • GKE clusters and node pools (inventory relationships only; no Kubernetes workload analysis yet)

Limit scope with --projects, --organization-id, --folder-id, --regions, --zones, --regions-allow, or --regions-deny.

Costs

Billing data from your configured BigQuery export (default lookback: 30 days):

  • Invoice month, usage period, list cost, effective cost, credits, adjustments, and taxes
  • Attribution to canonical resources where export rows include resource identifiers
  • Unattributed costs kept at project, service, and SKU level

If you have no billing export configured, cost collection stops with an error. CloudOpt won’t estimate historical cost from catalog prices.

Check totals after collection:

cloudopt cost-reconcile

Metrics

Cloud Monitoring data for Compute Engine, persistent disks, Cloud SQL, Cloud NAT, and GKE node pools (default lookback: 14 days):

  • CPU, network, and storage raw metrics
  • Derived signals: mean, max, p95, idle periods, trend

Rightsizing and idle-instance checks require metrics collection.

IAM roles

Grant read-only roles at project or folder scope.

Inventory

Role Purpose
roles/compute.viewer Compute Engine, VPC, NAT, external IPs
roles/cloudsql.viewer Cloud SQL instances
roles/container.viewer GKE clusters and node pools
roles/serviceusage.serviceUsageViewer Enabled API preflight
roles/resourcemanager.projectViewer Project discovery

Billing export

Role Purpose
roles/bigquery.dataViewer Read billing export table
roles/bigquery.jobUser Run BigQuery queries
roles/cloudbilling.viewer Billing account metadata

Cloud Monitoring

Role Purpose
roles/monitoring.viewer Read utilization metrics

Copy-paste JSON lives in the CloudOpt repository under each adapter directory.

Service account impersonation

Impersonate a member-project service account from a central runner:

cloudopt collect gcp inventory \
  --impersonate-service-account cloudopt-reader@my-project.iam.gserviceaccount.com \
  --projects my-app-project \
  --regions us-central1

Your ADC identity needs permission to impersonate the target service account.

Partial snapshots

When a project, region, or API fails (permission gap or disabled API), CloudOpt saves a partial snapshot with per-unit coverage notes. Analysis skips partial snapshots by default. Fix IAM or enable the API, then re-run collect.

Multiple projects

cloudopt collect gcp inventory \
  --projects app-prod,app-staging,shared-vpc \
  --regions us-central1,europe-west1

Projects collect concurrently (default: 3 at a time) with retries.

Offline testing

Use --offline with recorded fixtures. See Try without cloud access.