Ctrlk
LoginBook a Demo
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Connecting to GCP

Step-by-step guide to connect a Google Cloud project to a Bluebricks collection, grant discovery permissions, and start cloud resource ingestion

Connect a Google Cloud project to a Bluebricks collection so Bluebricks can inventory cloud resources into the context layer. After you grant the required IAM roles to the Bluebricks service account, discovery ingests your project resources and powers the agent.

Unlike AWS and Azure, GCP connections do not start discovery automatically. You must grant IAM roles on your project first, then trigger ingestion.

Prerequisites

  1. A valid Google Cloud project ID

  2. Permission to grant IAM roles on that project (roles/resourcemanager.projectIamAdmin or equivalent)

  3. A Bluebricks collection

Bluebricks uses service account impersonation to connect to GCP: no static service account keys are required. Bluebricks creates a dedicated service account per project and authenticates through Google's identity federation.

How to connect and enable discovery

1

Connect GCP in Bluebricks

  1. Click Connect Cloud on the collection you want to link to GCP

  2. Select GCP as the Cloud Provider

  3. Choose an existing Project ID or click New Project

  4. If creating a New Project, enter the Google Cloud Project ID

  5. Click Connect & Create to complete the setup

2

Copy the service account email

Bluebricks creates one service account per connected project. You grant IAM roles to this account on your project.

  1. Choose Edit on the collection options

  2. Copy the Bluebricks Service Account email (also available in the Cloud Accounts API response as service_account_email)

Use a unique service account email per project. Do not reuse the same principal across unrelated projects.

3

Grant discovery permissions

Discovery permissions are required for cloud resource ingestion, the context layer, and the agent. Without these roles, ingestion fails with IAM permission errors.

Grant the following roles to the Bluebricks service account on your Google Cloud project:

Role
IAM role ID
Purpose

Cloud Asset Viewer

roles/cloudasset.viewer

Query Cloud Asset Inventory (required for resource discovery)

Security Reviewer

roles/iam.securityReviewer

Read IAM policies and security configurations

Viewer

roles/viewer

General read-only access to project resources

  1. Open the Google Cloud console and select your project

  2. Search for IAM and open IAM & Admin

  3. Click Grant access

  4. Paste the Bluebricks service account email in New principals

  5. Assign each role from the table above (Cloud Asset Viewer, Security Reviewer, Viewer)

  6. Click Save

Set PROJECT_ID to the Google Cloud project you connected in Bluebricks. Set SA_EMAIL to the Bluebricks service account email from the previous step (format: name@PROJECT_ID.iam.gserviceaccount.com).

Prefer separate commands? Keep the same PROJECT_ID and SA_EMAIL lines above, then run each binding individually with "$PROJECT_ID" and "serviceAccount:${SA_EMAIL}".

4

Grant GKE permissions

If this project runs GKE workloads, grant one more role so Bluebricks can add live cluster details to your context layer. The agent can then answer questions about what is running inside your clusters, not just that the clusters exist.

Discovery alone lists GKE clusters as cloud resources. This step indexes in-cluster objects such as Pods, Deployments, Jobs, and Ingresses. That gives the agent a fuller picture of your environment.

Role
IAM role ID
Purpose

Kubernetes Engine Viewer

roles/container.viewer

Read GKE clusters and connect to the Kubernetes API

  1. Open IAM & Admin > IAM for your project

  2. Find the Bluebricks service account, or use Grant access if it is not listed yet

  3. Add the Kubernetes Engine Viewer role to the same principal

  4. Click Save

If your shell session is still open from the Grant discovery permissions step, PROJECT_ID and SA_EMAIL are already set. Otherwise, edit and run the full block below:

# Skip these two lines if PROJECT_ID and SA_EMAIL are already set
PROJECT_ID="my-gcp-project-id"
SA_EMAIL="bluebricks-sa@my-gcp-project-id.iam.gserviceaccount.com"

gcloud projects add-iam-policy-binding "$PROJECT_ID" \
  --member="serviceAccount:${SA_EMAIL}" \
  --role="roles/container.viewer"

Grant this role before you trigger discovery in the next steps so the first scan includes GKE workload data. No GKE in this project? Continue to the next step.

For more information, see Kubernetes Integration.

5

Trigger discovery and verify ingestion

GCP connections do not start discovery automatically. After IAM roles propagate (usually within a few minutes), trigger ingestion:

  1. Ask the agent to refresh cloud resources for your collection, or trigger ingestion through the Cloud Accounts API

  2. Wait for the ingestion job to complete (typically 2 to 5 minutes)

  3. Verify by asking the agent a project-scoped question, for example: "List compute instances in my GCP project" or "What GKE clusters are running?"

If ingestion fails with a Cloud Asset Inventory or IAM permission error, confirm all three discovery roles from the Grant discovery permissions step are granted on the correct project. Failed jobs do not retry automatically after exhausting retries.

6

Grant orchestration permissions (optional)

If you plan to deploy blueprints through Bluebricks, also grant the Editor role (roles/editor) to the same service account. This allows Bluebricks to create, modify, and destroy infrastructure in your project.

GCP uses the same service account for both discovery and orchestration. See Connect your Cloud for how permission types work across providers.

Discovery-only setups do not need the Editor role. Complete the discovery and ingestion steps above without granting orchestration permissions.

  1. Open IAM & Admin > IAM for your project

  2. Find the Bluebricks service account

  3. Add the Editor role to the same principal

  4. Click Save

If your shell session is still open from the Grant discovery permissions step, PROJECT_ID and SA_EMAIL are already set. Otherwise, edit and run the full block below:

# Skip these two lines if PROJECT_ID and SA_EMAIL are already set
PROJECT_ID="my-gcp-project-id"
SA_EMAIL="bluebricks-sa@my-gcp-project-id.iam.gserviceaccount.com"

gcloud projects add-iam-policy-binding "$PROJECT_ID" \
  --member="serviceAccount:${SA_EMAIL}" \
  --role="roles/editor"

How to connect via the API

Use the Cloud Accounts API to create a cloud account. Pass the Google Cloud project ID as accountId. The response includes the Bluebricks service account email in cloud_config.

After connecting, grant the IAM roles and trigger discovery using the steps above.

Troubleshooting

For ingestion failures, missing resources, and IAM permission errors, see Cloud Connection Troubleshooting in the Help Center.

Next steps

PreviousConnecting to Azure
NextKubernetes Integration

Last updated