AWS Accounts

CostLens reads your AWS cost data and resource configurations using a cross-account IAM role. The setup takes about 5 minutes and requires no code changes or agents in your AWS environment.

How it works#

What is the External ID?#

When you click Add Account, a unique External ID (a UUID like 550e8400-e29b-41d4-a716-446655440000) is generated and displayed in the form. You must paste this value into your AWS IAM role trust policy. It acts as a shared secret — without it, no one can assume your role, even if they know your Role ARN. Keep it private and treat it like a password. It is always visible on your account card if you need to copy it again.

Step-by-step: IAM Role setup (recommended)#

Step 1 — Open CostLens → Accounts → Add Account#

Click Add Account in the top-right corner of the Accounts page. Select IAM Role (recommended). Your unique External ID is shown in the form — copy it now, you will paste it into AWS Console in step 3.

Step 2 — Go to AWS Console → IAM → Roles → Create role#

Log in to console.aws.amazon.com. Search for IAM in the top bar, open Roles in the left nav, and click Create role.

Step 3 — Configure the trusted entity#

On the "Select trusted entity" screen:

Leave MFA unchecked. Click Next.

Step 4 — Attach ReadOnlyAccess + Apply Fix policy#

Step 4a — Scan only

Search for ReadOnlyAccess and select the AWS-managed policy. This lets CostLens scan for waste and surface recommendations.

# Covered by ReadOnlyAccess (scanning)
ce:GetCostAndUsage, ce:GetCostForecast
ec2:DescribeInstances, DescribeVolumes, DescribeAddresses
rds:DescribeDBInstances
cloudwatch:GetMetricStatistics

Step 4b — Apply Fix permissions (recommended)

After attaching ReadOnlyAccess, click Next → Create role. Then open the role → Add permissions → Create inline policy → JSON and paste:

{
  "Version": "2012-10-17",
  "Statement": [{
    "Sid": "CostlensApplyFix",
    "Effect": "Allow",
    "Action": [
      "ec2:DeleteVolume",
      "ec2:DeleteSnapshot",
      "ec2:TerminateInstances",
      "ec2:ModifyVolume",
      "ec2:ModifyInstanceAttribute",
      "ec2:StopInstances",
      "ec2:StartInstances",
      "ec2:ReleaseAddress",
      "ec2:CreateTags",
      "ssm:SendCommand",
      "ssm:GetCommandInvocation",
      "rds:DeleteDBInstance",
      "rds:StopDBInstance",
      "rds:StartDBInstance",
      "rds:AddTagsToResource",
      "scheduler:CreateSchedule",
      "scheduler:CreateScheduleGroup",
      "scheduler:GetScheduleGroup",
      "iam:GetRole",
      "iam:CreateRole",
      "iam:PutRolePolicy",
      "iam:PassRole",
      "logs:PutRetentionPolicy",
      "logs:DescribeLogGroups"
    ],
    "Resource": "*"
  }]
}

Name the inline policy CostlensApplyFix and save.

What each permission enables:

• ec2:DeleteVolume / DeleteSnapshot — remove unused EBS volumes & snapshots
• ec2:TerminateInstances — terminate long-stopped EC2 instances
• ec2:StopInstances / StartInstances / ModifyInstanceAttribute — schedule & rightsize EC2 instances
• ec2:ModifyVolume + ssm:* — expand full EBS volumes live (no downtime)
• ec2:ReleaseAddress — release unattached Elastic IPs
• rds:DeleteDBInstance — delete idle RDS databases
• rds:StopDBInstance / StartDBInstance — schedule RDS stop-start
• scheduler:* + iam:* — create EventBridge schedules for automated stop-start
• logs:PutRetentionPolicy / DescribeLogGroups — set 30-day retention on CloudWatch Log Groups

Step 5 — Name the role and create it#

On the "Name, review, and create" screen, set the role name to AezonaCostlens. Scroll down and verify the Trusted entities section shows the CostLens Account ID and your External ID condition. Click Create role.

Step 6 — Copy the Role ARN back into CostLens#

In AWS Console, open the newly created role. Copy the ARN shown at the top:

arn:aws:iam::123456789012:role/AezonaCostlens

Go back to the CostLens connect dialog, paste it into the Role ARN field, optionally enter an account name, then click Test Connection. Once the test passes, click Connect Account to save.

First sync phases#

After saving, a first-sync progress panel appears. It runs three phases in sequence:

The panel auto-dismisses after completion. The account card then shows In sync and a last-synced timestamp.

Option B — Access Keys (not recommended)#

Adding Apply Fix permissions later#

If you skipped Step 4b, you can add the CostlensApplyFix inline policy at any time by opening your AezonaCostlens IAM role in AWS → Add permissions → Create inline policy → JSON and pasting the JSON from Step 4b.

Managing connected accounts#

Sync status reference#

Common errors and fixes#