Skip to main content

​
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.
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.

​
Setup Provisioning Options

You have three ways to create the IAM Role in AWS. Pick whichever matches how your team manages AWS infrastructure. 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.
1

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.
2

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.
3

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.
4

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.

​
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.
1

Open IAM > Roles In The AWS Console

Log in to the AWS Console for the account you want to connect. Navigate to IAM → Roles.
2

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.
3

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.
4

Name The Role And Create It

Click Next, name the role something recognizable (e.g., RootlyAIReadOnly), and click Create role.
5

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.

​
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.
​
AWS Services The Agent Can Read
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.
​
Restrict To Regions
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).
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.

​
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.
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.

​
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:
1

Open The AWS Card In Rootly

Configuration → AI → Connectors → click Configure on the AWS card.
2

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.
3

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.
4

Save In Rootly

Save the updated configuration in Rootly. New Rootly AI queries respect the new scope on the next investigation.

​
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

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.
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.
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).
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).
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).
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.

​
Frequently Asked Questions

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.
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.
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.
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.
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.
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.
(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.

Connectors Overview

The full list of Connectors and how they fit together.

Data Privacy for Rootly AI

What Rootly AI sees, retention, and model-training controls.

AWS documentation on External IDs

AWS’s own reference on how External IDs work in IAM trust policies.