Skip to main content

GCP Configuration

Overview​

Overmind's GCP infrastructure discovery provides comprehensive visibility into your Google Cloud Platform resources through secure, read-only access using Google Cloud's native IAM system.

Overmind supports two authentication methods:

  1. Direct Access (Default) - Grant permissions directly to the Overmind service account
  2. Service Account Impersonation (Optional) - Create your own service account with permissions, then allow Overmind to impersonate it

Both methods provide the same functionality and security. Choose the method that fits your organization's security policies.

Authentication Methods Comparison​

Direct Access:

  • Simplest setup - grant roles directly to Overmind's service account
  • Best for quick setup and straightforward security requirements

Service Account Impersonation:

  • Enhanced control - you create and manage your own service account
  • Better for organizations requiring all service accounts to be internally managed
  • Provides dual identity in audit logs (both Overmind's SA and your SA)
  • Learn more: GCP Service Account Impersonation

Why Service Account-Based Access?​

Each customer receives a unique Overmind service account with minimal, read-only permissions. All access is logged through Google Cloud's audit system, giving you complete control with no shared credentials. This aligns with Google Cloud's security best practices.

Prerequisites​

Before beginning setup, ensure you have:

  • GCP Project Access: Project IAM Admin role or equivalent permissions to grant IAM roles (and create service accounts for impersonation)
  • Required Tools: One of the following:
  • Project Information: Your GCP Project ID where Overmind will discover resources
  • Regional Scope: List of GCP regions where your resources are located (mandatory for source configuration)

Authentication Setup​

Ensure your local environment is authenticated with Google Cloud:

# Authenticate with Google Cloud
gcloud auth login

# Set your default project
gcloud config set project YOUR_PROJECT_ID

# Verify authentication
gcloud auth list

For Terraform users, configure Application Default Credentials (ADC):

gcloud auth application-default login

Quick Start​

Step 1: Create Your Overmind GCP Source​

  1. Navigate to Settings > Sources > Add Source > GCP in the Overmind application
  2. Configure your source:
    • Project ID: Your GCP Project ID
    • Name: A descriptive name for this source (optional)
    • Regions: Select the regions where your resources are located (mandatory)
    • Impersonation (optional): Toggle on to use service account impersonation
      • Enter the email of the service account you'll create (e.g., overmind-reader@your-project.iam.gserviceaccount.com)
      • Use any unique name for your service account
  3. Click Create Source

You'll be redirected to the source details page showing:

  • The Overmind service account email (e.g., C-xxxxx@ovm-production.iam.gserviceaccount.com)
  • Configuration instructions customized for your setup
  • Whether impersonation is enabled

Step 2: Grant Permissions​

The source details page provides customized scripts for your setup. Choose your preferred method:

Option A: Cloud Shell (Easiest)​

Click the "Open in Google Cloud Shell" button shown on the source details page. This provides you with the scripts and guidance needed to complete the setup. Follow the instructions in Cloud Shell to run the appropriate setup script for your configuration.

Option B: Manual Script​

Copy and run the bash script shown on the source details page. The script varies based on whether impersonation is enabled:

For Direct Access:

  • Grants read-only roles directly to the Overmind service account

For Impersonation:

  • Grants read-only roles to your service account (you must create the service account manually first)
  • Grants Overmind's service account permission to impersonate yours (roles/iam.serviceAccountTokenCreator)

Option C: Terraform​

Copy the Terraform configuration shown on the source details page and apply it:

terraform init
terraform plan
terraform apply

Step 3: Verify Source Status​

  1. Navigate to Settings > Sources in the Overmind application
  2. Verify your GCP source shows as Healthy

Required Permissions​

Overmind requires read-only IAM roles for infrastructure discovery. See the Required GCP Roles Reference for the complete list.

Permission Flow​

Direct Access:

Your GCP Project
  └─ Overmind Service Account
      └─ Granted: Viewer roles + custom role

Service Account Impersonation:

Your GCP Project
  ├─ Your Service Account
  │   └─ Granted: Viewer roles + custom role
  └─ Overmind Service Account
      └─ Granted: roles/iam.serviceAccountTokenCreator on Your Service Account

Switching Between Authentication Methods​

Enable Impersonation​

  1. Create a service account in your GCP project (if you haven't already)
  2. Grant it the required read-only roles and impersonation permission (use the scripts from the source details page - they handle both)
  3. Edit your source in Overmind: enable Impersonation and enter your service account email
  4. (Optional) Remove direct permissions from Overmind's service account

Disable Impersonation​

  1. Edit your source in Overmind: disable Impersonation (this updates the scripts on the source details page)
  2. Grant the required read-only roles directly to Overmind's service account (use the updated scripts from the source details page)
  3. (Optional) Remove the impersonation permission and delete your service account

Validation​

Verify IAM Permissions​

Using Google Cloud Console:

  1. Go to IAM & Admin > IAM
  2. Search for the service account (Overmind's or yours, depending on setup)
  3. Verify all required roles are listed

Using Google Cloud CLI:

For direct access:

gcloud projects get-iam-policy YOUR_PROJECT_ID \
  --flatten="bindings[].members" \
  --format="table(bindings.role)" \
  --filter="bindings.members:serviceAccount:OVERMIND_SA_EMAIL"

For impersonation (verify your SA has roles):

gcloud projects get-iam-policy YOUR_PROJECT_ID \
  --flatten="bindings[].members" \
  --format="table(bindings.role)" \
  --filter="bindings.members:serviceAccount:YOUR_SA_EMAIL"

For impersonation (verify Overmind can impersonate):

gcloud iam service-accounts get-iam-policy YOUR_SA_EMAIL \
  --project=YOUR_PROJECT_ID \
  --flatten="bindings[].members" \
  --format="table(bindings.role,bindings.members)" \
  --filter="bindings.members:serviceAccount:OVERMIND_SA_EMAIL"

Test Source Discovery​

  1. Navigate to Explore in the Overmind application
  2. Run a query: GCP sources are prefixed with gcp-
    • To list all VMs: gcp-compute-instance > LIST
  3. Verify resources are being discovered

Validate Regional Coverage​

Review the Regions configuration in your source settings and verify discovered resources match your expected regional distribution.

Troubleshooting​

Common Issues​

"Insufficient Permissions" Error

Verify all required roles are assigned:

# For direct access
gcloud projects get-iam-policy YOUR_PROJECT_ID \
  --flatten="bindings[].members" \
  --filter="bindings.members:serviceAccount:OVERMIND_SA_EMAIL"

# For impersonation
gcloud projects get-iam-policy YOUR_PROJECT_ID \
  --flatten="bindings[].members" \
  --filter="bindings.members:serviceAccount:YOUR_SA_EMAIL"

Re-run the setup script or check for organization-level policies restricting service account access.

No Resources Discovered

  1. Verify regional configuration matches where your resources exist
  2. Check that required GCP APIs are enabled: 
    gcloud services list --enabled --project=YOUR_PROJECT_ID
  3. Some resources may require additional organization-level permissions

Service Account Impersonation Fails

  1. Verify the impersonation permission is granted:

    gcloud iam service-accounts get-iam-policy YOUR_SA_EMAIL --project=YOUR_PROJECT_ID

    You should see Overmind's service account with roles/iam.serviceAccountTokenCreator.

  2. Verify your service account exists and isn't disabled:

    gcloud iam service-accounts describe YOUR_SA_EMAIL --project=YOUR_PROJECT_ID

  3. Ensure the service account email in Overmind matches exactly

  4. Wait for propagation: IAM policy changes can take a few minutes to propagate. Wait 2-5 minutes after granting permissions before testing.

  5. Check organization policies: Some organization policies may restrict service account impersonation.

Service Account Not Found

  1. Verify you copied the correct email from the Overmind application
  2. Ensure the email format is correct (ends with .iam.gserviceaccount.com)
  3. For impersonation: verify your service account was created successfully
  4. Contact Overmind support if issues persist

Terraform Apply Failures

  1. Verify authentication: gcloud auth application-default print-access-token
  2. Ensure your credentials have necessary IAM permissions
  3. For impersonation: ensure you have iam.serviceAccounts.create permission

Getting Help​

If you continue to experience issues, contact Overmind support with:

  • Your GCP Project ID
  • The Overmind service account email
  • Your service account email (if using impersonation)
  • Whether you're using direct access or impersonation
  • Specific error messages and screenshots

Security Considerations​

Principle of Least Privilege​

All roles are read-only and do not allow:

  • Resource modification or deletion
  • Data access (beyond metadata)
  • Configuration changes
  • Administrative operations

Monitoring and Auditing​

  1. Enable Cloud Audit Logs for your project
  2. Monitor service account activity in audit logs
  3. Configure alerts for unusual behavior

Impersonation Audit Benefits: With impersonation, audit logs show both Overmind's identity and your service account identity, providing enhanced traceability.

Permission Management​

  • Regular Review: Periodically review granted permissions
  • Revocation: Remove access anytime:
    • Direct access: Remove IAM bindings
    • Impersonation: Remove serviceAccountTokenCreator role or disable/delete your service account

Required Permissions​

Overmind requires read-only access to discover and map your GCP infrastructure. The setup scripts provided in the Overmind application automatically grant all necessary permissions.

What Gets Configured​

Read-only viewer roles for GCP services including:

  • Compute Engine, GKE, Cloud Run, Cloud Functions
  • Cloud SQL, BigQuery, Spanner, Cloud Storage
  • IAM, networking, monitoring, and logging resources
  • And other GCP services

A custom role with additional permissions for:

  • BigQuery data transfer configurations
  • Spanner database details

For impersonation (if enabled):

  • roles/iam.serviceAccountTokenCreator - Allows Overmind to impersonate your service account

All permissions are read-only and do not allow resource modification, deletion, or access to data beyond metadata.

The complete list of roles is included in the setup scripts shown in your source details page. These scripts are automatically updated as Overmind adds support for new GCP services.

Required GCP Roles Reference​

Here are all the predefined GCP roles that Overmind requires, plus the custom role for additional permissions:

Predefined Roles​

RolePurpose
roles/aiplatform.viewerAI Platform resource discovery GCP Docs
roles/artifactregistry.readerArtifact Registry repository discovery GCP Docs
roles/bigquery.metadataViewerBigQuery metadata discovery GCP Docs
roles/bigquery.userBigQuery data transfer discovery GCP Docs
roles/bigtable.viewerCloud Bigtable resource discovery GCP Docs
roles/cloudbuild.builds.viewerCloud Build resource discovery GCP Docs
roles/cloudfunctions.viewerCloud Functions discovery GCP Docs
roles/cloudkms.viewerCloud KMS resource discovery GCP Docs
roles/cloudsql.viewerCloud SQL instance discovery GCP Docs
roles/compute.viewerCompute Engine resource discovery GCP Docs
roles/container.viewerGKE cluster and resource discovery GCP Docs
roles/dataform.viewerDataform resource discovery GCP Docs
roles/dataplex.catalogViewerDataplex catalog resource discovery GCP Docs
roles/dataplex.viewerDataplex resource discovery GCP Docs
roles/dataproc.viewerDataproc cluster discovery GCP Docs
roles/dns.readerCloud DNS resource discovery GCP Docs
roles/essentialcontacts.viewerEssential Contacts discovery GCP Docs
roles/eventarc.viewerEventarc trigger discovery GCP Docs
roles/file.viewerCloud Filestore discovery GCP Docs
roles/iam.roleViewerIAM role discovery GCP Docs
roles/iam.serviceAccountViewerIAM service account discovery GCP Docs
roles/logging.viewerCloud Logging resource discovery GCP Docs
roles/monitoring.viewerCloud Monitoring resource discovery GCP Docs
roles/orgpolicy.policyViewerOrganization Policy discovery GCP Docs
roles/pubsub.viewerPub/Sub resource discovery GCP Docs
roles/redis.viewerCloud Memorystore Redis discovery GCP Docs
roles/resourcemanager.tagViewerResource Manager tag discovery GCP Docs
roles/run.viewerCloud Run resource discovery GCP Docs
roles/secretmanager.viewerSecret Manager secret discovery (metadata only) GCP Docs
roles/securitycentermanagement.viewerSecurity Center management discovery GCP Docs
roles/servicedirectory.viewerService Directory resource discovery GCP Docs
roles/serviceusage.serviceUsageViewerService Usage discovery GCP Docs
roles/spanner.viewerCloud Spanner resource discovery GCP Docs
roles/storage.bucketViewerCloud Storage bucket discovery GCP Docs
roles/storagetransfer.viewerStorage Transfer Service discovery GCP Docs

Custom Role​

RolePurpose
projects/{PROJECT_ID}/roles/overmindCustomRoleCustom role for additional BigQuery and Spanner permissions Permissions: bigquery.transfers.get - BigQuery transfer configuration discovery, spanner.databases.get - Spanner database detail discovery, spanner.databases.list - Spanner database enumeration

All predefined roles provide read-only access and are sourced from Google Cloud's predefined roles documentation. The custom role is created automatically by the provided scripts and Terraform configurations.