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 Resource Access: Appropriate IAM admin permissions at the organization, folder, or project level to grant IAM roles (and create service accounts for impersonation)
  • Required Tools: One of the following:
  • Parent Resource: The parent resource ID where Overmind will discover resources. This can be:
    • An organization: organizations/123456789
    • A folder: folders/987654321
    • A project: projects/my-project-id
  • 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 (if using a project as parent)
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:
    • Parent ID: The parent resource to discover from. Format:
      • Organization: organizations/123456789
      • Folder: folders/987654321
      • Project: projects/my-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. These scripts automatically apply IAM permissions at the level you specified (organization, folder, or project). Permissions granted at a parent level are inherited by all child resources.

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 automatically detects whether you're using an organization, folder, or project parent and applies the correct gcloud commands. The script varies based on whether impersonation is enabled:

For Direct Access:

  • Grants read-only roles directly to the Overmind service account at your specified parent level
  • For project-level parents, also creates a custom role for additional permissions

For Impersonation:

  • Grants read-only roles to your service account at your specified parent level (you must create the service account manually first)
  • For project-level parents, also creates a custom role for additional permissions
  • 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​

Permissions can be applied at any level of the GCP resource hierarchy and are inherited by child resources:

Direct Access:

Your GCP Organization/Folder/Project
  └─ Overmind Service Account
      └─ Granted: Viewer roles (+ custom role for project-level)
          └─ Inherited by all child folders and projects

Service Account Impersonation:

Your GCP Organization/Folder/Project
  ├─ Your Service Account
  │   └─ Granted: Viewer roles (+ custom role for project-level)
  │       └─ Inherited by all child folders and projects
  └─ 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. Navigate to IAM & Admin > IAM
  2. Select your organization, folder, or project
  3. Search for the service account (Overmind's or yours, depending on setup)
  4. Verify all required roles are listed

Using Google Cloud CLI:

For direct access at organization level:

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

For direct access at folder level:

gcloud resource-manager folders get-iam-policy YOUR_FOLDER_ID \
  --flatten="bindings[].members" \
  --format="table(bindings.role)" \
  --filter="bindings.members:serviceAccount:OVERMIND_SA_EMAIL"

For direct access at project level:

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 Overmind can impersonate your SA):

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 at the appropriate level:

# For organization-level access
gcloud organizations get-iam-policy YOUR_ORG_ID \
  --flatten="bindings[].members" \
  --filter="bindings.members:serviceAccount:SA_EMAIL"

# For folder-level access
gcloud resource-manager folders get-iam-policy YOUR_FOLDER_ID \
  --flatten="bindings[].members" \
  --filter="bindings.members:serviceAccount:SA_EMAIL"

# For project-level access
gcloud projects get-iam-policy YOUR_PROJECT_ID \
  --flatten="bindings[].members" \
  --filter="bindings.members:serviceAccount: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. For project-level parents, check that required GCP APIs are enabled: 
    gcloud services list --enabled --project=YOUR_PROJECT_ID
  3. For organization or folder-level parents, verify that you have the necessary permissions to list projects and that child projects have the required APIs enabled
  4. Some resources may require additional permissions at different levels of the hierarchy

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 parent resource (organization/folder/project ID)
  • The Overmind service account email
  • Your service account email (if using impersonation)
  • Whether you're using direct access or impersonation
  • The parent level you're configuring (organization, folder, or project)
  • 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​

Essential role for resource discovery:

  • roles/browser - Required for listing projects and navigating the resource hierarchy

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

Project-level-only roles (only applied when using projects/ parent):

  • roles/iam.roleViewer - View IAM roles
  • roles/iam.serviceAccountViewer - View service accounts

Note: Some GCP IAM roles can only be granted at the project level, not at the organization or folder level. When configuring at the organization or folder level, these project-specific roles are automatically excluded. The custom role and project-level IAM roles are only created and assigned when using a project-level parent (e.g., projects/my-project).

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 and adapt based on whether you're configuring at the organization, folder, or project level.

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/browserRequired: List projects and navigate resource hierarchy GCP Docs
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.roleViewerProject-level only: IAM role discovery GCP Docs
roles/iam.serviceAccountViewerProject-level only: IAM 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.

Project-Level Restrictions: Some roles (roles/iam.roleViewer and roles/iam.serviceAccountViewer) can only be granted at the project level in GCP. When configuring at the organization or folder level, these roles are automatically excluded. The custom role is also only created and assigned when using a project-level parent (e.g., projects/my-project).