> For the complete documentation index, see [llms.txt](https://bluebricks.co/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://bluebricks.co/docs/help/troubleshooting/cloud-connections.md).

# Cloud Connections

## 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

{% tabs %}
{% tab title="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
   {% endtab %}

{% tab title="CLI" %}
List your collections and check which ones have cloud accounts:

```bash
bricks collection ls
```

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

* [Connect AWS](https://docs.bluebricks.co/bluebricks-documentation/getting-started/connect-your-cloud/how-to-connect-aws)
* [Connect Azure](https://docs.bluebricks.co/bluebricks-documentation/getting-started/connect-your-cloud/how-to-connect-azure)
* [Connect GCP](https://docs.bluebricks.co/bluebricks-documentation/getting-started/connect-your-cloud/how-to-connect-gcp)
* [Connect Self-Hosted](https://docs.bluebricks.co/bluebricks-documentation/security/bluebricks-self-hosted-runner/what-is-a-self-hosted-cloud)
  {% endtab %}
  {% endtabs %}

***

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

```bash
bricks clouds ls
```

{% hint style="info" %}
For step-by-step setup instructions, see [Connect AWS](https://docs.bluebricks.co/bluebricks-documentation/getting-started/connect-your-cloud/how-to-connect-aws).
{% endhint %}

***

## 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](https://docs.bluebricks.co/bluebricks-documentation/agent/agents-overview) 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

{% hint style="info" %}
Unlike GCP, AWS connections start discovery ingestion automatically after connect when a discovery role is present.
{% endhint %}

***

## AWS discovery ingestion failed

Discovery scans your AWS account through [Steampipe](https://steampipe.io/), 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](https://console.aws.amazon.com/resource-explorer/home) 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`

{% hint style="info" %}
For initial setup, use the Bluebricks CloudFormation connector template from [Connect AWS](https://docs.bluebricks.co/bluebricks-documentation/getting-started/connect-your-cloud/how-to-connect-aws). It creates the discovery role and aggregator index together.
{% endhint %}

***

## 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](https://docs.bluebricks.co/bluebricks-documentation/security/netwrok-access-requirements#ip-whitelist) on the control plane

{% hint style="info" %}
See [Kubernetes Integration](https://docs.bluebricks.co/bluebricks-documentation/getting-started/connect-your-cloud/kubernetes-integration) for provider-specific permissions and network requirements.
{% endhint %}

***

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

{% hint style="info" %}
For step-by-step setup instructions, see [Connect GCP](https://docs.bluebricks.co/bluebricks-documentation/getting-started/connect-your-cloud/how-to-connect-gcp).
{% endhint %}

***

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

```bash
PROJECT_ID="my-gcp-project-id"
SA_EMAIL="bluebricks-sa@my-gcp-project-id.iam.gserviceaccount.com"

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

3. Wait a few minutes for IAM propagation, then trigger a fresh ingestion through the agent or API
4. Ask the agent to check ingestion job status for your collection

{% hint style="info" %}
For GKE workload indexing, also grant `roles/container.viewer`. See [Kubernetes Integration](https://docs.bluebricks.co/bluebricks-documentation/getting-started/connect-your-cloud/kubernetes-integration).
{% endhint %}

***

## 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](https://cloud.google.com/kubernetes-engine/docs/how-to/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:

```bash
# 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"
```

3. If the cluster API is restricted, allow [Bluebricks egress IP ranges](https://docs.bluebricks.co/bluebricks-documentation/security/netwrok-access-requirements#ip-whitelist) on the control plane
4. Trigger a fresh discovery ingestion after IAM propagation

{% hint style="info" %}
See [Kubernetes Integration](https://docs.bluebricks.co/bluebricks-documentation/getting-started/connect-your-cloud/kubernetes-integration) for provider-specific permissions and network requirements.
{% endhint %}

***

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

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

2. Check BDC logs for errors:

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

3. Confirm the runner can reach `api.bluebricks.co` on port 443
4. If BDC is not installed, follow the [Self-Hosted Runner](https://docs.bluebricks.co/bluebricks-documentation/security/bluebricks-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](https://docs.bluebricks.co/bluebricks-documentation/orchestration/collections/managing-collections) for account management steps
3. [Contact support](https://www.bluebricks.co/support) with your cloud provider, collection name, and error message