Skip to main content
Connect your GCP projects to enable CloudThinker agents to analyze costs, optimize resources, audit security, and manage infrastructure across Google Cloud services. GCP authenticates with a service-account key (a JSON file); the service account’s IAM roles determine what each agent can reach.

​
Prerequisites

  • A GCP project with IAM administrator access.
  • Permission to create service accounts and assign IAM roles in the project.
  • The Google Cloud Console accessible in your browser.
A viewer-level service account is sufficient for cost analysis, security audits, and resource inspection. Widen the roles only if you need write capabilities.

​
Setup

1

Create a service account

In the Google Cloud Console, select your project and navigate to IAM & Admin → Service accounts. Click Create Service Account and enter:
  • Name: cloudthinker-readonly
  • Description: Read-only access for CloudThinker monitoring
2

Assign roles

Grant the required viewer roles:
  • Viewer (basic read access)
  • Monitoring Viewer (for monitoring data)
  • Security Reviewer (for security analysis)
3

Generate a JSON key

Click on the created service account from the list, go to Keys tab → Add key → Create new key, select JSON format, and click Create. Download the key file and store it securely.
4

Add the connection in CloudThinker

Navigate to Connections → GCP and upload the JSON key file (or paste its contents). Click Connect. CloudThinker verifies the credentials and shows a Connected status.
Store the JSON key file securely. Never commit it to version control or share it publicly.

​
Multi-project setup

For organizations with multiple GCP projects:
1

Grant organization-level access

Grant the service account roles at the organization or folder level so it can reach all target projects.
2

Add billing account access

Add Billing Account Viewer for cross-project cost analysis.
3

Add projects

CloudThinker automatically discovers accessible projects after connecting.

​
Connection details

FieldDescriptionExample
Service Account Key (JSON)Full GCP service-account key JSON, uploaded or pasted into the connection dialog{"type": "service_account", "project_id": "your-project-id", ...}
The key file contains the following structure: 
{
  "type": "service_account",
  "project_id": "your-project-id",
  "private_key_id": "key-id",
  "private_key": "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----\n",
  "client_email": "cloudthinker-readonly@your-project.iam.gserviceaccount.com",
  "client_id": "123456789012345678901",
  "auth_uri": "https://accounts.google.com/o/oauth2/auth",
  "token_uri": "https://oauth2.googleapis.com/token"
}

​
Required permissions

​
Minimum (read-only analysis)

roles/viewer                    # Basic read access
roles/monitoring.viewer         # Cloud Monitoring access
roles/logging.viewer            # Cloud Logging access

# All of the above, plus:
roles/compute.viewer            # Compute Engine details
roles/container.viewer          # GKE cluster access
roles/cloudsql.viewer           # Cloud SQL access
roles/bigquery.dataViewer       # BigQuery analysis
roles/billing.viewer            # Billing and cost data
roles/securitycenter.viewer     # Security Command Center
Start with the minimum roles and add more only as needed. A viewer role at the project level is sufficient for cost analysis and most security audits.

​
Agent capabilities

Once connected, agents can analyze and optimize your GCP resources.
AgentGCP capabilities
AlexCost analysis, VM right-sizing, committed use recommendations, resource optimization
OliverSecurity Command Center findings, IAM audits, compliance checks
TonyCloud SQL performance, BigQuery optimization, Spanner tuning
KaiGKE cluster management, workload optimization, Autopilot analysis

​
Verify the connection

@alex run a GCP account check and list connected projects and active services

​
Example prompts

@alex analyze Compute Engine costs over the last 30 days and #recommend right-sizing opportunities
@oliver audit GCP IAM bindings and flag any over-permissioned service accounts
@kai inspect GKE cluster health and #report any pod failures or resource pressure

​
Troubleshooting

Verify the service account has the required roles. Check project-level IAM bindings, ensure APIs are enabled (Compute, Monitoring, etc.), and confirm the JSON key is valid and not expired.
Verify the JSON file is complete and properly formatted. Check that the private key hasn’t been truncated and that no extra whitespace or characters were added. Try regenerating the key from GCP Console.
Verify Billing Account Viewer role is assigned. Enable the Cloud Billing API and check that billing export to BigQuery is configured.
Ensure Kubernetes Engine Viewer role is assigned. Verify the cluster is in an accessible project and check if the cluster uses Workload Identity.

​
Security

  • Least privilege — grant only the permissions the agents need for your use case; start read-only and widen later.
  • Read-only by default — use read-only credentials unless you want agents to make changes through this connection.
  • Rotate credentials — rotate keys and tokens on your normal schedule; CloudThinker picks up the new value when you update the connection.
  • Revoke on offboarding — remove the credential at the provider when you delete a connection or a teammate leaves.
  • Project scope — limit the service account’s IAM roles to only the GCP projects CloudThinker needs to access.
  • Key storage — store the service-account JSON in a secret manager and delete local copies after uploading to CloudThinker.
https://mintcdn.com/cloudthinker/aLd-ttc-SCW-aFky/images/icons/aws.svg?fit=max&auto=format&n=aLd-ttc-SCW-aFky&q=85&s=45d526a3e9345214c0345f277da2e829

AWS Connection

Connect Amazon Web Services

Kai Agent

Kubernetes-focused agent for GKE