# Connect GCP

> Connect your GCP environment to the CloudBolt Platform

---

Site [llms.txt](/llms.txt)

---

Connect your Google Cloud Platform (GCP) environment to the CloudBolt Platform to enable cost analysis, resource inventory, and optimization recommendations across your GCP projects.

CloudBolt offers two connection methods:

- **OAuth connect (recommended):** Sign in with Google to let CloudBolt automatically discover and provision resources.
- **Setup script (manual):** Generate a Terraform or gcloud script to run in your own environment for full control.

Both methods create a Workload Identity Federation (WIF) credential that CloudBolt uses for ongoing, passwordless data collection.

You can onboard multiple billing accounts in a single session. Each billing account becomes its own connection, and all connections share the same service account, WIF pool, and FOCUS export bucket, hosted in a GCP project you choose. After onboarding, CloudBolt runs the daily billing data export on its own schedule, so no scheduled queries or transfer jobs run in your environment.

## Prerequisites

Before you begin, ensure you have:

- A GCP account with access to the billing accounts and projects you want to monitor.
- One of the following roles:
  - **Billing Account Viewer** on each billing account (for read-only billing discovery)
  - **Billing Account Administrator** (if you want CloudBolt to provision billing-side resources)
  - Permission to grant IAM roles at the **organization** level. CloudBolt assigns read-only Viewer roles at organization scope so that new projects are covered automatically. If organization-level access cannot be granted, provisioning falls back to per-project Viewer roles on the selected projects.
- A **detailed BigQuery billing export** configured for each billing account you want to onboard. If one is missing, enable it in the GCP Console under **Billing** > **Billing export** > **BigQuery export**, then restart discovery.
- A modern web browser with popups enabled for your CloudBolt Platform instance.
- **Admin** access to your CloudBolt Platform instance. Refer to [Manage roles](/docs/cbp/getting-started/manage-organizations-users-roles/roles/).

## OAuth connect (recommended)

### Step 1: Sign in with Google

1. Log in to the CloudBolt Platform. The address depends on where your organization's tenant is hosted; see [Sign in](/docs/cbp/getting-started/#sign-in).
1. In the sidebar, go to **Settings** > **Connections**.
1. Next to GCP, select **Add Connection**.
1. Select **Connect with Google**.
1. In the sign-in pop-up, sign in and grant the requested permissions:
   - Cloud Platform access
   - Billing read-only access

After sign-in, CloudBolt discovers your GCP environment. The button displays **Discovering GCP resources…** while discovery runs; this can take a minute or two for large organizations.

<div class="alert alert-info" role="alert">


If the pop-up does not appear, check that your browser allows pop-ups for this site.
</div>


### Step 2: Select your GCP organization

If your Google account has access to multiple GCP organizations, select the organization you want CloudBolt to monitor, then select **Continue**. The CloudBolt service account receives read-only IAM bindings at this organization's scope.

If your account has access to only one organization, this step is automatic.

### Step 3: Select scope

Choose which billing accounts CloudBolt should monitor. Each selected billing account becomes its own connection.

**Billing accounts:**

- Select one or more billing accounts. Use **Select all**/**Deselect all** for bulk selection. Each account shows its display name and ID, plus badges where relevant:
  - **Export active**: a BigQuery billing export dataset already exists for this account.
  - A region badge (for example, **US** or **EU**): the BigQuery region of the account's export dataset.
  - **Sub-account**: a sub-account whose master billing account is not visible to your user. Onboarding it is fine, but if the master is later onboarded under another connection, remove this one to avoid double-counting costs.
- All billing accounts selected together must use BigQuery datasets in the **same region**. Accounts in a different region are disabled in the list. Onboard each region in its own session.
- Billing accounts without a detailed billing export cannot be onboarded and block submission until the export is enabled and discovery is re-run.

<div class="alert alert-info" role="alert">


If no billing accounts are found, CloudBolt can still monitor resource inventory, but cost data requires billing viewer access.
</div>


**CloudBolt project:**

Pick the GCP project that will host CloudBolt's service account, Workload Identity pool, and FOCUS export bucket. Projects that contain a selected billing account's export dataset are marked with a **Billing data** badge. CloudBolt reads inventory and recommendations across every project in your organization via an organization-level Viewer role, so there is no per-project opt-in to set.

Select **Set up GCP resources** to proceed to provisioning.

### Step 4: Provisioning

CloudBolt automatically provisions the required GCP resources, shown in two groups.

**Shared infrastructure** (created once, shared by all connections):

| Step | Purpose |
| --- | --- |
| Enable GCP APIs | Enables the required APIs on the CloudBolt project (BigQuery, Cloud Billing, Storage, IAM, Resource Manager, Recommender) |
| GCS export bucket | Storage for billing data exports |
| Service account | Dedicated service account for CloudBolt |
| WIF pool | Creates a Workload Identity Federation pool |
| WIF provider | Configures the OIDC identity provider |
| WIF → Service Account binding | Binds the WIF provider to the service account |
| Organization-wide IAM viewer roles | Grants read-only Viewer roles at organization scope |
| Project-scope IAM viewer roles | Fallback per-project Viewer grants when organization scope is unavailable |
| GCS bucket access | Grants storage read access |

**Billing accounts:** each selected billing account provisions its own row of steps:

| Step | Purpose |
| --- | --- |
| BQ dataset | BigQuery dataset for FOCUS billing views |
| Billing export | Verifies the billing export feeding the dataset |
| FOCUS view | Creates the FOCUS-formatted billing view |
| FOCUS view editor grant | Grants CloudBolt permission to maintain the view |
| Dataset READER | Grants the service account dataset read access |
| Billing Viewer | Grants billing data read access on the billing account |
| BigQuery jobUser | Grants query execution permission |
| FOCUS history backfill | Automatically imports the last 12 months of billing history |
| Verify access | Confirms end-to-end access for this billing account |
| Chip refresh | Refreshes connection status indicators |

Each step displays a status indicator:

- Green checkmark: completed successfully
- Red icon: failed, with a retry option
- Amber triangle: completed with warnings
- Gray minus: skipped or requires manual action

When provisioning finishes, select **Finish**. If some billing accounts failed, you can select **Retry *n* failed** to re-attempt them, or **Save successful and finish** to continue with the accounts that provisioned successfully.

### Step 5: Validate access

Verify CloudBolt can access all required resources using the provisioned credentials.

1. Select **Run validation** to start the access checks, including WIF configuration and token exchange, BigQuery access, resource inventory, billing access, and your billing account and project selections.
1. Each check shows a pass/fail status. Failed permission checks display the missing role. Select **Re-run** to revalidate after resolving any failures.
1. Select **Finish setup** (or **Finish with warnings** to continue without resolving errors) to save the configuration.

CloudBolt redirects you to the Connections page. Historical data continues importing in the background.

## Setup script (manual)

Use this option if you prefer to provision GCP resources using your own infrastructure-as-code workflow.

### Generate the script

1. In the CloudBolt Platform sidebar, go to **Settings** > **Connections**.
1. Next to GCP, select **Add Connection**.
1. Select **Use setup script**.
1. Select a script type:
   - **Terraform:** Generates a `.tf` configuration file
   - **gcloud:** Generates a shell script using the gcloud CLI
1. Enter your GCP details:
   - **Billing account IDs** (comma-separated)
   - **Project IDs** (comma-separated)
1. Select **Generate script**.
1. Review the generated script and select **Copy** to copy it to your clipboard.

### Run the script

1. Open your terminal or Google Cloud Shell.
1. Paste and run the generated script.
1. When the script completes, it outputs configuration values.

### Register the connection

1. Return to the CloudBolt Platform and expand the **Paste script output** section.
1. Enter the script output values:
   - **GCP Project Number**
   - **WIF Pool ID** (for example, `cloudbolt-pool`)
   - **WIF Provider ID** (for example, `cloudbolt-auth0`)
   - **Service Account Email** (for example, `cloudbolt-collector@project.iam.gserviceaccount.com`)
   - **GCS Bucket Name** (for example, `cloudbolt-focus-export-xxxxxx`)
1. Select **Register connection**. CloudBolt validates and saves the configuration, then prompts you to validate access.

## Manage connections

Each onboarded billing account appears as its own connection under **Settings** > **Connections**. Open a connection to view its details:

- **Project ID** and **Project Number**
- **Billing Account**
- **Service Account**
- **FOCUS Bucket**
- **WIF Pool** and **WIF Provider**

### Disconnect a billing account

To disconnect, open the connection and select **Disconnect billing account**. Disconnecting requires a fresh Google sign-in with an account that has **Billing Account Administrator** on the billing account and owner-equivalent access on the CloudBolt project.

Disconnecting revokes the Billing Viewer role on that billing account and the READER access on its BigQuery dataset. Shared resources (the service account, WIF pool and provider, organization-level Viewer bindings, and the export bucket) are left in place while other billing accounts still use them. Disconnecting the **last** billing account also tears down the shared resources, and reconnecting afterward requires running the full setup again.

## Troubleshooting

| Issue | Solution |
| --- | --- |
| The Google sign-in pop-up does not appear | Enable pop-ups for your CloudBolt Platform URL in your browser settings |
| "Access was denied" during sign-in | Ensure you grant all requested permissions in the Google consent screen |
| No billing accounts discovered | Verify your Google account has the Billing Account Viewer role on the target billing account |
| "These billing accounts have no detailed billing export and can't be onboarded yet" | Enable billing export in the GCP Console (**Billing** > **Billing export** > **BigQuery export**), then re-run discovery |
| A billing account is disabled in the scope list | Its BigQuery dataset is in a different region than the accounts already selected. Onboard each region in its own session. |
| "Discovery session was lost" | The discovery session expired. Start the GCP connection flow again. |
| Provisioning step fails | Select the retry option on the failed step, and check that your account has the required IAM roles |
| Validation shows "forbidden" | The service account is missing a required role. The validation result shows which role is needed; assign it in the GCP Console under **IAM & Admin**. |
| WIF authentication fails | Verify that the WIF pool, provider, and service account binding are correctly configured. Re-run the setup script if needed. |