AWS Accounts

CostLens reads your AWS cost data and resource configuration using a cross-account IAM role. The guided Add Account wizard is the fastest way to connect — it opens a pre-filled CloudFormation stack, creates the role for you, and detects the connection automatically. No IAM console work and no values to copy back into CostLens.

How it works#

Connect a new AWS account#

Step 1 — Add Account → AWS → choose access level#

From the Accounts page, click Add Account, choose AWS, then choose Read-Only or Read/Write. The next screen shows exactly what CostLens is about to be granted:

The trust model is a cross-account IAM role assumed via sts:AssumeRole with a unique External ID (confused-deputy protection) — CostLens never creates or stores AWS access keys for this flow.

Step 2 — Authorize#

Click Authorize. This opens AWS CloudFormation Quick-Create in a new browser tab, signed into whichever AWS account your browser is currently authenticated as, with everything pre-filled:

• The CostLens-hosted template
• A stack name unique to your CostLens organization (costlens-<id>)
• Your External ID (also shown in CostLens if you need to copy it)
• The access level you chose

Step 3 — Create stack#

In the AWS tab, review the stack (nothing to edit — the parameters are already filled in) and click Create stack. CloudFormation provisions an IAM role named CostLensAccessRole, trusting CostLens's account with your External ID, and attaches exactly the permissions your chosen access level requires.

Step 4 — CostLens connects automatically#

Once the stack reaches CREATE_COMPLETE, its notifier reports the account ID straight back to CostLens — the wizard's "Finishing automatically…" screen updates on its own within a few seconds, no action needed. First sync (billing → optimization checks → AI explanations) starts immediately.

Reconnecting, or connecting a second AWS account#

CostLens can't see into an AWS account before you grant it access, so it can't always know in advance whether "Authorize" should create a new role or reuse one that already exists. It handles this in two ways:

Automatic reuse. If your organization previously connected an AWS account to CostLens and later removed it, clicking Add Account → AWS shows "Found and verified your existing connection" immediately — CostLens already checked that account's role still works and skips CloudFormation entirely. Click Continue to finish.

Explicit choice. If your organization has connected AWS before but CostLens can't automatically verify a reusable role (e.g. you're adding a genuinely different, second AWS account), the Review screen replaces the single Authorize button with two options:

If you go ahead and connect an account that turns out to already be active in your CostLens organization, you'll see "This account already exists — it's already connected. Nothing was added again" on the success screen, rather than a misleading "new account connected" message.

Connect an entire AWS Organization (multi-account)#

If you manage many AWS accounts under an AWS Organization, click Connect an organization from the Accounts page instead of adding accounts one at a time:

1. Pick a seed account — an already-connected account whose role has organization-level reach (typically the management account).
2. First time only: expand "Grant organization-wide access" for a generated script that extends the seed account's role to every member account (via CloudFormation StackSets).
3. Click Discover & connect — CostLens enumerates every member account under the seed and connects each one, showing a live per-account result (Connected / Failed / Skipped). Accounts already connected are updated, not duplicated; a failed account gets an "Enter details manually" link so one bad account never blocks the rest.

Alternative: create the IAM role by hand#

If you'd rather not use CloudFormation (e.g. your organization requires manual IAM review before any role is created), you can create the role yourself and paste its details into CostLens instead — same trust model, same permissions, same role name.

Step 1 — AWS Console → IAM → Roles → Create role#

Log in to console.aws.amazon.com. Search for IAM, open Roles, and click Create role.

Step 2 — Configure the trusted entity#

Leave MFA unchecked. Click Next.

Step 3 — Attach permissions#

Read-only scan — search for ReadOnlyAccess and attach the AWS-managed policy:

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

Apply Fix permissions (only if you chose Read/Write) — after creating the role, open it → Add permissions → Create inline policy → JSON, name it CostlensApplyFix, 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": "*"
  }]
}

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 4 — Name the role and create it#

Name the role CostLensAccessRole (the same name CloudFormation would have used — CostLens assumes this name by default, so using it means you don't have to paste the ARN back). Verify the Trusted entities section shows CostLens's account ID and your External ID condition, then click Create role.

Step 5 — Paste into CostLens#

Back in the CostLens wizard's manual-entry step, enter your 12-digit AWS account ID. Leave IAM role ARN blank (CostLens assumes CostLensAccessRole in that account) — or paste the full ARN if you used a different role name. Click Connect account.

Additional billing source: Cost & Usage Reports (optional)#

Once an AWS account is connected via IAM Role, its account card shows a Billing Data Source panel where you can optionally layer on Cost & Usage Reports (CUR) — a more granular, resource-level billing export than Cost Explorer provides. This reuses the same CostLensAccessRole you already created (just add s3:GetObject/s3:ListBucket on the CUR bucket to its policy) — no separate role. See the dedicated Cost & Usage Reports guide for the full setup.

Kubernetes (EKS) cost & optimization#

The ReadOnlyAccess policy attached above already covers everything CostLens needs for EKS — eks:List*/Describe*, Auto Scaling, EC2 and CloudWatch reads for the node-pool checks, plus Cost Explorer for Kubernetes cost. No extra IAM is required. Two capabilities depend on an AWS billing setting (not a permission):

Adding Apply Fix permissions later#

Connected with Read-Only and want Auto-Fix later? Open your CostLensAccessRole IAM role in AWS → Add permissions → Create inline policy → JSON and paste the CostlensApplyFix JSON from the manual-setup section above.

First sync phases#

After connecting, 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.

Managing connected accounts#

Sync status reference#

Common errors and fixes#