> 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/getting-started/connect-your-cloud/how-to-connect-aws.md).

# Connecting to AWS

{% hint style="info" %}
**First time using Bluebricks?** The onboarding wizard walks you through connecting your cloud automatically. Follow the [Quick Start](/docs/getting-started/quick-start.md) instead.
{% endhint %}

## Prerequisites

1. A valid [AWS account](https://docs.aws.amazon.com/accounts/latest/reference/manage-acct-creating.html)
2. Permissions to create CloudFormation stacks and IAM roles in your AWS account

## How to connect in the Bluebricks app

{% stepper %}
{% step %}

### Create a collection and launch CloudFormation

1. Go to the **Collections** page
2. Click **Create Collection**
3. Name the collection (for example, `production` or `staging`)
4. Select **AWS** as the cloud provider
5. In the **Account Number** dropdown, click **New Account**
6. Click **Launch CloudFormation stack**

This opens the AWS CloudFormation console with the Bluebricks template, stack name, and your External ID prefilled.
{% endstep %}

{% step %}

### Create the stack in AWS

Review the prefilled stack details, scroll to the bottom, acknowledge the IAM capabilities checkbox, and click **Create stack**. Wait for the stack to reach **CREATE\_COMPLETE** status. This usually takes under a minute.
{% endstep %}

{% step %}

### Copy the Role ARN

Open the **Outputs** tab in the CloudFormation console. The stack provisions IAM roles that Bluebricks uses to access your AWS account. You need at least one Role ARN, but we recommend providing both for full visibility and deployment capabilities.

* **Discovery Role ARN**: grants read-only access for resource discovery, inventory, and the [context layer](/docs/getting-started/building-blocks.md#the-context-layer). Required for the agent to see what is running in your account
* **Orchestration Role ARN**: grants read/write access for deploying and managing infrastructure through [blueprints](/docs/orchestration/packages/blueprints-overview.md). Required for making changes through the orchestration platform

Copy the **Discovery Role ARN** and, if available, the **Orchestration Role ARN**. See [Connect your Cloud](/docs/getting-started/connect-your-cloud.md) for more details on permission types.
{% endstep %}

{% step %}

### Connect in Bluebricks

Back in the Bluebricks wizard, paste the Role ARN(s) and click **Connect & Create**. Bluebricks verifies the connection and begins ingesting your cloud resources into the context layer.
{% endstep %}
{% endstepper %}

## How to connect via 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 Role ARN as `roleArnId`.

## Next steps

* [Connect your Cloud](/docs/getting-started/connect-your-cloud.md): overview of all supported providers
* [Kubernetes Integration](/docs/getting-started/connect-your-cloud/kubernetes-integration.md): live cluster indexing through discovery
* [Connect your Code](/docs/getting-started/connect-your-code.md): give the agent access to your infrastructure repositories