# Connecting Google Cloud

Connect a Google Cloud project, or every project under an organization or folder, so Eraser can draw architecture diagrams from the infrastructure you actually have deployed. Eraser reads your projects through a service account you create yourself, and that account holds only read roles.

## Quick overview

1. Choose the host project ([how-to](/connecting-google-cloud#1-choose-the-host-project))
2. Create the connector service account ([how-to](/connecting-google-cloud#2-create-the-connector-service-account))
3. Grant read access, **per project** or on **an organization or folder** ([how-to](/connecting-google-cloud#3-grant-read-access))
4. Let Eraser use the account ([how-to](/connecting-google-cloud#4-let-eraser-use-the-account))
5. Enable the APIs ([how-to](/connecting-google-cloud#5-enable-the-apis))
6. Pick the projects to import ([how-to](/connecting-google-cloud#6-pick-the-projects-to-import))

Only step 3 changes depending on how much you want Eraser to see. The rest is the same either way.

## What Eraser gets access to

You create a service account and grant it three roles on the projects Eraser should read: **Cloud Asset Viewer**, **Browser**, and **Compute Viewer**. Together they allow listing resources and reading their configuration – they do not grant access to the contents of your buckets, databases, or secrets.

No key file is created. Instead, you grant Eraser's scanner the **Service Account Token Creator** role on the account, and Google Cloud issues a short-lived token at scan time.

Eraser checks the account before it accepts the connection, and refuses anything broader than read access – including write permissions inherited from a folder or the organization.

## Choose a scope

Open **Settings → Cloud connect**, choose **Connect a cloud environment**, and pick **GCP**.

<Figure src="/assets/cloud-gcp-connect-pane.png" alt="The Connect GCP form in Eraser, with Single project selected" border />

* **Single project** grants read access on one project at a time.
* **Multiple projects** grants read access once on an organization or folder, which covers every project beneath it.

## 1. Choose the host project

The host project is where the service account will live. It does not decide what Eraser can read – that is decided by the access you grant in step 3.

Choose **Open Manage resources in Google Cloud**, find the project in the list, and copy its **ID**.

<Figure src="/assets/cloud-gcp-manage-resources.png" alt="The Manage resources page in Google Cloud, listing projects and their IDs" border />

Paste it into the **Host project ID** field in Eraser.

## 2. Create the connector service account

<Callout kind="warning" title="Required role">
Steps 2 and 4 need permission to create and manage service accounts in the host project, such as **Service Account Admin**.
</Callout>

Eraser gives you two values for the new account:

<Figure src="/assets/cloud-gcp-sa-values.png" alt="The Name and Account ID values in Eraser, each with a Copy button" border />

Choose **Open Service accounts in Google Cloud**, then **Create service account**. Paste the **Name**, then paste the **Account ID** over the **Service account ID** field.

<Callout kind="warning" title="Overwrite the Service account ID">
The console fills in **Service account ID** automatically from the name. Replace it with the **Account ID** from Eraser – the ID is how Eraser recognizes the account, and the connection is refused without it.
</Callout>

<Figure src="/assets/cloud-gcp-create-service-account.png" alt="The Create service account page in Google Cloud with the name and ID filled in" border />

Choose **Create and close**. Skip the optional **Permissions** and **Principals with access** sections – steps 3 and 4 cover them.

## 3. Grant read access

<Callout kind="warning" title="Required role">
Granting roles needs permission to change IAM policy on the target – **Owner** or **Project IAM Admin** on a project, **Folder IAM Admin** or **Organization Administrator** above that – so this step may be performed by a different person than step 2.
</Callout>

Once the host project ID is in place, Eraser shows the account's full email address:

<Figure src="/assets/cloud-gcp-grant-value.png" alt="The New principals value in Eraser, with a Copy button" border />

Choose **Open the IAM page**. The **resource picker at the top** of that page opens this dialog, listing the organization, its folders, and their projects. Whichever row you pick is the level the grant lands on.

<Figure src="/assets/cloud-gcp-select-resource.png" alt="The Select a resource dialog in Google Cloud, showing the organization, a folder, and its projects" border />

<Callout kind="note">
The IAM page looks identical at every level of the hierarchy. Check the picker before granting – a grant on the wrong project or folder is easy to miss.
</Callout>

Follow whichever section matches the scope you picked.

### On each project

In the picker, choose a project Eraser should read, then choose **Grant access**.

Paste the email under **New principals**, then add three roles: **Cloud Asset Viewer**, **Browser**, and **Compute Viewer**. Choose **Save**.

<Figure src="/assets/cloud-gcp-grant-access-project.png" alt="The Grant access panel for a project, with the three roles added" border />

Repeat for every project Eraser should map. You choose which of them to import in step 6.

### On an organization or folder

In the picker, choose the organization or folder, then choose **Grant access**.

Paste the email under **New principals**, then add the same three roles: **Cloud Asset Viewer**, **Browser**, and **Compute Viewer**. Choose **Save**.

<Figure src="/assets/cloud-gcp-grant-access-folder.png" alt="The Grant access panel for a folder, with the three roles added" border />

## 4. Let Eraser use the account

Eraser gives you the principal to add:

<Figure src="/assets/cloud-gcp-principal-value.png" alt="The Principal value in Eraser, with a Copy button" border />

Choose **Open Service accounts in Google Cloud**, open the connector account, and select its **Principals with access** tab.

<Figure src="/assets/cloud-gcp-principals-with-access.png" alt="The Principals with access tab of the connector service account" border />

<Callout kind="note">
This is a different tab from **Permissions**. Permissions lists what the account can read; Principals with access lists who may use it. Older consoles label this tab **Permissions** as well – it is the one that offers **Grant access**.
</Callout>

Choose **Grant access**, paste the principal, and add one role: **Service Account Token Creator**. Choose **Save**.

<Figure src="/assets/cloud-gcp-grant-token-creator.png" alt="The Grant access panel for the service account, with Service Account Token Creator selected" border />

## 5. Enable the APIs

Eraser reads project inventory through two APIs that must be enabled in the host project: the **Cloud Asset API** and the **Cloud Resource Manager API**.

<Figure src="/assets/cloud-gcp-enable-apis.png" alt="The Enable the APIs step in Eraser, with a button for each API" border />

Each button opens that API's page in the host project. Choose **Enable** on each, then return to Eraser and choose **Continue**.

## 6. Pick the projects to import

Eraser now shows every project the connector account can see. Tick the ones it should import.

<Figure src="/assets/cloud-gcp-pick-projects.png" alt="The project picker in Eraser, with all three projects selected" border />

Choose **Connect**, and Eraser runs its first scan. Granting the account access on another project or folder later, then reconnecting, adds more.

## Prefer the command line?

The connect form can hand you an equivalent `gcloud` script that performs steps 2 to 5 in Cloud Shell. Look for **Copy the equivalent gcloud script** at the bottom of the form.

## After connecting

Each connection appears in **Settings → Cloud connect**, listing the projects it covers and when it last synced.

* **Rescan** reads the projects again. There is no scheduled background scan – Eraser reads your environment when you ask it to.
* **Active** lets Eraser scan the connection and use it as context in AI chat. **Inactive** stops both, without discarding the connection.
* **Remove from Eraser** disconnects and forgets the connection.

Removing a connection does not delete anything in Google Cloud. To revoke access completely, also delete the connector service account.

## Troubleshooting

| What Eraser says | What it means |
|---|---|
| Could not authenticate to Google Cloud | Usually step 4. Check that the **Service Account Token Creator** grant is on the connector account's **Principals with access** tab, and that the account's ID matches the one Eraser gave you. |
| The connector service account cannot see any project | The step 3 grant is missing, or it landed on a different resource. Grant **Cloud Asset Viewer**, **Browser**, and **Compute Viewer** on the projects Eraser should read. |
| The connector service account cannot read the project inventory | **Cloud Asset Viewer** is missing on that project. Add it, as in step 3. |
| The Cloud Asset API is not enabled in that project | Enable it from step 5, then try again. |
| The Cloud Resource Manager API is not enabled in the host project | Enable it from step 5, then try again. |
| The connector service account holds write permissions | Something granted a write role – Editor, Owner, or similar – directly or through a folder or the organization. Eraser refuses write-capable access. Remove it and keep only the three read roles. |