Skip to main content

AWS Setup Guide

Connect your AWS account to CloudWise, read-only, in about five minutes.

Don't want to connect a live AWS account?

If your organization has strict security policies, or you just want to evaluate CloudWise first, use Air-Gapped Mode — analyze an offline cost export with no IAM role and no cross-account access.

Learn about Air-Gapped Mode →

🔐 Security first​

CloudWise follows AWS security best practices:

  • Read-only access for monitoring — no write permissions, nothing in your account is changed or deleted
  • Least privilege — only the permissions detection needs
  • Cross-account role, not access keys
  • Single-use External ID — minted per connection and baked into the CloudFormation stack for you; you never have to copy or store it

Every permission the role gets is listed publicly, and you can review the whole list before you grant anything: see every permission.

Remediation uses a separate role

The monitoring role described here is read-only. Executing fixes is a separate, opt-in capability on the Agentic plan that uses a distinct, narrowly-scoped write role. See the AI Remediation Guide. Free, Shield, and Compliance never execute changes — the agent proposes the fix and you run it.

📋 Prerequisites​

  • Permission to create an IAM role and a CloudFormation stack in the AWS account you want to connect
  • The AWS account open in your browser (you'll create the stack in your own console)

🚀 One-click setup (recommended)​

This is the fastest path and the one most people should use. There is no template to download and no Role ARN to copy back by hand.

Step 1 — Open AWS with the stack pre-filled​

In CloudWise, start the Connect flow (new sign-ups land here; existing users go to Settings → AWS Accounts) and click "Open AWS — one-click setup".

CloudWise mints a single-use External ID for your session and opens a CloudFormation quick-create deep link in your own AWS console, with every parameter already filled in — the read-only role name, the unique External ID, and a callback so the stack can report itself back when it finishes.

Step 2 — Review it and click Create stack​

The quick-create screen shows exactly what will be created: one read-only role (CloudWise-Cost-Monitoring-Role-…) whose only trust is CloudWise + your single-use External ID. AWS asks you to tick an IAM acknowledgement — that's CloudFormation confirming the template creates the IAM role it just showed you. Tick it and click Create stack. The stack finishes in about two minutes.

Step 3 — CloudWise verifies and scans​

When the stack finishes, CloudFormation reports the new role back to CloudWise automatically, and CloudWise validates the access live — the same check a hand-pasted ARN would go through. There is nothing to paste and nothing to come back for.

The first scan then starts on its own, the moment the role is assumable. You'll see a waste total and a ranked list of findings within minutes. Full cost history (from your Cost and Usage Report) fills in over the next few hours — see When your data appears.

Popup blocked, or your team deploys templates by hand?

Use the manual setup below. Everything downstream (verification, scanning) is identical.

🛠️ Manual setup (fallback)​

Use this if a popup blocker stops the quick-create tab from opening, or if your team reviews and deploys CloudFormation templates by hand.

Step 1 — Launch the read-only stack​

In the Connect flow, switch to "Set it up manually instead." CloudWise downloads the template to your computer and opens the CloudFormation console. In the console, choose Upload a template file (not the pre-selected "Amazon S3 URL") and pick the file you just downloaded.

Step 2 — Create the stack and paste the outputs​

Create the stack (~2 minutes). Open its Outputs tab and copy the values back into the Connect form:

  • Role ARN — arn:aws:iam::YOUR-ACCOUNT:role/CloudWise-Cost-Monitoring-Role-…
  • Cost-report S3 bucket and cost-report name
  • Your 12-digit AWS account ID is the number in the middle of the Role ARN

Then click Connect & start the first scan. Verification and scanning proceed exactly as in the one-click flow.

Reference: the CloudFormation template​

The stack CloudWise generates is the equivalent of the role below. Review or adapt it if you build the role yourself:

AWSTemplateFormatVersion: '2010-09-09'
Description: 'CloudWise read-only cost-monitoring role'

Parameters:
  ExternalId:
    Type: String
    Description: Single-use External ID provided by CloudWise
    NoEcho: true

Resources:
  CloudWiseCostMonitoringRole:
    Type: AWS::IAM::Role
    Properties:
      # CloudWise generates a unique per-connection role name
      # (CloudWise-Cost-Monitoring-Role-<id>); a fixed name works too.
      AssumeRolePolicyDocument:
        Version: '2012-10-17'
        Statement:
          - Effect: Allow
            Principal:
              AWS: arn:aws:iam::123456789012:root   # CloudWise's account
            Action: sts:AssumeRole
            Condition:
              StringEquals:
                sts:ExternalId: !Ref ExternalId
      ManagedPolicyArns:
        - arn:aws:iam::aws:policy/ReadOnlyAccess
        - arn:aws:iam::aws:policy/job-function/Billing
      Policies:
        - PolicyName: CloudWiseCostExplorerAccess
          PolicyDocument:
            Version: '2012-10-17'
            Statement:
              - Effect: Allow
                Action:
                  - ce:GetCostAndUsage
                  - cur:GetUsageReport
                  - ce:ListCostCategoryDefinitions
                  - ce:GetRightsizingRecommendation
                  - ce:GetSavingsPlansUtilization
                  - ce:GetReservationPurchaseRecommendation
                  - ce:GetReservationUtilization
                  - budgets:ViewBudget
                  - budgets:DescribeBudgets
                Resource: "*"

Outputs:
  RoleArn:
    Description: ARN of the CloudWise cost-monitoring role
    Value: !GetAtt CloudWiseCostMonitoringRole.Arn

⏱️ When your data appears​

CloudWise reads two different kinds of data on two different clocks:

  • Waste findings — within minutes. Idle NAT gateways, unattached volumes, oversized instances, and the like come from live describe calls and CloudWatch metrics, so they appear on the workspace shortly after the role is assumable.
  • Cost history — within a few hours. Spend by service, trends, and month-over-month comparisons come from your AWS Cost and Usage Report. For an account that already has a CUR, this is usually a few hours. For a brand-new CUR configuration, AWS itself can take up to 24 hours to deliver the first report — that delay is on the AWS side, not CloudWise.

🔍 Troubleshooting​

The CloudFormation stack failed to create​

  • "Bucket already exists" — you're reconnecting an account CloudWise has seen before, and its cost-report bucket is still there. Delete the old stack (and the cloudwise-cur-<account>-<region> bucket if it lingers) and re-launch the connect flow.
  • Popup never opened — a browser popup blocker stopped the quick-create tab. Use the manual setup above.

"Role cannot be assumed" after the stack succeeds​

  • The stack created the role but verification hasn't picked it up yet — give it a few seconds; CloudWise polls automatically.
  • If it persists, confirm the stack created the role in us-east-1 and that no Service Control Policy blocks sts:AssumeRole.

"No cost data available"​

  • Waste findings appear first; cost data follows once your CUR is delivered (see When your data appears).
  • For a brand-new CUR, allow up to 24 hours.
  • Confirm the cost-report bucket and report name were captured (one-click does this for you; manual setup requires pasting them).

🏢 Multi-account setup​

Connect each account with its own one-click flow — repeat the steps above per account. For AWS Organizations, run the connect flow from each account you want visibility into; consolidated views group them in CloudWise. Ensure any Service Control Policies allow the read-only actions the role requests.

🛡️ Security best practices​

  • Least privilege — the role grants read-only monitoring and nothing more. Review it against the public permission list.
  • The External ID is single-use — CloudWise mints and manages it per connection; you don't need to store or rotate it.
  • Audit — CloudTrail records every assume-role, so you can see exactly when and how CloudWise reads your account.
  • Revoke anytime — delete the CloudFormation stack in your console and the access is gone.

🆘 Need help?​

⚡ Fast: most people connect in about five minutes • 🔒 Read-only: nothing in your account is changed • 📈 Real numbers: a waste total within minutes