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

# AWS

> Give Rootly AI read-only access to your AWS account via an IAM Role — with fine-grained service and region scoping and optional EKS support.

## Overview

Connecting AWS gives Rootly AI **read-only access** to your AWS account. Once connected, Rootly AI can look up CloudWatch metrics, EC2 instance state, RDS database status, SQS queue depth, and other AWS services during investigations — grounding its reasoning in the actual state of your infrastructure rather than best-guess inference.

Access is granted through an **IAM Role** you create in your AWS account. You control which AWS services the role can read and which regions it can operate in.

***

## Before You Start

You'll need:

* **AWS Console access** to the account you want to connect, with permission to create IAM Roles.
* **The External ID shown on the AWS connection modal in Rootly** — this is unique to your Rootly organization. Copy it when the modal opens; it goes into the trust policy on the AWS side.
* **A decision on scope** — which AWS services and regions should Rootly AI be able to read? You can start narrow and expand later.

<Note>
  All Rootly AI access to AWS is **read-only**. The IAM Role can't launch instances, modify security groups, or change any configuration — only describe existing state.
</Note>

***

## Setup Provisioning Options

You have three ways to create the IAM Role in AWS. Pick whichever matches how your team manages AWS infrastructure.

### Option 1 — CloudFormation (Recommended)

The one-click path. Rootly generates a CloudFormation template with your External ID pre-filled — review it in the AWS Console and click **Create stack**.

<Steps>
  <Step title="Copy Your External ID From Rootly">
    Open **Configuration → AI → Connectors** in Rootly and click **Connect** on the AWS card. The connection modal shows your External ID at the top — copy it now.
  </Step>

  <Step title="Launch The CloudFormation Stack">
    Click **Launch CloudFormation stack** in the AWS Configuration section of the Rootly modal. A new tab opens directly to AWS CloudFormation with the template and External ID pre-populated. Review the template — it creates one IAM Role with the read-only permissions matching the services you selected.
  </Step>

  <Step title="Create The Stack">
    Click **Create stack** in the AWS Console. Wait for the stack status to reach `CREATE_COMPLETE` — usually 30–60 seconds. Once complete, open the stack's **Outputs** tab and copy the **RoleArn** value.
  </Step>

  <Step title="Paste The Role ARN Into Rootly">
    Return to the Rootly connection modal and paste the Role ARN into the **IAM Role ARN** field. Click **Test Connection** to verify, then save.
  </Step>
</Steps>

### Option 2 — Terraform

If your team manages AWS through Terraform, Rootly provides a Terraform module in the connection modal that creates the same IAM Role. Apply the module in your Terraform workspace, copy the resulting Role ARN into the Rootly modal, and click Test Connection.

### Option 3 — Manual Console Setup

For teams that prefer clicking through the AWS Console step-by-step, or for accounts where CloudFormation isn't an option.

<Steps>
  <Step title="Open IAM > Roles In The AWS Console">
    Log in to the AWS Console for the account you want to connect. Navigate to **IAM → Roles**.
  </Step>

  <Step title="Create The Role With A Custom Trust Policy">
    Click **Create role**. Choose **Custom trust policy** as the trusted entity type. Paste the trust policy shown in the Rootly modal — it references your External ID.
  </Step>

  <Step title="Attach Permissions">
    Click **Next** and attach permissions matching the services you selected in the Rootly modal:

    * **If you selected specific services** — add a custom inline policy with exactly the read access needed for those services. Rootly displays the exact policy JSON on the connection modal.
    * **If you selected all services** — attach the AWS managed **ReadOnlyAccess** policy for account-wide read access.
  </Step>

  <Step title="Name The Role And Create It">
    Click **Next**, name the role something recognizable (e.g., `RootlyAIReadOnly`), and click **Create role**.
  </Step>

  <Step title="Copy The Role ARN Into Rootly">
    From the role detail page, copy the **Role ARN**. Paste it into the Rootly connection modal's **IAM Role ARN** field, click **Test Connection**, then save.
  </Step>
</Steps>

***

## Configuring Access Scope

Rootly AI's AWS integration accepts two scoping dimensions. Both are configured on the Rootly connection modal *before* you generate the IAM policy — the policy Rootly creates matches your selections exactly.

<ParamField path="AWS Services The Agent Can Read" type="multi-select">
  Search and select the AWS services Rootly AI should be able to describe (EC2, RDS, CloudWatch, S3, SQS, and so on). **Leave empty to allow all services** — that grants the equivalent of the AWS managed `ReadOnlyAccess` policy.

  Narrow is safer than broad. Start with the services your team actually operates; the connection can be updated later to add more services.
</ParamField>

<ParamField path="Restrict To Regions" type="multi-select">
  Search and select AWS regions Rootly AI can query. **Leave empty to allow all regions.** When set, Rootly AI directs API calls only to those regions. For a hard enforcement at the AWS side, add a `Condition` on `aws:RequestedRegion` to the role's attached permission policy (the trust policy alone cannot bound the resulting session's regional reach).
</ParamField>

<Tip>
  For most teams, "the services you operate" plus "the regions you deploy in" is the right starting scope. If your AWS presence is a single region running EC2, RDS, and CloudWatch, that's a three-service one-region role — much smaller blast radius than granting `ReadOnlyAccess` account-wide.
</Tip>

***

## Optional: EKS Support

If Rootly AI needs to query Kubernetes clusters managed by EKS (nodes, workloads, cluster events), enable the **EKS Support** section on the Rootly connection modal and follow its generated instructions.

The modal produces the narrow, read-only permission set (typically `eks:DescribeCluster`, `eks:ListClusters`, `eks:DescribeNodegroup`, `eks:ListNodegroups`, and an EKS **access entry** attaching the `AmazonEKSClusterAdminPolicy`-alternative *view* policy at cluster scope) that Rootly AI actually needs. Prefer that over broad managed policies like `AmazonEKSClusterPolicy`, which grant write actions Rootly AI never uses.

<Note>
  **EKS API access restrictions:** If your EKS cluster's API server endpoint is restricted to specific IP ranges, allow Rootly AI's outbound IPs (listed on the connection modal) so Rootly AI can reach the cluster.
</Note>

***

## Verifying The Connection

Click **Test Connection** in the Rootly modal after pasting the Role ARN. Rootly checks that the role can be used with the External ID you set, and reports back:

* **Connection verified** — the role is set up correctly. Save the integration and Rootly AI can now query AWS.
* **Assume-role failed** — the trust policy on the AWS role doesn't reference the External ID correctly. Recheck the trust policy on the AWS side.
* **Permissions insufficient** — the role works but doesn't grant the reads Rootly AI needs. Recheck the permissions policy against the services you selected.

***

## Adjusting Access After Setup

To narrow or broaden scope after the initial connection:

<Steps>
  <Step title="Open The AWS Card In Rootly">
    Configuration → AI → Connectors → click **Configure** on the AWS card.
  </Step>

  <Step title="Adjust Services Or Regions">
    Add or remove services and regions from the multi-select pickers. Rootly displays the *updated* IAM policy JSON matching your new selection.
  </Step>

  <Step title="Update The Role's Policy In AWS">
    Copy the updated policy JSON and replace the inline policy on your IAM Role in AWS. Rootly does not modify the AWS-side policy for you — the Rootly UI shows what the policy should be; you apply it on the AWS side.
  </Step>

  <Step title="Save In Rootly">
    Save the updated configuration in Rootly. New Rootly AI queries respect the new scope on the next investigation.
  </Step>
</Steps>

***

## Best Practices

* **Start with narrow service and region scope.** You can always expand. Granting broad `ReadOnlyAccess` up front makes it harder to reason about what Rootly AI has seen after the fact.
* **Use a memorable role name.** `RootlyAIReadOnly` (or similar) makes the role easy to find in IAM Roles listings and easy to identify in CloudTrail logs.
* **Guard the External ID.** The External ID keeps your Rootly connection separate from every other Rootly customer's. Don't paste it into public issues, screenshots, or Slack channels.
* **Audit AWS-side access changes.** Any change to the IAM Role's trust policy or attached permissions should go through the same review process as any other AWS IAM change.
* **Consider a dedicated AWS account for observability queries.** If you have a hub-and-spoke AWS setup with a central observability account, connect that account to Rootly AI rather than each spoke account individually.
* **Reconnect if you suspect misuse.** If you rotate the External ID or suspect the role has been misused, disconnect the integration from Rootly, delete the AWS-side role, and re-run the setup. Reconnection generates a fresh External ID.

***

## Troubleshooting

<AccordionGroup>
  <Accordion title="Test Connection returns 'AssumeRole failed'" icon="triangle-exclamation">
    Two common causes: (1) the trust policy on the AWS role doesn't reference the correct External ID — check for typos or a stale External ID from a previous connection attempt; (2) the trust policy JSON in the Rootly modal wasn't pasted correctly on the AWS side.
  </Accordion>

  <Accordion title="CloudFormation stack fails with 'Insufficient permissions'" icon="lock">
    The IAM user or role you're running CloudFormation as needs permission to create IAM Roles and attach policies. Run as an admin user, or ask an AWS admin to run the stack for you and share the resulting Role ARN.
  </Accordion>

  <Accordion title="Rootly AI's investigation cites AWS but the data looks stale" icon="clock">
    AWS returns current state at the moment of the query. If it looks stale, check what the AWS Console shows for the same resource — if AWS itself shows the same value, the "staleness" is coming from AWS's own metric-emission timing (CloudWatch metrics often lag actual events by 1–5 minutes).
  </Accordion>

  <Accordion title="EKS queries fail after connecting" icon="server">
    Two likely causes: (1) the IAM Role doesn't have `AmazonEKSClusterPolicy` attached — attach it and retry; (2) the EKS cluster API endpoint is IP-restricted and Rootly AI's outbound IPs aren't allowed — add them to the endpoint's allow-list (they're shown on the Rootly modal's EKS section).
  </Accordion>

  <Accordion title="Rootly AI can query some AWS services but not others" icon="filter">
    Selected-services scope mismatch. Open the AWS integration's Configure screen in Rootly to see which services are currently selected. If a service you expect Rootly AI to use isn't listed, add it — but remember to also update the AWS-side IAM policy to grant read permissions for that service (Rootly shows the updated policy JSON when you change the selection).
  </Accordion>

  <Accordion title="After rotating my Role ARN, the integration shows Connected but queries fail" icon="plug-circle-xmark">
    Open **Configure** on the AWS card, paste the new Role ARN, click Test Connection, and save. The Connected status alone doesn't verify current-credential health — a rotation without reconnecting leaves stale credentials in place.
  </Accordion>
</AccordionGroup>

***

## Frequently Asked Questions

<AccordionGroup>
  <Accordion title="Is Rootly AI's AWS access read-only?" icon="lock">
    Yes. The IAM policies Rootly generates grant only `Describe*`, `Get*`, `List*`, and equivalent read-only actions. Rootly AI cannot start or stop instances, modify security groups, or change any configuration.
  </Accordion>

  <Accordion title="What is the External ID for?" icon="key">
    The External ID is a per-organization identifier that keeps your Rootly connection separate from every other Rootly customer's. Your role's trust policy checks that the External ID matches your organization's specifically, so nobody else can use the same connection pattern to reach your role.
  </Accordion>

  <Accordion title="Can I connect multiple AWS accounts?" icon="server">
    Currently one AWS integration per Rootly team. If you operate multiple AWS accounts, connect the one that hosts the majority of your observability signals — typically a hub or central account. Multi-account support is on the roadmap.
  </Accordion>

  <Accordion title="What AWS services does Rootly AI use most often?" icon="chart-line">
    In investigation flows we see the most calls to **CloudWatch** (metrics and log queries), **EC2** and **RDS** (instance and database state), and **ELB / ALB** (load balancer health). Add these first if you're scoping narrowly. **CloudTrail** is also useful for "what changed in AWS recently" investigations.
  </Accordion>

  <Accordion title="Does Rootly AI's AWS access show up in CloudTrail?" icon="file-lines">
    Yes. Every API call Rootly AI makes appears in your CloudTrail logs. You can audit exactly what Rootly AI queried and when. Use the role name (e.g., `RootlyAIReadOnly`) as the CloudTrail filter to see the full history.
  </Accordion>

  <Accordion title="Does the integration count against AWS API rate limits?" icon="gauge-high">
    Rootly AI's AWS calls count against your account's standard AWS API rate limits. In practice, investigation volume is low — a handful of calls per investigation — so rate limits are not a concern for typical use.
  </Accordion>

  <Accordion title="How do I fully disconnect AWS from Rootly?" icon="trash">
    (1) Click Disconnect on the AWS card in Rootly — this removes the stored Role ARN and External ID. (2) In AWS, delete the IAM Role and any CloudFormation stack that created it.
  </Accordion>
</AccordionGroup>

***

## Related Pages

<CardGroup cols={3}>
  <Card title="Connectors Overview" icon="sparkles" href="/ai/connectors/overview">
    The full list of Connectors and how they fit together.
  </Card>

  <Card title="Data Privacy for Rootly AI" icon="shield" href="/ai/data-privacy-for-rootly-ai">
    What Rootly AI sees, retention, and model-training controls.
  </Card>

  <Card title="AWS documentation on External IDs" icon="up-right-from-square" href="https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-user_externalid.html">
    AWS's own reference on how External IDs work in IAM trust policies.
  </Card>
</CardGroup>