> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cloudthinker.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Google Cloud

> Connect Google Cloud to CloudThinker for resource management, cost optimization, and security monitoring via service account

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](https://console.cloud.google.com/) accessible in your browser.

<Info>
  A viewer-level service account is sufficient for cost analysis, security audits, and resource inspection. Widen the roles only if you need write capabilities.
</Info>

***

## Setup

<Steps>
  <Step title="Create a service account">
    In the [Google Cloud Console](https://console.cloud.google.com/), 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
  </Step>

  <Step title="Assign roles">
    Grant the required viewer roles:

    * `Viewer` (basic read access)
    * `Monitoring Viewer` (for monitoring data)
    * `Security Reviewer` (for security analysis)
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>
</Steps>

<Warning>
  Store the JSON key file securely. Never commit it to version control or share it publicly.
</Warning>

### Multi-project setup

For organizations with multiple GCP projects:

<Steps>
  <Step title="Grant organization-level access">
    Grant the service account roles at the organization or folder level so it can reach all target projects.
  </Step>

  <Step title="Add billing account access">
    Add **Billing Account Viewer** for cross-project cost analysis.
  </Step>

  <Step title="Add projects">
    CloudThinker automatically discovers accessible projects after connecting.
  </Step>
</Steps>

***

## Connection details

| Field                          | Description                                                                      | Example                                                             |
| ------------------------------ | -------------------------------------------------------------------------------- | ------------------------------------------------------------------- |
| **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:

```json theme={null}
{
  "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
```

### Recommended (full analysis)

```
# 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
```

<Tip>
  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.
</Tip>

***

## Agent capabilities

Once connected, agents can analyze and optimize your GCP resources.

| Agent                              | GCP capabilities                                                                     |
| ---------------------------------- | ------------------------------------------------------------------------------------ |
| **[Alex](/guide/agents/alex)**     | Cost analysis, VM right-sizing, committed use recommendations, resource optimization |
| **[Oliver](/guide/agents/oliver)** | Security Command Center findings, IAM audits, compliance checks                      |
| **[Tony](/guide/agents/tony)**     | Cloud SQL performance, BigQuery optimization, Spanner tuning                         |
| **[Kai](/guide/agents/kai)**       | GKE cluster management, workload optimization, Autopilot analysis                    |

### Verify the connection

```text theme={null}
@alex run a GCP account check and list connected projects and active services
```

### Example prompts

```text theme={null}
@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

<Accordion title="Permission denied errors">
  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.
</Accordion>

<Accordion title="Invalid key file">
  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.
</Accordion>

<Accordion title="Missing billing data">
  Verify **Billing Account Viewer** role is assigned. Enable the Cloud Billing API and check that billing export to BigQuery is configured.
</Accordion>

<Accordion title="GKE access issues">
  Ensure **Kubernetes Engine Viewer** role is assigned. Verify the cluster is in an accessible project and check if the cluster uses Workload Identity.
</Accordion>

***

## 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.

***

## Related

<CardGroup cols={2}>
  <Card title="AWS Connection" icon="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" href="/guide/connections/aws" width="24" height="24" data-path="images/icons/aws.svg">
    Connect Amazon Web Services
  </Card>

  <Card title="Kai Agent" icon="dharmachakra" href="/guide/agents/kai">
    Kubernetes-focused agent for GKE
  </Card>
</CardGroup>