# Connecting to AWS

## Prerequisites

1. A valid [AWS Account](https://docs.aws.amazon.com/accounts/latest/reference/manage-acct-creating.html).
2. A [Bluebricks collection](https://bluebricks.co/docs/core-concepts/collections/create-an-environment).

## Step 1: Create Role ARN using CloudFormation Stack

1. [Download Bluebricks CloudFormation Stack](https://bluebricks-public.s3.eu-north-1.amazonaws.com/cloudformation-aws-bricks-setup/cf-bricks-setup-single.json)
2. Navigate to AWS Console
3. Click the "Search" field, type "cloudformation" and click it
4. Click "Create stack" and choose "With new resources (standard)"
5. Mark "Choose an existing template", mark "Upload a template file" and click Choose file
6. Open the file you downloaded in step 1 and click Next
7. Give your stack a name and click Next
8. Acknowledge the required capabilities at the bottom of the page and click Next
9. Review and click Submit

{% hint style="info" %}
AWS supports two Role ARNs: at least one is required:

* **Discovery Role ARN**: grants read-only access for [cloud discovery](https://bluebricks.co/docs/core-concepts/discovery) and resource inventory.
* **Orchestration Role ARN**: grants read/write access for deploying and managing infrastructure through blueprints.

You can provide both to enable full visibility and deployment capabilities. See [Connect your Cloud](https://bluebricks.co/docs/core-concepts/collections/connect-your-cloud) for details on permission types.
{% endhint %}

## Step 2: Connect AWS in Bluebricks

### Using the app

1. Click **"Connect Cloud"** on the collection you want to link to **AWS**
2. Select **AWS** as the **Cloud Provider**
3. Choose an existing **Account Number** or click **"New Account"**
4. If creating a **New Account**, enter the **Role ARN ID** and **CloudFormation Stack ID**
5. Click **"Connect & Create"** to complete the setup

## Connect via CLI

You can connect an AWS cloud account to a collection using the Bricks CLI:

```bash
bricks setup aws --collection production
```

The command walks you through the AWS connection flow interactively. After setup completes, verify the connection:

```bash
bricks collection ls
```

A connected collection shows the cloud provider and account name:

```
GUID                                NAME           CLOUD PROVIDER   CLOUD ACCOUNT   SLUG              STATUS
----------------------------------- -------------- ---------------- --------------- ----------------- -------------------------
env-uuid-123                        production    AWS              aws-prod        production        DEFAULT, web-app (running)
```

An unconnected collection shows `-` for both fields:

```
GUID                                NAME           CLOUD PROVIDER   CLOUD ACCOUNT   SLUG              STATUS
----------------------------------- -------------- ---------------- --------------- ----------------- -------------------------
env-uuid-456                        development   -                -               development       -
```

{% hint style="info" %}
CLI cloud setup currently supports AWS only. To connect GCP, Azure, or a self-hosted runner, use the Bluebricks app with the provider-specific instructions above.
{% endhint %}

### Using the API

Use the [Cloud Accounts API](https://bluebricks.co/docs/api/reference/cloud-accounts) to create a cloud account. Pass the Stack ID as `cloudFormationStackId` and the RoleArn Value as `roleArnId`.

## Next steps

* [Managing Collections](https://bluebricks.co/docs/core-concepts/collections/managing-collections)
* [Connect your Cloud](https://bluebricks.co/docs/core-concepts/collections/connect-your-cloud): overview of all cloud connection types
* [CLI Reference: bricks clouds](https://bluebricks.co/docs/bricks-cli/cli-reference/bricks_clouds)