Google Cloud Platform

CloudThinker runs the Google Cloud CLI against your projects to answer questions about compute, GKE, BigQuery, storage, identity, and cost. You connect with a service account’s JSON key, and that service account’s IAM roles decide what agents can reach.

The connection takes a service account JSON key only. Workload Identity Federation and impersonation aren’t supported.

Prerequisites

A Google Cloud project where you can create service accounts and grant IAM roles.
Permission to create service account keys. If your organization enforces constraints/iam.disableServiceAccountKeyCreation (the default on organizations created since May 2024), ask your organization policy admin for an exception on this project before you start. Policy changes can take a few minutes to apply.

The APIs for the services you want answers about, enabled in every project the connection should cover. Agents get API not enabled for any service that’s off. Enabling APIs needs Service Usage Admin (roles/serviceusage.serviceUsageAdmin) or Owner on the project. A common set, covering projects, inventory, GKE, BigQuery, IAM reviews, metrics, logs, and Cloud Storage:

APIS="cloudresourcemanager.googleapis.com serviceusage.googleapis.com \
  compute.googleapis.com container.googleapis.com bigquery.googleapis.com \
  iam.googleapis.com monitoring.googleapis.com logging.googleapis.com storage.googleapis.com"

# One project
gcloud services enable $APIS --project=PROJECT_ID

# Every project you can see, for a folder or organization grant
for P in $(gcloud projects list --format="value(projectId)"); do
  gcloud services enable $APIS --project="$P"
done

The Admin role in your CloudThinker workspace, which can add and edit connections. See Roles.
For cost questions and Optimize: a Cloud Billing Standard usage cost export to BigQuery. The export dataset must be in the same project as the service account, because Optimize only reads billing tables in the connected project. To create it, a Billing Account Administrator goes to Billing → Billing export → BigQuery export, and under Standard usage cost clicks Edit settings. See Google’s setup guide. A new export can take a few hours before its first rows appear, so Optimize may look empty on day one.

Setup

Create the service account in Google Cloud first, then upload its key to CloudThinker.

Google Cloud console
gcloud CLI

Create the service account

In the Google Cloud console, select the project and go to IAM & Admin → Service Accounts. Click Create service account, name it cloudthinker-readonly, and click Create and continue.

Grant read-only roles

Add Viewer (roles/viewer). For Optimize, also add BigQuery Job User (roles/bigquery.jobUser). Click Done. If your organization bans basic roles such as Viewer, use the predefined roles in Required permissions instead.

For Optimize: share the billing dataset

Go to BigQuery, select the billing export dataset, and click Sharing → Permissions → Add principal. Enter the service account’s email, pick BigQuery Data Viewer, and click Save. Skip it if you don’t use Optimize.

Create a JSON key

Open the service account, go to the Keys tab, and click Add key → Create new key. Choose JSON and click Create. The key file downloads once and can’t be downloaded again.

Run these in Cloud Shell or any terminal signed in to Google Cloud. Replace PROJECT_ID with your project ID.

PROJECT_ID=your-project-id
SA=cloudthinker-readonly@$PROJECT_ID.iam.gserviceaccount.com

gcloud iam service-accounts create cloudthinker-readonly \
  --project="$PROJECT_ID" --display-name="CloudThinker read-only"

gcloud projects add-iam-policy-binding "$PROJECT_ID" \
  --member="serviceAccount:$SA" --role="roles/viewer"

# Optimize only: skip these two commands if you don't use Optimize.
# Replace BILLING_DATASET with the billing export dataset's name
# and DATASET_LOCATION with its location, for example US or EU.
gcloud projects add-iam-policy-binding "$PROJECT_ID" \
  --member="serviceAccount:$SA" --role="roles/bigquery.jobUser"
bq query --project_id="$PROJECT_ID" --location=DATASET_LOCATION --use_legacy_sql=false \
  "GRANT \`roles/bigquery.dataViewer\` ON SCHEMA \`$PROJECT_ID.BILLING_DATASET\` TO 'serviceAccount:$SA'"

gcloud iam service-accounts keys create cloudthinker-key.json --iam-account="$SA"

The last command writes the key to cloudthinker-key.json. In Cloud Shell, download it to your computer with cloudshell download cloudthinker-key.json, and once it’s uploaded to CloudThinker, delete the Cloud Shell copy with rm cloudthinker-key.json.

Then connect it in CloudThinker:

Open the connect dialog

In the sidebar, click More → Workspace settings → Connections, select Google Cloud Platform, and click Connect.

Name the project

Fill in Alias (for example prod-gcp) and Description (for example Production GCP project, GKE workloads). Agents read the description to pick the right connection when you have several.

Upload the key and pick a region

Drag the JSON key file into GOOGLE_SERVICE_ACCOUNT_KEY, or click to browse for it. Pick your main region from the GCP_DEFAULT_REGION list. It defaults to us-central1. Click Connect.Success state: the status moves through Connecting and Verifying, and the project shows a Connected status. Discovery now runs once in the background and spends credits. Check the Discovery section on the detail panel before your first prompt. See What happens after you connect.

Set the environment

Open Google Cloud Platform in More → Workspace settings → Connections, click the pencil icon on the project’s row, and set Environment in Edit Instance. It labels the project for people and agents.

Ask a verification question

Open a chat and ask the verification question. The answer should list your real project IDs.

Connect more projects

Option	How	Best when
One service account, many projects	Grant the same roles to the service account in each project, or once on a folder or the organization	You want one connection that can look across projects
One connection per project	Repeat the setup in each project and click Connect again on Google Cloud Platform with a new alias	Projects belong to different teams, or sit on different billing accounts, each with its export in the connected project

An approval rule covers a whole connection, so a folder grant that mixes production and dev projects gets the same rules for all of them. Use one connection per project when they need different approval rules.

Optimize reads billing only from the project the key belongs to (its project_id), whichever option you pick. A per-project connection whose project doesn’t hold a billing export gets no Optimize cost data. The billing export covers every project on its billing account, so put the service account in the project that holds the export, grant Viewer on the folder or organization, and connect once. To grant on a folder you need Folder IAM Admin (roles/resourcemanager.folderIamAdmin). To grant on the organization you need Organization Administrator (roles/resourcemanager.organizationAdmin):

BILLING_PROJECT=your-billing-project-id
SA=cloudthinker-readonly@$BILLING_PROJECT.iam.gserviceaccount.com

# Find the organization ID, then the folder ID
gcloud organizations list
gcloud resource-manager folders list --organization=ORGANIZATION_ID

# Grant on one folder
gcloud resource-manager folders add-iam-policy-binding FOLDER_ID \
  --member="serviceAccount:$SA" --role="roles/viewer"

# Or grant on the whole organization
gcloud organizations add-iam-policy-binding ORGANIZATION_ID \
  --member="serviceAccount:$SA" --role="roles/viewer"

Connection details

Field	Description	Example
Alias	Short name for this connection. Blank picks one for you.	`prod-gcp`
Description	What the project is. Agents use it to choose between connections.	`Production GCP project`
GOOGLE_SERVICE_ACCOUNT_KEY	The service account’s JSON key file, uploaded	`cloudthinker-key.json`
GCP_DEFAULT_REGION	Starting region for agent commands, picked from a searchable list. Defaults to `us-central1`.	`us-central1`

The key file is JSON with fields such as type, project_id, private_key, and client_email. Upload it unchanged. Environment (Production, Staging, Development, or Not set) isn’t in the connect dialog. Set it after connecting, as in the setup steps: it labels the project for people and agents. Approval rules don’t read it, so a Rule that should cover one project names that connection.

Required permissions

You want	Role	Grant on
Inventory, health, and IAM questions	Viewer (`roles/viewer`)	Each project, or a folder or organization
Optimize cost data	BigQuery Data Viewer (`roles/bigquery.dataViewer`)	The billing export dataset (or the project)
Optimize cost queries	BigQuery Job User (`roles/bigquery.jobUser`)	The connected project
Agents to make specific changes	Only the narrow roles for those changes	Where the change happens. See Write access.

If your organization bans basic roles, grant predefined read roles for the areas you need in place of Viewer:

Area	Role
List projects and folders	Browser (`roles/browser`)
Compute Engine	Compute Viewer (`roles/compute.viewer`)
GKE	Kubernetes Engine Viewer (`roles/container.viewer`)
IAM reviews	Security Reviewer (`roles/iam.securityReviewer`)
Metrics	Monitoring Viewer (`roles/monitoring.viewer`)
Logs	Logs Viewer (`roles/logging.viewer`)

Viewer can’t change anything, so it’s a safe starting point. It reads data as well as configuration: in BigQuery, Viewer reads every dataset that keeps the default project-level reader access. To keep agents out of a sensitive dataset, remove that default access from it, or use a custom role instead of Viewer.

Agent capabilities

Area	What CloudThinker does
Inventory	Lists and describes Compute Engine, GKE, Cloud Storage, BigQuery, and other resources across the projects the service account can see
Identity	Reviews IAM bindings and service accounts for broad or unused access
Containers	Checks GKE cluster and node pool configuration and health
Cost	Reads your BigQuery billing export to break down spend by project, service, and label. Feeds Optimize.
Changes	Runs Google Cloud CLI writes only when Allow writes is on, the service account permits them, and your approval settings allow them

Verify the connection

Which Google Cloud projects can you reach through my GCP connection, and which services are enabled in each?

The answer lists your real project IDs. With a folder or organization grant, every project under it should appear.

Example prompts

List Compute Engine instances that have been stopped for more than 30 days and the disks still attached to them
Find service accounts with the Owner or Editor role in my projects
Break down last month's Google Cloud spend by project and service

Write access

Allow writes on the connection’s detail panel controls whether agents may change anything in Google Cloud. It’s on by default, but a service account with only Viewer and the BigQuery read roles can’t change anything, so Google Cloud refuses every write until you grant more.

IAM roles	Allow writes	Result
Read-only roles only	On or off	Read-only. Google Cloud rejects any change.
Extra write roles granted	Off	Read-only. CloudThinker refuses every change before it reaches Google Cloud.
Extra write roles granted	On	Agents can propose changes. Your Rules and Approval mode decide each one.

To lock writes in CloudThinker as well, open More → Workspace settings → Connections, select Google Cloud Platform, and turn off the Allow writes switch on its detail panel.

Troubleshooting

You can't create a key: key creation is disabled

Cause: the organization policy constraints/iam.disableServiceAccountKeyCreation is enforced.Fix: ask an organization policy admin to allow key creation for this project, or to create the key for you. If the exception is already granted, wait a few minutes: policy changes take time to apply. Also check that a policy set lower down, on the project or its folder, doesn’t still enforce the constraint.

The upload is rejected or the test fails right away

Cause: the file isn’t the original JSON key. Common cases are a P12 key, a copied snippet, or a file that was edited and lost its private_key line breaks.Fix: create a new JSON key and upload the downloaded file unchanged.

Agents get PERMISSION_DENIED or 'API not enabled'

Check: the service account has a role on the project you asked about, and the API for that service (for example Compute Engine or Kubernetes Engine) is enabled in that project.Fix: grant Viewer on the project or its folder, or enable the API under APIs & Services. No reconnect needed: the next request uses the new access.

Optimize says no billing export was found

Cause: Optimize needs a Cloud Billing Standard usage cost export table (named gcp_billing_export_v1_...) in the connected project.Fix: turn on the Standard usage cost export in Billing → Billing export, pointing at a dataset in the same project as the service account. If Optimize says the table is outside the connected project, move the export or create the service account in the project that holds it. If it asks you to select a table, pick the one you want Optimize to use.

The test shows Timed out

Cause: the test didn’t finish in time. Google Cloud endpoints are public, so it’s rarely your network.Fix: connect again. If it keeps timing out, contact us.

The connection shows Error

Cause: the key was deleted or disabled, or an organization policy (constraints/iam.serviceAccountKeyExpiryHours) expired it.Fix: create a new key, then open the connection and click Replace credentials to upload it. That opens Edit Instance, the same dialog as Replace…. Scheduled work resumes once the status is Connected.

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.

Delete local copies of the key. After you upload the JSON file, delete it from your downloads folder or store it in a secret manager. It grants the service account’s access to anyone who holds it.
Rotate at least every 90 days. Limit the key’s lifetime with the constraints/iam.serviceAccountKeyExpiryHours policy. To rotate, create a new key, click the pencil icon on the project’s row, upload it with Replace… in Edit Instance, then delete the old key under the service account’s Keys tab. See Rotate a credential.

Optimize quickstart

Turn your billing export into cost findings and savings recommendations.

Connections

Rotate credentials, set the environment, and read Discovery results.

Connections

Customize

Approvals

Workspace settings

Admin Settings

Artifacts and sharing

Prerequisites

Setup

Connect more projects

Connection details

Required permissions

Agent capabilities

Verify the connection

Example prompts

Write access

Troubleshooting

Security

Optimize quickstart

Connections

​Prerequisites

​Setup

​Connect more projects

​Connection details

​Required permissions

​Agent capabilities

​Verify the connection

​Example prompts

​Write access

​Troubleshooting

​Security

​Related

Optimize quickstart

Connections

Prerequisites

Setup

Connect more projects

Connection details

Required permissions

Agent capabilities

Verify the connection

Example prompts

Write access

Troubleshooting

Security

Related