AWS Integration | Atatus Docs

Atatus connects to your AWS account with a cross-account IAM role. Once connected, Atatus collects CloudWatch metrics, resource metadata, and — if you turn it on — CloudWatch Logs.

There are two ways to set it up:

Setup	Use it when
CloudFormation (recommended)	You want metrics and logs configured in one launch. Atatus builds the stack URL with your External ID already filled in.
Manual	Your organization does not allow vendor CloudFormation stacks, or you want to create the IAM role yourself and review every permission first.

Both produce the same result: an IAM role in your account that Atatus can assume. The CloudFormation path additionally installs the log forwarder.

How the connection works

Atatus never stores AWS access keys. You create an IAM role in your account that trusts the Atatus AWS account, and Atatus assumes that role with an External ID that is unique to your Atatus organization.

Atatus (AWS account 317265140635)
        │  sts:AssumeRole  +  ExternalId
        ▼
AtatusIntegrationRole  (your account)
        │
        ├── CloudWatch metrics          read
        ├── Resource metadata           read
        └── Subscription filters        managed by Atatus, named atatus-log-forwarder

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.

Log content never travels through the role. The role reads log metadata only (logs:Describe*). Log events reach Atatus by push, from a forwarder Lambda that runs in your own account. Nothing in the role can read a log event.

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.
For the CloudFormation path, permission to create CloudFormation stacks and Lambda functions.

Set up the integration

Pick a path. The tabs below hold the full steps for each one.

Step 1: Start in Atatus

In Atatus, go to Integrations and select AWS.
Click Add AWS Account.
Choose what to collect:
- Metrics — CloudWatch metrics and the resource metadata that labels them.
- Logs — installs the log forwarder and subscribes the log groups you select.
- You must select at least one. A stack that collects neither is rejected in the console before it deploys.
If you selected logs, pick the log services to collect (for example Lambda, RDS, API Gateway). Atatus turns that selection into log group prefixes such as /aws/lambda/*.
Click Launch CloudFormation stack.

Atatus opens the AWS CloudFormation console in a new tab with the template and your parameters already filled in.

Note:

Launch the stack from the Atatus UI. The template needs a WorkflowId and an AtatusExternalId that only Atatus can generate, and it reports its progress back to Atatus as it deploys. Launching it by hand from S3 will not produce a working integration.

Step 2: Check the parameters

Most parameters are already filled in. These are the ones worth reviewing:

Parameter	Default	What it does
`AtatusApiKey`	—	Authenticates the status reports and the log pushes. Filled in by Atatus.
`AtatusSite`	`atatus.com`	Where data is sent. Leave as is unless Atatus support tells you otherwise.
`InstallMetricCollection`	`true`	Creates the IAM role Atatus assumes to read CloudWatch.
`InstallLogForwarder`	`true`	Installs the CloudWatch Logs forwarder Lambda.
`IAMRoleName`	`AtatusIntegrationRole`	Rename it if your account has a naming standard.
`EnabledLogServices`	(blank)	The log services you chose in Atatus.
`LogGroupPrefixes`	(blank)	The resolved log group patterns, for example `/aws/lambda/,/aws/rds/`.

WorkflowId and AtatusExternalId are generated by Atatus. Do not edit them.

The Advanced section holds TemplateBaseUrl and the site override fields. Leave them alone unless you are on an Atatus-operated staging environment.

Step 3: Create the stack

Tick I acknowledge that AWS CloudFormation might create IAM resources with custom names.
Click Create stack.

The stack is named Atatus-AWS-Integration by default and usually completes in two to five minutes. It creates nested stacks for the IAM role, the permissions refresh, and the log forwarder.

While it deploys, the Atatus setup screen shows live progress. Each stage reports itself as it finishes.

Step 4: Finish in Atatus

When the stack reaches CREATE_COMPLETE, return to the Atatus tab. Atatus proves the role by assuming it, then creates the integration. Metrics begin arriving within about ten minutes.

What the stack creates

Resource	Name	Purpose
IAM role	`AtatusIntegrationRole`	The role Atatus assumes. Trusts account `317265140635` with your External ID.
Inline policy	`AtatusIntegrationPolicy`	Read access to CloudWatch and resource metadata, plus subscription filter management scoped to the filter name `atatus-log-forwarder`.
Lambda	`atatus-log-forwarder-<region>`	Pushes log events to Atatus. One per region where log collection is enabled.
Subscription filters	`atatus-log-forwarder`	Route matching log groups to the forwarder. Managed by Atatus from its own side, not frozen at stack-creation time.

Changing which log services you collect is done in the Atatus UI, not by updating the stack.

Note:

Use this when you cannot run the CloudFormation stack. It gives you metric collection. To collect logs as well, deploy atatus_log_forwarder.yaml afterwards, or keep using the CloudFormation path for that part.

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.

In Atatus, go to Integrations and select AWS.
Click Add AWS Account.
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.

Sign in to the AWS IAM Console and go to Roles.
Click Create role.
For Trusted entity type, select AWS account.
Select Another AWS account.
In Account ID, enter the Atatus AWS account ID:
```
317265140635
```
Select Require external ID, and paste the External ID you copied in Step 1.
Leave Require MFA turned off. Atatus cannot complete an MFA prompt, so the connection fails if you enable it.
Click Next, then click Next again to skip the permissions screen. You add permissions in Step 3.
Give the role a name, for example AtatusIntegrationRole. Write it down, because you need the exact name in Step 5.
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.

Open the role you created on the Roles page.
Click Add permissions, then select Create inline policy.
Select the JSON tab.
Replace the contents of the box with the following policy:

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": "*"
    }
  ]
}

Click Next.
Name the policy, for example AtatusIntegrationPolicy.
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:

Open the role on the Roles page.
Click Add permissions, then select Attach policies.
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.

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.
Enter the AWS Role Name you chose in Step 2, for example AtatusIntegrationRole.
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

In Atatus: Integrations → AWS shows the account as connected, with a last-seen timestamp.
Metrics: open any AWS dashboard in Atatus. Data appears within roughly ten minutes.
Logs: go to Logs and filter by source:aws. The first events arrive within a few minutes of the forwarder being installed.
In AWS: the stack Atatus-AWS-Integration is CREATE_COMPLETE, and CloudWatch shows invocations on atatus-log-forwarder-<region>.

Troubleshooting

Atatus is not authorized to perform sts:AssumeRole

The trust policy does not match what Atatus is presenting. Check, in order:

The account ID in the trust policy is 317265140635.
The External ID matches exactly the one on the Atatus screen — no leading or trailing space.
Require MFA is not enabled on the role.
The role name in the ARN you pasted matches the role you actually created.

Some services are missing data

Usually the permission list is older than the service. Re-apply the permissions policy from the current template. On the CloudFormation path, update the stack; it refreshes the list at deploy time.

Also confirm the region is one Atatus is configured to poll — resource collection is per region.

A permissions boundary is blocking access

If your account applies a permissions boundary to every role, the boundary must allow the actions in AtatusIntegrationPolicy. The role is created but every call fails. Ask your AWS administrator to add the boundary exception, or create the role in an account without one.

A Service Control Policy is blocking access

An SCP at the organization or OU level denies the action before the role policy is ever evaluated. The symptom is an explicit deny that does not correspond to anything in the role. Your AWS organization administrator has to allow it at the SCP level.

The stack fails on the log forwarder

The IAM role is created before the forwarder, so metrics still work. Check the nested stack's events for the reason — most often a Lambda concurrency limit or a region where Lambda is not enabled. Re-run the stack update after fixing it.

Pause the integration

To stop collection without removing anything, set the integration to Disabled in Atatus. The subscription filters are removed so no data flows and nothing is billed, but the configuration is kept. Re-enabling restores the previous metric and log settings without re-onboarding.

Remove the integration

Removing the Atatus AWS integration involves three separate operations. Each operation performs a different level of cleanup, so you can choose the one that matches what you want to remove.

Operation	What it does	How to perform
Delete Integration	Stops the AWS account from sending data to Atatus. The integration will no longer appear as an active integration in the Atatus dashboard.	Atatus Dashboard
Uninstall	Removes the Atatus Lambda forwarder functions from your AWS account.	Run `atatus_aws_uninstall.sh`
Remove Access	Completely removes the AWS resources created for the Atatus integration, including the CloudFormation stack and associated IAM resources.	Run `atatus_aws_uninstall.sh --remove-identity`

1. Delete the integration

In Atatus, go to Integrations → AWS and delete the account.

This removes the routing: Atatus deletes the atatus-log-forwarder subscription filters from your log groups. Data stops flowing immediately, and the forwarder Lambda stops being invoked, so it stops billing.

What is left standing on purpose: the forwarder Lambdas and the CloudFormation stack. Atatus names them in the deletion summary rather than removing them, so a customer who deletes in order to pause still has something to re-enable onto.

Note:

Deleting the integration does not delete any of your CloudWatch log data. Atatus removes only the subscription filters it created.

2. Uninstall the forwarders

Download and run the uninstall script:

curl -O https://atatus-artifacts.s3.us-east-1.amazonaws.com/atatus-cloud-templates/aws/atatus_aws_uninstall.sh
chmod +x atatus_aws_uninstall.sh
./atatus_aws_uninstall.sh

It finds every atatus-log-forwarder-<region> Lambda in your account, verifies the routing is already gone, and deletes them.

Flag	Effect
`--status`	Report what it finds and delete nothing.
`--verify-routing`	Exhaustive scan of every log group for remaining `atatus-log-forwarder` filters, instead of the fast invocation check. Slower and thorough.
`--remove-identity`	Also delete the `Atatus-AWS-Integration` CloudFormation stack, which removes the IAM role.
`--force`	Delete the Lambdas without confirming the routing is gone. See the warning below.
`--profile <name>`	Use a named AWS CLI profile.
`--regions us-east-1,eu-west-1`	Restrict to specific regions instead of scanning all of them.
`--stack-name <name>`	If you renamed the stack at launch.

Note:

Do step 1 before step 2. The subscription filters point at the forwarder Lambda. Delete the Lambda while a filter still points at it and CloudWatch Logs does not fail quietly — it keeps attempting delivery, and on some log groups a broken destination throttles delivery for everything else on that group. Your own logging degrades, in a way that looks nothing like "I uninstalled Atatus". The script refuses to run if it can still see the forwarders being invoked; --force overrides that check and is only for an account whose filters were already cleaned up by other means.

The script never touches your log groups, your log data, or any resource not named atatus-log-forwarder-*.

3. Remove access

./atatus_aws_uninstall.sh --remove-identity

This deletes the Atatus-AWS-Integration stack, which removes AtatusIntegrationRole and its policy. After this, Atatus can no longer read anything in the account.

It is opt-in and never implicit: uninstalling the forwarders stops Atatus collecting, but until the role is gone a cross-account role that Atatus can assume still exists.

If you created the role manually, delete it yourself in IAM → Roles.