# 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                | Migration or maintenance in progress | Wait for the operation to complete                        |

***

## 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, 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/collection/what-is-a-cloud-account/how-to-connect-aws)
* [Connect GCP](https://docs.bluebricks.co/bluebricks-documentation/collection/what-is-a-cloud-account/how-to-connect-gcp)
* [Connect Self-Hosted](https://docs.bluebricks.co/bluebricks-documentation/collection/what-is-a-cloud-account/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 require different ARN configurations

### 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
4. If you use separate ARNs for Discovery and Orchestration, ensure both are configured correctly in the collection

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

***

## GCP authentication error

Bluebricks connects to GCP using a service account. Authentication failures usually stem from misconfigured credentials or missing permissions.

### Common causes

* **Service account key expired or revoked**: the JSON key file is no longer valid
* **Workload identity federation misconfigured**: the federation pool or provider settings are incorrect
* **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. If using a key file, generate a new key and update the connection in Bluebricks
3. If using workload identity federation, verify:
   * The workload identity pool is configured correctly
   * The provider allows the Bluebricks principal
   * The service account has the `roles/iam.workloadIdentityUser` binding
4. 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/collection/what-is-a-cloud-account/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 deployment/bdc-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

Collections can be temporarily locked during maintenance operations or migrations.

### How to fix

* **Wait**: the lock typically clears automatically when the operation completes
* **Check status**: open the collection in the Bluebricks app to see if a migration or operation is in progress
* **Contact admin**: if the lock persists, contact your organization admin

***

## Still stuck?

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/core-concepts/collections/managing-collections) for account management steps
3. [Contact support](https://www.bluebricks.co/support) with your cloud provider, collection name, and error message