Connect GCP

  8 minute read  

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.

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.
2. In the sidebar, go to Settings > Connections.
3. Next to GCP, select Add Connection.
4. Select Connect with Google.
5. 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.

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.

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):

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

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.
2. Each check shows a pass/fail status. Failed permission checks display the missing role. Select Re-run to revalidate after resolving any failures.
3. 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.
2. Next to GCP, select Add Connection.
3. Select Use setup script.
4. Select a script type:
   • Terraform: Generates a .tf configuration file
   • gcloud: Generates a shell script using the gcloud CLI
5. Enter your GCP details:
   • Billing account IDs (comma-separated)
   • Project IDs (comma-separated)
6. Select Generate script.
7. Review the generated script and select Copy to copy it to your clipboard.

Run the script

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

Register the connection

1. Return to the CloudBolt Platform and expand the Paste script output section.
2. 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)
3. 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