# 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          |
| GCP authentication error         | Service account misconfigured      | Check workload identity federation or service account key |
| 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 cloud 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 %}

***

## GCP authentication error

Bluebricks connects to GCP using service account impersonation via workload identity federation. Bluebricks creates a managed service account and impersonates it during deployments. Authentication failures usually stem from misconfigured federation or missing permissions.

### Common causes

* **Workload identity federation misconfigured**: the federation pool or provider settings are incorrect
* **Service account impersonation not granted**: the Bluebricks principal cannot impersonate the managed service account
* **Missing IAM permissions**: the service account lacks the required roles for the target project

### How to fix

1. Open the GCP IAM console and verify the service account exists and is enabled
2. Check workload identity federation settings:
   * The workload identity pool is configured correctly
   * The provider allows the Bluebricks principal
   * The service account has the `roles/iam.workloadIdentityUser` binding
3. Ensure the service account has the necessary IAM roles for the APIs your blueprints use

{% 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 %}

***

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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://bluebricks.co/docs/help/troubleshooting/cloud-connections.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.