Skip to main content

GCP Configuration

Overview​

Overmind's GCP infrastructure discovery capability provides comprehensive visibility into your Google Cloud Platform resources through secure, read-only access. Our solution uses Google Cloud's native Identity and Access Management (IAM) system with service account-based authentication to ensure both security and operational efficiency.

Why Service Account-Based Access?​

Overmind implements a cross-platform direct access model using dedicated Google Cloud Service Accounts, which offers several key advantages:

  • Enhanced Security: Each customer receives a unique service account with minimal, read-only permissions
  • Audit Trail: All access is logged through Google Cloud's audit logging system
  • Granular Control: You maintain complete control over permissions and can revoke access at any time
  • No Shared Credentials: No API keys or shared credentials that could be compromised
  • Google-Native Security: Leverages Google Cloud's robust IAM system and security controls

This approach aligns with Google Cloud's security best practices and provides enterprise-grade security for infrastructure discovery operations.

How It Works​

When you create an Overmind GCP source:

  1. A dedicated service account is created in Overmind's GCP project
  2. You grant this service account read-only permissions in your GCP project(s)
  3. Overmind uses this service account to discover and map your infrastructure
  4. All operations are read-only and logged through Google Cloud's audit system

Prerequisites​

Before beginning the setup process, ensure you have:

  • GCP Project Access: Project IAM Admin role or equivalent permissions to grant IAM roles
  • 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

Step-by-Step Setup​

Step 1: Create Your Overmind GCP Source​

  1. Navigate to the Overmind application
  2. Go to Settings > Sources > Add Source > GCP
  3. Configure your source:
    • Project ID: Your GCP Project ID
    • Name: A descriptive name for this source (optional: defaults to "GCP Source for project YOUR_PROJECT_ID")
    • Regions: Specify the regions where your resources are located (mandatory)
  4. Click Create Source

You will be redirected to View Source Details, where you will find instructions to grant permissions to the Overmind service account. Important: Copy the service account email displayed on the View Source Details page - you'll need this for the next step

This service account will be referred to as OVERMIND_SA_EMAIL throughout the guide.

Step 2: Grant Permissions to Overmind Service Account​

Overmind requires specific IAM permissions within your GCP project to enable infrastructure discovery and metadata analysis. The baseline requirement is the roles/browser role, which provides Read access to browse the hierarchy for a project, including the folder, organization, and allow policy.

For comprehensive resource visibility, Overmind recommends implementing a defined set of read-only IAM roles that enable resource enumeration and metadata inspection across all supported GCP services. This includes critical roles such as roles/compute.viewer for Compute Engine resources and equivalent viewer roles for other service domains.

Reference the Required GCP Roles Reference for the complete IAM permission list.

You have two options for granting the required permissions:

  1. Create the permission script(gcp-perm-for-ovm-sa.sh):

    #!/bin/bash

    # Script to add IAM policy bindings to a service account in GCP
    # Expects GCP_PROJECT_ID and GCP_OVERMIND_SA_EMAIL environment variables to be set
    #
    # NOTE: The GCP_OVERMIND_SA_EMAIL should be the service account email presented in the Overmind
    # application when creating a new GCP source.

    set -euo pipefail  # Exit on error, undefined vars, and pipe failures

    # Check if GCP_PROJECT_ID environment variable is set
    if [[ -z "${GCP_PROJECT_ID:-}" ]]; then
    echo "ERROR: GCP_PROJECT_ID environment variable is not set"
    exit 1
    fi

    # Check if GCP_OVERMIND_SA_EMAIL environment variable is set
    if [[ -z "${GCP_OVERMIND_SA_EMAIL:-}" ]]; then
    echo "ERROR: GCP_OVERMIND_SA_EMAIL environment variable is not set"
    echo "NOTE: Use the service account email presented in the Overmind application when creating a GCP source"
    exit 1
    fi

    echo "Using GCP Project ID: ${GCP_PROJECT_ID}"
    echo "Service Account: ${GCP_OVERMIND_SA_EMAIL}"

    # Define the array of roles
    ROLES=(
     "roles/aiplatform.viewer"
     "roles/artifactregistry.reader"
     "roles/bigquery.metadataViewer"
     "roles/bigquery.user"
     "roles/bigtable.viewer"
     "roles/cloudbuild.builds.viewer"
     "roles/cloudfunctions.viewer"
     "roles/cloudkms.viewer"
     "roles/cloudsql.viewer"
     "roles/compute.viewer"
     "roles/container.viewer"
     "roles/dataform.viewer"
     "roles/dataplex.catalogViewer"
     "roles/dataplex.viewer"
     "roles/dataproc.viewer"
     "roles/dns.reader"
     "roles/essentialcontacts.viewer"
     "roles/eventarc.viewer"
     "roles/file.viewer"
     "roles/iam.roleViewer"
     "roles/iam.serviceAccountViewer"
     "roles/logging.viewer"
     "roles/monitoring.viewer"
     "roles/orgpolicy.policyViewer"
     "roles/pubsub.viewer"
     "roles/redis.viewer"
     "roles/resourcemanager.tagViewer"
     "roles/run.viewer"
     "roles/secretmanager.viewer"
     "roles/securitycentermanagement.viewer"
     "roles/servicedirectory.viewer"
     "roles/serviceusage.serviceUsageViewer"
     "roles/spanner.viewer"
     "roles/storage.bucketViewer"
     "roles/storagetransfer.viewer"
    )

    # Counter for successful operations
    SUCCESS_COUNT=0
    TOTAL_ROLES=${#ROLES[@]}

    echo "Starting to add ${TOTAL_ROLES} IAM policy bindings..."
    echo "----------------------------------------"

    # Loop through each role and add the policy binding
    for ROLE in "${ROLES[@]}"; do
    echo "Adding role: ${ROLE}"

        if gcloud projects add-iam-policy-binding "${GCP_PROJECT_ID}" \
            --member="serviceAccount:${GCP_OVERMIND_SA_EMAIL}" \
            --role="${ROLE}" \
            --quiet > /dev/null 2>&1; then
            echo "✓ Successfully added role: ${ROLE}"
            ((SUCCESS_COUNT++)) || true
        else
            echo "✗ Failed to add role: ${ROLE}"
            # Print the error output
            gcloud projects add-iam-policy-binding "${GCP_PROJECT_ID}" \
                --member="serviceAccount:${GCP_OVERMIND_SA_EMAIL}" \
                --role="${ROLE}" \
                --quiet
            exit 1
        fi
    done

    echo "----------------------------------------"
    echo "✓ All IAM policy bindings completed successfully!"
    echo "✓ Added ${SUCCESS_COUNT}/${TOTAL_ROLES} roles to service account: ${GCP_OVERMIND_SA_EMAIL}"
    echo "✓ Project: ${GCP_PROJECT_ID}"

  2. Run the script with your project details:

    chmod +x gcp-perm-for-ovm-sa.sh
    GCP_PROJECT_ID=YOUR_PROJECT_ID \
    GCP_OVERMIND_SA_EMAIL=OVERMIND_SA_EMAIL \
    ./gcp-perm-for-ovm-sa.sh

    Replace:

  1. Create a new Terraform configuration file (overmind-permissions.tf):

    variable "overmind_service_account_email" {
      description = "The Overmind service account email provided during source creation"
      type        = string
    }

    # Get the current project configuration
    data "google_client_config" "default" {}

    # Define the required roles for Overmind service account
    variable "overmind_service_account_roles" {
      description = "List of IAM roles to assign to the Overmind Service Account"
      type        = list(string)
      default = [
        "roles/aiplatform.viewer",
        "roles/artifactregistry.reader",
        "roles/bigquery.metadataViewer",
        "roles/bigquery.user",
        "roles/bigtable.viewer",
        "roles/cloudbuild.builds.viewer",
        "roles/cloudfunctions.viewer",
        "roles/cloudkms.viewer",
        "roles/cloudsql.viewer",
        "roles/compute.viewer",
        "roles/container.viewer",
        "roles/dataform.viewer",
        "roles/dataplex.catalogViewer",
        "roles/dataplex.viewer",
        "roles/dataproc.viewer",
        "roles/dns.reader",
        "roles/essentialcontacts.viewer",
        "roles/eventarc.viewer",
        "roles/file.viewer",
        "roles/iam.roleViewer",
        "roles/iam.serviceAccountViewer",
        "roles/logging.viewer",
        "roles/monitoring.viewer",
        "roles/orgpolicy.policyViewer",
        "roles/pubsub.viewer",
        "roles/redis.viewer",
        "roles/resourcemanager.tagViewer",
        "roles/run.viewer",
        "roles/secretmanager.viewer",
        "roles/securitycentermanagement.viewer",
        "roles/servicedirectory.viewer",
        "roles/serviceusage.serviceUsageViewer",
        "roles/spanner.viewer",
        "roles/storage.bucketViewer",
        "roles/storagetransfer.viewer"
      ]
    }

    # Assign the required roles to the Overmind service account
    resource "google_project_iam_member" "overmind_service_account_iam" {
      for_each = toset(var.overmind_service_account_roles)
      project  = data.google_client_config.default.project
      role     = each.value
      member   = "serviceAccount:${var.overmind_service_account_email}"
    }

  2. Create a terraform.tfvars file:

    overmind_service_account_email = OVERMIND_SA_EMAIL

    Replace OVERMIND_SA_EMAIL with the service account email from Step 1: Create Your Overmind GCP Source.

  3. Apply the Terraform configuration:

    terraform init
    terraform plan
    terraform apply

Step 3: Verify Source Status​

  1. Return to the Overmind application
  2. Navigate to Settings > Sources
  3. Locate your GCP source
  4. Verify the status shows as Healthy

Validation​

Verify IAM Permissions​

You can verify that the permissions were granted correctly using the Google Cloud Console or CLI:

Using Google Cloud Console​

  1. Go to Google Cloud Console > IAM & Admin > IAM
  2. Select your project
  3. Search for the Overmind service account email
  4. Verify that all required roles are listed

Using Google Cloud CLI​

# List all IAM bindings for the service account
gcloud projects get-iam-policy YOUR_PROJECT_ID \
  --flatten="bindings[].members" \
  --format="table(bindings.role)" \
  --filter="bindings.members:serviceAccount:OVERMIND_SA_EMAIL"

Test Source Discovery​

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

Validate Regional Coverage​

Ensure your source is configured to discover resources in all required regions:

  1. Review the Regions configuration in your source settings
  2. Verify that discovered resources match your expected regional distribution

Troubleshooting​

Common Issues and Solutions​

Issue: "Insufficient Permissions" Error​

Symptoms:

  • Specific GCP services are not being discovered

Solutions:

  1. Verify all required roles are assigned:

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

  2. Re-run the permission script or Terraform configuration

  3. Check for organization-level policies that might restrict service account access

Issue: No Resources Discovered​

Symptoms:

  • Source is healthy but no resources are found
  • Discovery completes successfully but with zero results

Solutions:

  1. Verify Regional Configuration: Ensure the source is configured for the correct regions where your resources exist
  2. Check API Enablement: Verify that required Google Cloud APIs are enabled: 
    gcloud services list --enabled --project=YOUR_PROJECT_ID
  3. Resource Permissions: Some resources may require additional organization-level permissions

Issue: Service Account Not Found​

Symptoms:

  • Error messages indicating the service account doesn't exist
  • IAM binding operations fail

Solutions:

  1. Verify you copied the correct service account email from the Overmind application
  2. Ensure the service account email format is correct (should end with .iam.gserviceaccount.com)
  3. Contact Overmind support if the service account appears to be missing

Issue: Terraform Apply Failures​

Symptoms:

  • Terraform operations fail with authentication or permission errors

Solutions:

  1. Verify your Terraform authentication: 
    gcloud auth application-default print-access-token
  2. Ensure your Google Cloud credentials have the necessary IAM permissions
  3. Check that the Google Cloud Provider is configured correctly

Getting Additional Help​

If you continue to experience issues:

  1. Check the Overmind Status Page: Visit the status page for any known issues
  2. Contact Support: Reach out to Overmind support with:
    • Your GCP Project ID
    • The Overmind service account email
    • Specific error messages
    • Screenshots of the issue

Security Considerations​

Principle of The Least Privilege​

The provided roles follow the principle of the least privilege, granting only the minimum permissions required for infrastructure discovery. All roles are read-only and do not allow:

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

Monitoring and Auditing​

To maintain security visibility:

  1. Enable Cloud Audit Logs: Ensure Cloud Audit Logs are enabled for your project
  2. Monitor Service Account Activity: Review audit logs for the Overmind service account activity
  3. Set Up Alerts: Configure alerts for unusual service account behavior

Permission Management​

  • Regular Review: Periodically review granted permissions and remove access when no longer needed
  • Revocation: You can revoke access at any time by removing the IAM bindings

Required Predefined GCP Roles Reference​

Here are all the predefined GCP roles that Overmind requires:

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

All roles provide read-only access and are sourced from Google Cloud's predefined roles documentation.