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:

A dedicated service account is created in Overmind's GCP project
You grant this service account read-only permissions in your GCP project(s)
Overmind uses this service account to discover and map your infrastructure
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:
- Google Cloud CLI (gcloud) installed and authenticated
- Terraform with the Google Cloud Provider configured
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

Navigate to the Overmind application
Go to Settings > Sources > Add Source > GCP
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)
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:

Option A: Using Google Cloud CLI (Recommended for Quick Setup)

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}"

# Create custom role for additional BigQuery and Spanner permissions
echo "Creating custom role for additional BigQuery and Spanner permissions..."
if gcloud iam roles create overmindCustomRole \
    --project="${GCP_PROJECT_ID}" \
    --title="Overmind Custom Role" \
    --description="Custom role for Overmind service account with additional BigQuery and Spanner permissions" \
    --permissions="bigquery.transfers.get,spanner.databases.get,spanner.databases.list" \
    --quiet > /dev/null 2>&1; then
    echo "✓ Successfully created custom role: overmindCustomRole"
else
    echo "ℹ Custom role may already exist, continuing..."
fi

# Define the array of roles (including the custom role)
ROLES=(
 "roles/aiplatform.viewer"
 "roles/artifactregistry.reader"
 "roles/bigquery.metadataViewer"
 "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"
 "projects/${GCP_PROJECT_ID}/roles/overmindCustomRole"
)

# 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}"

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:
- YOUR_PROJECT_ID: Your GCP Project ID
- OVERMIND_SA_EMAIL: The service account email from Step 1: Create Your Overmind GCP Source

Option B: Using Terraform (Recommended for Infrastructure as Code)

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" {}

# Create a custom role for additional BigQuery and Spanner permissions
resource "google_project_iam_custom_role" "overmind_custom_role" {
  role_id     = "overmindCustomRole"
  title       = "Overmind Custom Role"
  description = "Custom role for Overmind service account with additional BigQuery and Spanner permissions"
  permissions = [
    "bigquery.transfers.get",
    "spanner.databases.get",
    "spanner.databases.list"
  ]
}

# Define the predefined 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/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 predefined 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}"
}

# Assign the custom role to the Overmind service account
resource "google_project_iam_member" "overmind_service_account_iam_custom" {
  project = data.google_client_config.default.project
  role    = google_project_iam_custom_role.overmind_custom_role.name
  member  = "serviceAccount:${var.overmind_service_account_email}"
}

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.

Apply the Terraform configuration:

terraform init
terraform plan
terraform apply

Step 3: Verify Source Status

Return to the Overmind application
Navigate to Settings > Sources
Locate your GCP source
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

Go to Google Cloud Console > IAM & Admin > IAM
Select your project
Search for the Overmind service account email
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

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

Validate Regional Coverage

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

Review the Regions configuration in your source settings
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:

Verify all required roles are assigned:

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

Re-run the permission script or Terraform configuration
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:

Verify Regional Configuration: Ensure the source is configured for the correct regions where your resources exist
Check API Enablement: Verify that required Google Cloud APIs are enabled:
```
gcloud services list --enabled --project=YOUR_PROJECT_ID
```
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:

Verify you copied the correct service account email from the Overmind application
Ensure the service account email format is correct (should end with .iam.gserviceaccount.com)
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:

Verify your Terraform authentication:

gcloud auth application-default print-access-token

Ensure your Google Cloud credentials have the necessary IAM permissions
Check that the Google Cloud Provider is configured correctly

Getting Additional Help

If you continue to experience issues:

Check the Overmind Status Page: Visit the status page for any known issues
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:

Enable Cloud Audit Logs: Ensure Cloud Audit Logs are enabled for your project
Monitor Service Account Activity: Review audit logs for the Overmind service account activity
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 GCP Roles Reference

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

Predefined Roles

Role	Purpose
`roles/aiplatform.viewer`	AI Platform resource discovery GCP Docs
`roles/artifactregistry.reader`	Artifact Registry repository discovery GCP Docs
`roles/bigquery.metadataViewer`	BigQuery metadata discovery GCP Docs
`roles/bigquery.user`	BigQuery data transfer discovery GCP Docs
`roles/bigtable.viewer`	Cloud Bigtable resource discovery GCP Docs
`roles/cloudbuild.builds.viewer`	Cloud Build resource discovery GCP Docs
`roles/cloudfunctions.viewer`	Cloud Functions discovery GCP Docs
`roles/cloudkms.viewer`	Cloud KMS resource discovery GCP Docs
`roles/cloudsql.viewer`	Cloud SQL instance discovery GCP Docs
`roles/compute.viewer`	Compute Engine resource discovery GCP Docs
`roles/container.viewer`	GKE cluster and resource discovery GCP Docs
`roles/dataform.viewer`	Dataform resource discovery GCP Docs
`roles/dataplex.catalogViewer`	Dataplex catalog resource discovery GCP Docs
`roles/dataplex.viewer`	Dataplex resource discovery GCP Docs
`roles/dataproc.viewer`	Dataproc cluster discovery GCP Docs
`roles/dns.reader`	Cloud DNS resource discovery GCP Docs
`roles/essentialcontacts.viewer`	Essential Contacts discovery GCP Docs
`roles/eventarc.viewer`	Eventarc trigger discovery GCP Docs
`roles/file.viewer`	Cloud Filestore discovery GCP Docs
`roles/iam.roleViewer`	IAM role discovery GCP Docs
`roles/iam.serviceAccountViewer`	IAM service account discovery GCP Docs
`roles/logging.viewer`	Cloud Logging resource discovery GCP Docs
`roles/monitoring.viewer`	Cloud Monitoring resource discovery GCP Docs
`roles/orgpolicy.policyViewer`	Organization Policy discovery GCP Docs
`roles/pubsub.viewer`	Pub/Sub resource discovery GCP Docs
`roles/redis.viewer`	Cloud Memorystore Redis discovery GCP Docs
`roles/resourcemanager.tagViewer`	Resource Manager tag discovery GCP Docs
`roles/run.viewer`	Cloud Run resource discovery GCP Docs
`roles/secretmanager.viewer`	Secret Manager secret discovery (metadata only) GCP Docs
`roles/securitycentermanagement.viewer`	Security Center management discovery GCP Docs
`roles/servicedirectory.viewer`	Service Directory resource discovery GCP Docs
`roles/serviceusage.serviceUsageViewer`	Service Usage discovery GCP Docs
`roles/spanner.viewer`	Cloud Spanner resource discovery GCP Docs
`roles/storage.bucketViewer`	Cloud Storage bucket discovery GCP Docs
`roles/storagetransfer.viewer`	Storage Transfer Service discovery GCP Docs

Custom Role

Role	Purpose
`projects/{PROJECT_ID}/roles/overmindCustomRole`	Custom 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.

Overview​

Why Service Account-Based Access?​

How It Works​

Prerequisites​

Authentication Setup​

Step-by-Step Setup​

Step 1: Create Your Overmind GCP Source​

Step 2: Grant Permissions to Overmind Service Account​

Option A: Using Google Cloud CLI (Recommended for Quick Setup)​

Option B: Using Terraform (Recommended for Infrastructure as Code)​

Step 3: Verify Source Status​

Validation​

Verify IAM Permissions​

Using Google Cloud Console​

Using Google Cloud CLI​

Test Source Discovery​

Validate Regional Coverage​

Troubleshooting​

Common Issues and Solutions​

Issue: "Insufficient Permissions" Error​

Issue: No Resources Discovered​

Issue: Service Account Not Found​

Issue: Terraform Apply Failures​

Getting Additional Help​

Security Considerations​

Principle of The Least Privilege​

Monitoring and Auditing​

Permission Management​

Required GCP Roles Reference​

Predefined Roles​

Custom Role​

Overview

Why Service Account-Based Access?

How It Works

Prerequisites

Authentication Setup

Step-by-Step Setup

Step 1: Create Your Overmind GCP Source

Step 2: Grant Permissions to Overmind Service Account

Option A: Using Google Cloud CLI (Recommended for Quick Setup)

Option B: Using Terraform (Recommended for Infrastructure as Code)

Step 3: Verify Source Status

Validation

Verify IAM Permissions

Using Google Cloud Console

Using Google Cloud CLI

Test Source Discovery

Validate Regional Coverage

Troubleshooting

Common Issues and Solutions

Issue: "Insufficient Permissions" Error

Issue: No Resources Discovered

Issue: Service Account Not Found

Issue: Terraform Apply Failures

Getting Additional Help

Security Considerations

Principle of The Least Privilege

Monitoring and Auditing

Permission Management

Required GCP Roles Reference

Predefined Roles

Custom Role