The AWS integration connects your AWS account to Atatus, so you can monitor your AWS services without installing an agent on every host. Atatus calls the AWS APIs on your behalf and pulls the data into your dashboard.

Use this integration to:

  • Collect CloudWatch metrics from your AWS services, such as EC2, RDS, Lambda, and ELB. <!-- - Collect resource details, such as how your instances, buckets, and databases are configured. -->

This page covers the manual setup using an IAM role. You create a role in your AWS account, allow Atatus to assume it, and then tell Atatus the role name.

How the connection works

Atatus uses role delegation to read your AWS data. Instead of storing a long lived access key, you create an IAM role in your own account and let the Atatus AWS account assume it.

The connection relies on three pieces:

Piece What it does
Atatus AWS account ID The AWS account Atatus calls from. You add it as a trusted account on your role. It is always 317265140635.
External ID A unique value Atatus generates for you. AWS checks it on every request, so no one else can assume your role even if they learn the role name.
IAM role The role in your account that holds the permissions Atatus is allowed to use.

You keep control the whole time. You can change the permissions or delete the role at any point, and Atatus loses access right away.

Note:

Role delegation is more secure than access keys because there is no secret to store, leak, or rotate. AWS issues short lived credentials each time Atatus assumes the role.

Before you start

Make sure you have:

  • An AWS account, and permission to create IAM roles and policies in it. The IAMFullAccess policy, or an equivalent, is enough.
  • Access to the Atatus dashboard.

Step 1: Get your External ID from Atatus

Start in Atatus, because you need the External ID before you can create the role in AWS.

  1. In Atatus, go to Integrations and select AWS.
  2. Click Add AWS Account.
  3. Copy the External ID shown on the screen.

Keep this browser tab open. You come back to it in Step 5.

Note:

The External ID is tied to your Atatus account. Treat it like a password and do not share it publicly.

Step 2: Create the IAM role in AWS

Now create the role that Atatus assumes.

  1. Sign in to the AWS IAM Console and go to Roles.
  2. Click Create role.
  3. For Trusted entity type, select AWS account.
  4. Select Another AWS account.

  5. In Account ID, enter the Atatus AWS account ID:

    317265140635

  6. Select Require external ID, and paste the External ID you copied in Step 1.

  7. Leave Require MFA turned off. Atatus cannot complete an MFA prompt, so the connection fails if you enable it.

  8. Click Next, then click Next again to skip the permissions screen. You add permissions in Step 3.

  9. Give the role a name, for example AtatusIntegrationRole. Write it down, because you need the exact name in Step 5.

  10. Click Create role.

AWS builds the trust policy for you from the account ID and External ID you entered. You do not need to write it by hand.

Warning:

Do not skip the Require external ID step. Without it, any AWS account that knows your role name could try to assume the role.

Step 3: Add the permissions policy

The role has no permissions yet. Attach a policy that lets Atatus read your metrics and resource details.

  1. Open the role you created on the Roles page.
  2. Click Add permissions, then select Create inline policy.
  3. Select the JSON tab.
  4. Replace the contents of the box with the following policy:
copy
icon/buttons/copy 
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "AtatusIntegrationReadOnly",
      "Effect": "Allow",
      "Action": [
        "account:GetAccountInformation",
        "airflow:GetEnvironment",
        "airflow:ListEnvironments",
        "apigateway:GET",
        "appsync:ListGraphqlApis",
        "autoscaling:Describe*",
        "backup:List*",
        "batch:DescribeJobDefinitions",
        "batch:DescribeJobQueues",
        "batch:DescribeJobs",
        "batch:ListJobs",
        "bcm-data-exports:GetExport",
        "bcm-data-exports:ListExports",
        "budgets:ViewBudget",
        "cloudfront:GetDistributionConfig",
        "cloudfront:ListDistributions",
        "cloudtrail:DescribeTrails",
        "cloudtrail:GetTrail",
        "cloudtrail:GetTrailStatus",
        "cloudtrail:ListTrails",
        "cloudtrail:LookupEvents",
        "cloudwatch:Describe*",
        "cloudwatch:Get*",
        "cloudwatch:List*",
        "codebuild:BatchGetProjects",
        "codebuild:ListProjects",
        "codedeploy:BatchGet*",
        "codedeploy:List*",
        "cost-optimization-hub:GetRecommendation",
        "cost-optimization-hub:ListRecommendations",
        "cur:DescribeReportDefinitions",
        "directconnect:Describe*",
        "dms:DescribeReplicationInstances",
        "dynamodb:Describe*",
        "dynamodb:List*",
        "ec2:Describe*",
        "ecs:Describe*",
        "ecs:List*",
        "eks:DescribeCluster",
        "eks:ListClusters",
        "elasticache:Describe*",
        "elasticache:List*",
        "elasticbeanstalk:DescribeEnvironments",
        "elasticfilesystem:DescribeAccessPoints",
        "elasticfilesystem:DescribeFileSystems",
        "elasticfilesystem:DescribeTags",
        "elasticloadbalancing:Describe*",
        "elasticmapreduce:Describe*",
        "elasticmapreduce:List*",
        "es:DescribeElasticsearchDomains",
        "es:ListDomainNames",
        "es:ListTags",
        "fsx:DescribeFileSystems",
        "fsx:ListTagsForResource",
        "glue:BatchGetJobs",
        "glue:GetJob",
        "glue:GetJobs",
        "glue:ListJobs",
        "health:DescribeAffectedEntities",
        "health:DescribeEventDetails",
        "health:DescribeEvents",
        "iam:ListAccountAliases",
        "iot:GetV2LoggingOptions",
        "kinesis:Describe*",
        "kinesis:List*",
        "lambda:List*",
        "logs:DescribeDeliveries",
        "logs:DescribeDeliverySources",
        "logs:DescribeLogGroups",
        "logs:DescribeLogStreams",
        "logs:DescribeSubscriptionFilters",
        "logs:FilterLogEvents",
        "logs:GetDeliveryDestination",
        "logs:TestMetricFilter",
        "network-firewall:DescribeLoggingConfiguration",
        "network-firewall:ListFirewalls",
        "oam:ListAttachedLinks",
        "oam:ListSinks",
        "organizations:Describe*",
        "organizations:List*",
        "rds:Describe*",
        "rds:List*",
        "redshift-serverless:ListNamespaces",
        "redshift:DescribeClusters",
        "redshift:DescribeLoggingStatus",
        "route53:List*",
        "route53resolver:ListResolverQueryLogConfigs",
        "s3:GetBucketLocation",
        "s3:GetBucketLogging",
        "s3:GetBucketNotification",
        "s3:GetBucketTagging",
        "s3:GetObject",
        "s3:ListAllMyBuckets",
        "s3:ListBucket",
        "ses:Get*",
        "ses:List*",
        "sns:GetSubscriptionAttributes",
        "sns:List*",
        "sqs:ListQueues",
        "ssm:GetServiceSetting",
        "ssm:ListCommands",
        "states:DescribeStateMachine",
        "states:ListStateMachines",
        "support:DescribeTrustedAdvisor*",
        "tag:GetResources",
        "tag:GetTagKeys",
        "tag:GetTagValues",
        "timestream:DescribeEndpoints",
        "trustedadvisor:ListRecommendationResources",
        "trustedadvisor:ListRecommendations",
        "wafv2:ListLoggingConfigurations",
        "xray:BatchGetTraces",
        "xray:GetTraceSummaries"
      ],
      "Resource": "*"
    }
  ]
}
  1. Click Next.
  2. Name the policy, for example AtatusIntegrationPolicy.
  3. Click Create policy.

The list is long because it covers every AWS service Atatus can monitor. You do not need to trim it to the services you run today. AWS ignores permissions for services you do not use, and keeping the full list means new services start reporting as soon as you use them, with no policy edit.

Every action in this policy is read only. It is made up of Get, List, and Describe calls, so Atatus can look at your metrics and your resource settings but cannot create, change, or delete anything in your account.

Tip:

Your security team may ask why the policy uses "Resource": "*". CloudWatch metrics and the tagging API are account wide, so AWS does not let you scope these read calls to a single resource ARN. You choose which regions Atatus reads from in the Atatus dashboard after you connect the account.

Note:

These permissions can change as Atatus adds support for new AWS services. If metrics for a service are missing, check this page for a newer version of the policy and update your inline policy to match.

Step 4: Turn on resource collection

Resource collection tells Atatus how your AWS resources are set up, not only how they perform. It is what lets you see, for example, which RDS instances are publicly reachable.

To turn it on, attach the AWS managed SecurityAudit policy to the same role:

  1. Open the role on the Roles page.
  2. Click Add permissions, then select Attach policies.
  3. Search for SecurityAudit, select it, and click Add permissions.

SecurityAudit is written and maintained by AWS, and it grants read only access to resource configuration across your services.

Note:

Resource collection is optional. If you only want CloudWatch metrics, skip this step. You can attach SecurityAudit later at any time.

Step 5: Finish the setup in Atatus

Go back to the Atatus tab you left open in Step 1.

  1. Enter your AWS Account ID. This is the 12 digit ID of your account, not the Atatus one. Enter it without dashes, for example 123456789012.

    You can find it in the role ARN, which looks like arn:aws:iam::123456789012:role/AtatusIntegrationRole.

  2. Enter the AWS Role Name you chose in Step 2, for example AtatusIntegrationRole.

  3. Click Save.

Atatus tries to assume the role right away. If it cannot, an error appears on screen so you can fix it before you leave the page.

Warning:

The role name is case sensitive. AtatusIntegrationRole and atatusintegrationrole are not the same, and a mismatch is the most common reason the connection fails.

Verify the setup

Once you save, give it up to 10 minutes for the first data to arrive. Then check that:

  • The AWS account is listed in Integrations > AWS with a Connected status.
  • CloudWatch metrics for your services appear in your Atatus dashboard.

Atatus collects data going forward only. It does not backfill metrics from before you connected the account, so an empty graph for an earlier time range is expected.

Troubleshooting

Atatus is not authorized to perform sts:AssumeRole

This means AWS rejected the connection. Check these in order:

  • The External ID matches. Open the role, go to the Trust relationships tab, and confirm the sts:ExternalId value matches the one shown in Atatus.
  • The trusted account is correct. On the same tab, confirm the Principal is arn:aws:iam::317265140635:root.
  • The role name matches exactly, including capitalization.
  • MFA is off. If the trust policy has an aws:MultiFactorAuthPresent condition, remove it.

Some services are missing data

Your role is probably missing a permission for those services. Compare the inline policy against the one in Step 3 and add anything that is absent.

After you change an IAM policy, AWS needs a few minutes to apply it everywhere. Wait, then check again before digging further.

A permissions boundary is blocking access

A permissions boundary caps what a role can do, even when its own policy allows more. If your organization uses one, the role can be denied actions that the policy appears to grant.

To check whether the role has a boundary, run:

copy
icon/buttons/copy 
$ aws iam get-role --role-name AtatusIntegrationRole \
    --query 'Role.PermissionsBoundary'

If a boundary is attached, ask your IAM or security team to allow the actions this integration needs.

A Service Control Policy is blocking access

If your account belongs to an AWS Organization, a Service Control Policy can block sts:AssumeRole even when your role and trust policy are both correct. Ask your AWS administrator to confirm that no SCP denies the actions listed in Step 3.

Remove the integration

To disconnect the account, delete the IAM role in AWS, then remove the account from Integrations > AWS in Atatus. Once the role is gone, Atatus can no longer reach your account.