> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sreagent.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Connect AWS with a read-only role

> Give SRE Agent read-only access to CloudWatch, CloudTrail and X-Ray through a role in your own AWS account.

export const Plan = ({tier}) => <Badge color="blue">{tier} plan</Badge>;

CloudWatch Metrics, CloudWatch Logs, CloudTrail and X-Ray data sources read from your AWS account.

<Plan tier="Free" />

Rather than hand over access keys, you create a role in your account that SRE Agent assumes for a short time to read. Two pieces make that safe.

* **The role** is a set of read-only permissions that lives in your AWS account. You create it, you control it, and you can delete it at any time. You do not paste any access keys for it.
* **The External ID** is a value that must accompany every request to assume the role. Your role's trust policy requires it, so a request that does not carry it is refused. It is the same for every AWS data source in your organization, so you set up the trust once and reuse the role. It is not a secret.

The form also shows **Principal to trust**, the identity that is allowed to assume your role. It is not a secret either: on its own it grants nothing, because every request must also carry your External ID.

<Steps>
  <Step title="Start the data source">
    Add a data source as described in [Connect your data](/guides/get-started/connect-your-data) and choose an AWS type, for example **CloudWatch Metrics**. Pick your **AWS Regions**. Set **Authentication** to **AWS Assume Role**.
  </Step>

  <Step title="Copy the trust values">
    The form shows a read-only **External ID (one per organization)** and, once shown, **Principal to trust**. You need both when you create the role. Enter the ARN of the role you are about to create in **Role ARN**, for example `arn:aws:iam::<aws-account-id>:role/sre-agent-readonly`, and select **Save Data Source**. Save now: SRE Agent does not check the role when you save, and the test fails until the role exists, so you run it in the last step.
  </Step>

  <Step title="Get the exact permissions">
    Go to **Settings**, then the **Infrastructure** tab. Under **Required AWS permissions**, select **Show the policy**. This panel is built from the data sources you have saved, which is why you saved first. The **Read-only role** block lists every permission your organization needs and which data source asked for it. Open **Permissions policy (JSON)** for the policy. When they are shown, a trust policy that already carries your External ID, a **Terraform** block and an **AWS CLI** block are available too. If you would rather build the role without saving first, the open-source Terraform modules linked on this tab and in the data source form create the role, its policy and the trust condition for you.
  </Step>

  <Step title="Create the role in AWS">
    In your AWS account, create the role with that permissions policy and trust policy, using the same name you entered in **Role ARN**.
  </Step>

  <Step title="Check and test">
    Back in **Required AWS permissions**, select **Check the role has these** to verify the role allows each action. Then go to **Data Sources** and select the signal button on the card, or **Test Connection** inside the edit form.
  </Step>
</Steps>

<Warning>
  Keep the read-only role read-only. Remediation features use a separate connector and a separate
  role under **Infrastructure**, so an account that can be read is never writable through a data
  source.
</Warning>

## What you see

A passing test shows `Connection successful!`. If the role is missing a permission, the failure names the denied action, and the form explains which permission to add. A trust policy that is missing the External ID condition is the most common reason a role works when you try it by hand but fails here.

If queries return nothing although the permissions are right, check the regions selected on the data source first. For the other data source types, see [Connect your data](/guides/get-started/connect-your-data).

## Related

* [Write and run runbooks](/guides/prevent/runbooks): runbook steps use a separate connector, not this role.
* [Review security findings](/guides/security-cost/security): the Security page reads the same AWS account.
* [Troubleshooting](/guides/reference/troubleshooting): what to check when queries return nothing.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.