GCP Integration Setup Guide

This guide walks you through setting up a read-only service account that allows OpsCompanion to monitor your Google Cloud Platform projects using Terraform.

Overview

The Terraform module automates the creation of a service account with comprehensive viewer permissions across your GCP project. This allows OpsCompanion to:

Monitor resources across all GCP services (Compute, Storage, BigQuery, Cloud SQL, GKE, etc.)
Collect audit logs for security and compliance monitoring
Access metrics and logs from Cloud Monitoring and Cloud Logging
Track billing and cost information

Important: The service account is configured with read-only permissions and cannot make changes to your infrastructure.

What Gets Created

Running this Terraform module will create:

Service Account - ops-{PROJECT_ID}-sa@{PROJECT_ID}.iam.gserviceaccount.com
IAM Roles - Project Viewer role (basic read-only access)
Workload Identity Binding - Allows OpsCompanion to authenticate as the service account
Enabled APIs - 20+ Google Cloud APIs required for comprehensive monitoring

Prerequisites

Before running the Terraform module, ensure you have:

1. Terraform Installed

# Check if Terraform is installed
terraform --version

If not installed, download from: https://www.terraform.io/downloads

2. Google Cloud SDK Installed

# Check if gcloud is installed
gcloud version

If not installed, download from: https://cloud.google.com/sdk/docs/install

3. Authenticated Account

# Login to gcloud
gcloud auth application-default login

# Set your default project (optional)
gcloud config set project YOUR_PROJECT_ID

4. Required Permissions

Your account needs these permissions on the target project:

iam.serviceAccounts.create - Create service accounts
resourcemanager.projects.setIamPolicy - Grant IAM roles
serviceusage.services.enable - Enable APIs

Recommended role: Project Owner or Project IAM Admin + Service Usage Admin

5. Billing Enabled

The target project must have billing enabled to use Cloud APIs.

6. Your OpsCompanion Organization ID

You'll need your organization ID from OpsCompanion. You can find this in your organization settings.

Installation Steps

Step 1: Create a new Terraform file

Create a new file called main.tf in your project directory and add the following module configuration:

module "opscompanion-gcp-integration" {
  source = "github.com/opscompanion/opscompanion-integrations-terraform/gcp"

  project_id    = "your-project-id"
  custom_org_id = "your-org-id"
}

output "service_account_email" {
  value = module.opscompanion-gcp-integration.service_account_email
}

Replace:

your-project-id with your GCP project ID
your-org-id with your OpsCompanion organization ID

Step 2: Navigate to the directory where the file is located

cd /path/to/your/terraform/directory

Step 3: Initialize Terraform

Run the command:

terraform init

This will download the OpsCompanion integration module and initialize your Terraform workspace.

Step 4: Review the changes

Run the command:

terraform plan

This will show you what resources will be created. Review the output to ensure it matches your expectations.

Step 5: Execute the Terraform configuration

Run the command:

terraform apply

Type yes when prompted to confirm the changes.

Step 6: Copy the Service Account Email

After the Terraform apply completes, it will output the service account email. Copy this value - you'll need it to complete the integration in OpsCompanion.

Outputs:

service_account_email = "ops-your-project-id-sa@your-project-id.iam.gserviceaccount.com"

Step 7: Complete the integration in OpsCompanion

Navigate to the OpsCompanion dashboard
Go to Manage Tools → Google Cloud Platform
Paste the service account email

Verification

1. Verify Service Account Creation

# List service accounts
gcloud iam service-accounts list --project=YOUR_PROJECT_ID | grep ops-

# Should show: ops-YOUR_PROJECT_ID-sa@YOUR_PROJECT_ID.iam.gserviceaccount.com

2. Verify IAM Roles

# Check granted roles
gcloud projects get-iam-policy YOUR_PROJECT_ID \
  --flatten="bindings[].members" \
  --filter="bindings.members:serviceAccount:ops-YOUR_PROJECT_ID-sa@*" \
  --format="table(bindings.role)"

Expected output should include roles/viewer.

3. Verify Enabled APIs

# List enabled APIs
gcloud services list --enabled --project=YOUR_PROJECT_ID | grep -E "compute|iam|logging"

4. Test Service Account Access

# Impersonate service account to test viewer access
gcloud compute instances list \
  --impersonate-service-account=ops-YOUR_PROJECT_ID-sa@YOUR_PROJECT_ID.iam.gserviceaccount.com \
  --project=YOUR_PROJECT_ID

Should successfully list instances (or show "Listed 0 items" if none exist).

Troubleshooting

Error: "Permission denied"

Cause: Your account lacks necessary permissions

Solution:

Verify you have Project Owner or IAM Admin role
Run gcloud auth application-default login again
Ensure billing is enabled on the project

Error: "Service account already exists"

Cause: Service account was created in a previous run

Solution: This is normal. Terraform will update the existing service account configuration. Run terraform apply again.

Error: "APIs could not be enabled"

Cause: Permission issues or quota limits

Solution:

Check the Terraform error output for which APIs failed
Enable them manually via the GCP Console if critical
Ensure the Service Usage API is enabled

Updating the Integration

If you need to update the integration configuration:

Modify your main.tf file
Run terraform plan to review changes
Run terraform apply to apply changes

Removing the Integration

To remove the OpsCompanion integration and clean up resources:

terraform destroy

Type yes when prompted. This will:

Delete the service account
Remove IAM bindings
Clean up all created resources

Note: This will not disable the APIs that were enabled.

Security Considerations

Read-Only Access

The service account has viewer permissions only and cannot:

Create, modify, or delete resources
Change IAM policies
Access Secret Manager secret values (can only list/view metadata)
Modify billing settings

Audit Logging

All actions taken by the service account are logged to Cloud Audit Logs and can be reviewed:

# View service account activity
gcloud logging read "protoPayload.authenticationInfo.principalEmail:ops-YOUR_PROJECT_ID-sa@*" \
  --project=YOUR_PROJECT_ID \
  --limit=50 \
  --format=json

Workload Identity Federation

The service account uses Workload Identity Federation instead of service account keys, which means:

✅ No long-lived credentials to manage
✅ Automatic credential rotation
✅ Scoped to specific external identities
✅ Can be revoked instantly

Principle of Least Privilege

The Terraform module grants only the viewer role by default, following the principle of least privilege.

Support

Getting Help

Documentation: https://opscompanion.ai/docs
Community: https://discord.gg/TdMZTqSFTq
Email: support@opscompanion.ai

Resource metadata and configuration
Audit logs (who did what, when)
Metrics from Cloud Monitoring
Billing and cost data

Not collected:

Application data from databases
File contents from Cloud Storage
Secret values from Secret Manager
Customer data from your applications

Q: Does this work with Organization-level access?

A: This module sets up project-level access. For organization-level access, contact support@opscompanion.ai.

Q: How often should I run Terraform?

A: Once per project for initial setup. Re-run only if you need to update the configuration.

Last updated: November 2025 Terraform module version: 1.0

GCP Integration Setup Guide

On this page