Cloud Connections

Resolve cloud account connection issues for AWS, Azure, GCP, and self-hosted infrastructure

Quick reference

Symptom	Cause	Fix
Collection missing cloud account	No cloud provider connected	Connect via the collection's Overview tab or CLI
AWS role assumption fails	Incorrect ARN or trust policy	Verify the ARN and trust relationship in AWS IAM
AWS connected but zero resources	Discovery ingestion not complete	Wait for or trigger a cloud sync
AWS discovery ingestion failed	Resource Explorer not enabled	Enable an aggregator index in the AWS account
AWS resources ingested but no EKS workloads	Missing EKS cluster access	Add AmazonEKSViewPolicy access entry for the discovery role
GCP authentication error	Service account misconfigured	Check service account impersonation and IAM role grants
GCP discovery ingestion failed	Missing discovery IAM roles	Grant Cloud Asset Viewer, Security Reviewer, and Viewer on the project
GCP resources ingested but no GKE workloads	Missing Kubernetes Engine Viewer role	Grant roles/container.viewer on the project
Self-hosted runner unreachable	BDC not installed or misconfigured	Verify Helm installation and namespace
Collection locked	Collection is inactive or deleted	Contact admin to re-enable the collection

---

Collection missing cloud account

A collection needs at least one cloud account connected before you can deploy blueprints to it.

How to fix

Bluebricks app

1. Open the collection from the Collections page

2. In the Overview tab, find the Cloud Account section

3. Click Connect Cloud Account

4. Select your cloud provider (AWS, Azure, GCP, or Self-Hosted) and follow the setup steps

CLI

List your collections and check which ones have cloud accounts:

bricks collection ls

Cloud account connection is configured through the Bluebricks app. See the provider-specific guides:

• Connect AWS

• Connect Azure

• Connect GCP

• Connect Self-Hosted

---

AWS role assumption fails

Bluebricks connects to AWS by assuming an IAM role in your account. If the role assumption fails, deployments cannot proceed.

Common causes

• Incorrect Role ARN: the ARN entered in Bluebricks does not match the role in your AWS account

• Trust policy not configured: the IAM role's trust policy does not allow Bluebricks to assume it

• Wrong ARN type: Discovery and Orchestration roles require different ARN configurations. The Bluebricks app labels these "Orchestration Role ARN" (maps to execution type in the API) and "Discovery Role ARN"

• External ID mismatch: the external ID in the IAM trust policy must match your Bluebricks organization ID

How to fix

1. Open the AWS IAM console and locate the role

2. Verify the Role ARN matches what you entered in Bluebricks

3. Check the Trust relationships tab and confirm:

   • The trust policy allows the Bluebricks principal

   • The external ID condition matches your Bluebricks organization ID

4. If you use separate ARNs for Discovery and Orchestration, ensure both are configured correctly in the collection

You can also verify your cloud accounts with:

bricks clouds ls

For step-by-step setup instructions, see Connect AWS.

---

AWS connected but zero resources

The AWS account is linked and the discovery role is configured, but the agent reports zero cloud resources in the context layer.

Common causes

• Ingestion not started or still running: discovery ingestion takes 2 to 5 minutes after connect or after you trigger a sync

• Previous ingestion failed: a failed job leaves the graph empty until a successful run completes

• Discovery role missing: the collection has an orchestration role but no discovery role configured

How to fix

1. Confirm the collection has a Discovery Role ARN configured (not just orchestration)

2. Ask the agent to check ingestion job status for the collection

3. If no job is running or the last job failed, trigger a fresh cloud sync through the agent

4. After the job reaches a ready state, ask the agent to list resources again

Unlike GCP, AWS connections start discovery ingestion automatically after connect when a discovery role is present.

---

AWS discovery ingestion failed

Discovery scans your AWS account through Steampipe, which queries AWS Resource Explorer v2 as a cross-region inventory index, then hydrates resource details from per-service APIs. If Resource Explorer is not enabled, ingestion fails before any resources are indexed.

Common causes

• Resource Explorer not enabled: no Resource Explorer index exists in the account. Steampipe cannot list supported regions or search resources

• CloudFormation stack created with Resource Explorer disabled: the Bluebricks connector template sets up an aggregator index by default, but the Resource Explorer parameter can be set to Disabled

• Discovery role lacks read access: the discovery IAM role does not have permissions to call Resource Explorer (resource-explorer-2:ListIndexes, resource-explorer-2:Search) and other read APIs

• Exhausted retries: failed ingestion jobs stop retrying after repeated errors

How to fix

1. Open the AWS Resource Explorer console in the connected account

2. If Resource Explorer is off, turn it on and create an aggregator index (recommended for multi-region discovery)

3. If you used the Bluebricks CloudFormation template, verify the Resource Explorer parameter was not set to Disabled. Update or redeploy the stack with Aggregator selected

4. Confirm the discovery IAM role has read-only access. The Bluebricks connector template attaches ReadOnlyAccess, which includes the Resource Explorer permissions discovery needs

5. Trigger a fresh ingestion through the agent after the index is active

Typical error messages:

• Resource Explorer failed to fetch supported regions

• No Resource Explorer index found

For initial setup, use the Bluebricks CloudFormation connector template from Connect AWS. It creates the discovery role and aggregator index together.

---

AWS resources ingested but no EKS workloads

Cloud discovery lists EKS clusters, but live Kubernetes objects (Pods, Deployments, Jobs) never appear in the agent.

Common causes

• Missing EKS access entry: the discovery IAM role lacks an EKS access entry with AmazonEKSViewPolicy

• Cluster API unreachable: private-only API endpoints or IP allowlists block Bluebricks from polling the cluster

How to fix

1. Confirm the EKS cluster appears in AWS as a managed cluster resource

2. Create an EKS access entry for the discovery IAM role and attach the AmazonEKSViewPolicy access policy at cluster scope

3. If the cluster API is restricted, allow Bluebricks egress IP ranges on the control plane

See Kubernetes Integration for provider-specific permissions and network requirements.

---

GCP authentication error

Bluebricks connects to GCP using service account impersonation. Bluebricks creates a dedicated service account per project and uses it to access your Google Cloud resources. Authentication failures usually stem from missing IAM role grants on your project.

Common causes

• Discovery roles not granted: the Bluebricks service account lacks Cloud Asset Viewer, Security Reviewer, or Viewer on your project

• Wrong project: IAM roles were granted on a different project than the one connected in Bluebricks

• Orchestration roles missing: the service account lacks Editor when deploying blueprints

• Roles not yet propagated: IAM changes can take a few minutes to take effect

How to fix

1. Open the GCP IAM console for the connected project and verify the Bluebricks service account is listed as a principal

2. Confirm these discovery roles are granted:

   • roles/cloudasset.viewer (Cloud Asset Viewer)

   • roles/iam.securityReviewer (Security Reviewer)

   • roles/viewer (Viewer)

3. If deploying blueprints, also grant roles/editor (Editor)

4. If using GKE live indexing, also grant roles/container.viewer (Kubernetes Engine Viewer)

5. After granting roles, trigger a fresh discovery ingestion (GCP does not auto-ingest on connect)

For step-by-step setup instructions, see Connect GCP.

---

GCP discovery ingestion failed

Discovery ingestion scans Cloud Asset Inventory and indexes resources into the context layer. If ingestion fails, the agent cannot answer questions about your cloud resources.

Common causes

• Cloud Asset Viewer missing: ingestion cannot query Cloud Asset Inventory without roles/cloudasset.viewer

• Security Reviewer or Viewer missing: IAM and resource reads fail without roles/iam.securityReviewer and roles/viewer

• Ingestion never triggered: GCP connections do not start discovery automatically after connect

• Exhausted retries: failed ingestion jobs stop retrying after repeated permission errors

How to fix

1. Copy the Bluebricks service account email from the collection's cloud connection settings

2. Grant all three discovery roles on your Google Cloud project:

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

PROJECT_ID="my-gcp-project-id"
SA_EMAIL="[e-mail]"

for ROLE in \
  roles/cloudasset.viewer \
  roles/iam.securityReviewer \
  roles/viewer; do
  gcloud projects add-iam-policy-binding "$PROJECT_ID" \
    --member="serviceAccount:${SA_EMAIL}" \
    --role="$ROLE"
done

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}".

1. Wait a few minutes for IAM propagation, then trigger a fresh ingestion through the agent or API

2. Ask the agent to check ingestion job status for your collection

For GKE workload indexing, also grant roles/container.viewer. See Kubernetes Integration.

---

GCP resources ingested but no GKE workloads

Cloud discovery lists GKE clusters, but live Kubernetes objects (Pods, Deployments, Jobs) never appear in the agent.

Common causes

• Missing Kubernetes Engine Viewer role: the Bluebricks service account lacks roles/container.viewer on the project

• Cluster API unreachable: private-only API endpoints or authorized networks block Bluebricks from polling the cluster

How to fix

1. Confirm the GKE cluster appears in Google Cloud as a managed cluster resource

2. Grant Kubernetes Engine Viewer (roles/container.viewer) to the Bluebricks service account on the connected project:

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="[e-mail]"

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

1. If the cluster API is restricted, allow Bluebricks egress IP ranges on the control plane

2. Trigger a fresh discovery ingestion after IAM propagation

See Kubernetes Integration for provider-specific permissions and network requirements.

---

Self-hosted runner unreachable

If Bluebricks cannot communicate with your self-hosted runner, deployments fail or hang.

Common causes

• BDC not installed: the Bluebricks Deployments Controller (BDC) is not deployed in your cluster

• Wrong namespace: the collection is looking for BDC in a different namespace

• Network issues: firewall rules block communication between BDC and the Bluebricks API

How to fix

1. Verify BDC is running:

kubectl get pods -n <bdc-namespace> | grep bdc

1. Check BDC logs for errors:

kubectl logs -f -l app.kubernetes.io/name=bluebricks-deployments-controller -n <bdc-namespace>

1. Confirm the runner can reach api.bluebricks.co on port 443

2. If BDC is not installed, follow the Self-Hosted Runner installation guide

---

Collection locked

A collection is locked when it has been deactivated or deleted by an admin. Unlike other issues on this page, a locked collection will not resolve on its own.

How to fix

• Check status: open the collection in the Bluebricks app to see if it is inactive or deleted

• Re-enable: ask your organization admin to re-enable the collection

• Use a different collection: if the collection was intentionally deactivated, deploy to a different active collection

---

Need more help?

1. Verify your cloud credentials are valid outside of Bluebricks (for example, use the AWS CLI or gcloud to test access)

2. Check Managing Cloud Accounts for account management steps

3. Contact support with your cloud provider, collection name, and error message