# Connecting AWS

Connect an AWS account, or an entire AWS organization, so Eraser can draw architecture diagrams from the infrastructure you actually have deployed. Eraser reads your account through an IAM role you create yourself, and that role holds nothing but AWS's read-only `SecurityAudit` policy.

## Quick overview

**Connecting a single account**

1. Launch the CloudFormation stack ([how-to](/connecting-aws#1-launch-the-cloudformation-stack))
2. Paste the Role ARN back into Eraser ([how-to](/connecting-aws#2-paste-the-role-arn))
3. Pick the accounts to import ([how-to](/connecting-aws#pick-the-accounts-to-import))

**Connecting an AWS organization**

1. Enable trusted access for StackSets ([how-to](/connecting-aws#1-enable-trusted-access))
2. Paste your organization root ID ([how-to](/connecting-aws#2-paste-your-organization-root-id))
3. Launch the stack in the management account ([how-to](/connecting-aws#3-launch-the-stack-in-the-management-account))
4. Paste the Role ARN back into Eraser ([how-to](/connecting-aws#4-paste-the-role-arn))
5. Pick the accounts to import ([how-to](/connecting-aws#pick-the-accounts-to-import))

## What Eraser gets access to

The CloudFormation stack creates one IAM role, `EraserCloudConnector`, and attaches AWS's managed **SecurityAudit** policy to it. That policy permits configuration metadata only – it does not grant access to the contents of your S3 objects, databases, or secrets.

No credentials are exchanged. Eraser assumes the role, and AWS issues a short-lived token each time.

Eraser checks the role before it accepts the connection, and refuses anything broader: a role holding any policy beyond `SecurityAudit` is rejected.

## Choose a scope

Open **Settings → Cloud connect**, choose **Connect a cloud environment**, and pick **AWS**. The first thing the form asks for is how much you want Eraser to see.

<Figure src="/assets/cloud-aws-connect-pane.png" alt="The Connect AWS form in Eraser, with Single account selected" border />

* **Single account** creates a read-only role in one account.
* **Multiple accounts** creates the same role across an AWS organization, including accounts that join later.

The steps differ from here, so follow the section that matches your choice.

## Connecting a single account

<Callout kind="warning" title="Required role">
Someone who can create IAM roles via CloudFormation in the target AWS account needs to perform the below.
</Callout>

### 1. Launch the CloudFormation stack

Choose **Launch stack in AWS**. The button opens CloudFormation's quick-create page in your own console, in the account you are signed in to, with the template and the External ID already filled in.

Tick the IAM acknowledgement at the bottom, then choose **Create stack**.

<Figure src="/assets/cloud-aws-quick-create-single.png" alt="The CloudFormation quick create stack page, with the Eraser template pre-filled" border />

### 2. Paste the Role ARN

Creating the stack takes about a minute. Once it finishes, open the stack's **Outputs** tab and copy the **RoleARN** value.

<Figure src="/assets/cloud-aws-outputs-single.png" alt="The stack Outputs tab, with the RoleARN value highlighted" border />

Paste it into the **Role ARN** field in Eraser and choose **Continue**.

## Connecting an AWS organization

Connecting at the organization level installs the same read-only role into every member account, so one setup covers your whole estate – including accounts created after you connect.

<Callout kind="warning" title="Required role">
Steps 1 to 3 are performed in the organization's **management account**, by someone who can enable trusted access and create StackSets.
</Callout>

### 1. Enable trusted access

In the management account, open **CloudFormation → StackSets** and choose **Activate trusted access** in the banner at the top. This is what lets StackSets deploy across the organization.

<Figure src="/assets/cloud-aws-stacksets-trusted-access.png" alt="The CloudFormation StackSets page showing the Activate trusted access banner" border />

No banner? It's already enabled – skip this step.

### 2. Paste your organization root ID

Open the AWS Organizations console and copy the ID beside **Root** at the top of the account list. It starts with `r-`.

<Figure src="/assets/cloud-aws-organizations-root-id.png" alt="The AWS Organizations console with the root ID highlighted" border />

Paste it into the **Organization root ID** field in Eraser.

<Callout kind="note">
The organization ID and the root ID sit next to each other and look alike. Eraser needs the **root** ID, which starts with `r-` – not the organization ID, which starts with `o-`.
</Callout>

### 3. Launch the stack in the management account

Still in the management account, choose **Launch stack in AWS**. Every field arrives pre-filled, including the root ID you just pasted.

Tick the IAM acknowledgement, then choose **Create stack**. The stack creates one read-only role in the management account, plus a StackSet that installs the same role into every member account.

<Figure src="/assets/cloud-aws-quick-create-org.png" alt="The CloudFormation quick create stack page for the organization template" border />

### 4. Paste the Role ARN

Open the stack's **Outputs** tab and copy the **RoleARN** value.

<Figure src="/assets/cloud-aws-outputs-org.png" alt="The organization stack Outputs tab, with the RoleARN value highlighted" border />

Paste it into the **Role ARN** field in Eraser and choose **Continue**.

<Callout kind="note">
The stack in the management account finishes in about a minute, but the StackSet keeps rolling the role out to member accounts for a few minutes after that. If an account is missing from the next step, give it a moment and reconnect.
</Callout>

## Pick the accounts to import

Eraser now shows every account the role can see. Tick the ones it should import.

<Figure src="/assets/cloud-aws-pick-accounts.png" alt="The account picker in Eraser, with two of six accounts selected" border />

Choose **Connect**, and Eraser runs its first scan. You can widen the selection later by reconnecting.

## After connecting

Each connection appears in **Settings → Cloud connect**, showing the account it covers and when it last synced.

* **Rescan** reads the account again. Do this after you deploy something new, or before generating a diagram that should reflect today's state. There is no scheduled background scan – Eraser reads your account when you ask it to.
* **Active** lets Eraser scan the account and use it as context in AI chat. **Inactive** stops both, without discarding the connection.
* **Remove from Eraser** disconnects and forgets the account.

Removing a connection does not delete anything in AWS. To revoke access completely, also delete the CloudFormation stack – which is the only thing the setup created.

Once a connection is active, anyone on the team can reference it in AI chat to generate architecture diagrams of that environment.

## Troubleshooting

| What Eraser says | What it means |
|---|---|
| That does not look like a role ARN | The pasted value isn't an ARN. Copy the **RoleARN** output from the stack, not the stack ID or the account number. |
| Expected an `EraserCloudConnector` role | The ARN points at some other role in the account. Copy the **RoleARN** from the Eraser stack's Outputs tab. |
| Could not assume that role | Usually the stack is still creating. Wait for it to finish; if it still fails, launch the stack again from Eraser. |
| This role's trust policy does not require the External ID | The `ExternalId` condition is missing from the trust policy. Re-run the CloudFormation stack. |
| The connector role holds policies beyond SecurityAudit | Something attached an extra policy to the role. Eraser refuses write-capable access – detach them and keep only `SecurityAudit`. |
| The role was assumed but could not read the account | The `SecurityAudit` policy is missing or was replaced. Re-run the stack to restore it. |