Skip to main content

AWS Setup Guide

Complete guide to connecting your AWS account to CloudWise securely and efficiently.

Don't Want to Connect Your AWS Account?

If your organization has strict security policies or you want to evaluate CloudWise first, try Air-Gapped Mode! No IAM roles, no cross-account access needed.

Learn about Air-Gapped Mode →

🔐 Security First​

CloudWise follows AWS security best practices:

  • Read-only access for monitoring (no write permissions)
  • Least privilege principle - minimum required permissions
  • Cross-account roles instead of access keys
  • External ID for additional security layer
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​

Before starting, ensure you have:

  • AWS account administrator access
  • Ability to create IAM roles
  • Basic understanding of AWS IAM concepts

🛠️ Step-by-Step Setup​

Step 1: Start the Connect Flow​

  1. Open the Workspace and start the Connect flow (or, once signed in, Settings → AWS Accounts)
  2. CloudWise walks you through guided CloudFormation: download the template and one-click open the AWS CloudFormation console
  3. Copy the External ID shown (keep this safe)
The guided CloudFormation path is the fastest setup

The Connect flow downloads a ready-made template and opens the CloudFormation console for you—accept the defaults and deploy. The manual IAM steps below are an alternative if you prefer to build the role by hand.

Step 2: Create the IAM Role​

Use the template the Connect flow provides—it creates the read-only CloudWiseCostRole with the correct trust policy and External ID automatically. Skip to Step 4 once the stack finishes.

Option B: Create the role manually in the AWS Console​

  1. Open AWS IAM Console
  2. Go to Roles → Create Role
  3. Select "Another AWS account"
  4. Enter CloudWise Account ID: 123456789012
  5. Check "Require external ID"
  6. Enter the External ID from Step 1
  7. Click Next

Reference: equivalent CloudFormation template​

If you want to review or adapt the role yourself, this is the equivalent of what the guided template deploys:

AWSTemplateFormatVersion: '2010-09-09'
Description: 'CloudWise Cost Management Role'

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

Resources:
  CloudWiseCostRole:
    Type: AWS::IAM::Role
    Properties:
      RoleName: CloudWiseCostRole
      AssumeRolePolicyDocument:
        Version: '2012-10-17'
        Statement:
          - Effect: Allow
            Principal:
              AWS: arn:aws:iam::123456789012:root
            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 Role
    Value: !GetAtt CloudWiseCostRole.Arn

Step 3: Configure Permissions​

Attach the following policies to your role:

Required Policies:​

  1. AWS Managed Policies:

    • ReadOnlyAccess (for resource optimization recommendations)
    • Billing (for cost and billing data access)

  2. Custom Policy (CloudWise Cost Explorer Access):

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

Step 4: Complete CloudWise Configuration​

  1. Copy the Role ARN from AWS (looks like: arn:aws:iam::YOUR-ACCOUNT:role/CloudWiseCostRole)
  2. Return to the Connect flow in CloudWise
  3. Enter the following details:
    • Account Name: Descriptive name (e.g., "Production Account")
    • AWS Account ID: Your 12-digit AWS account ID
    • Role ARN: The ARN copied in step 1
    • External ID: Pre-filled from earlier
  4. Click "Add Account"

Step 5: Verify Connection​

  1. CloudWise will test the connection immediately
  2. If successful, you'll see a green checkmark
  3. Your first scan runs within ~1 hour of connecting (CloudWise assigns your account to one of 24 hourly scan shards). Cost data typically appears within 2-4 hours; for brand-new AWS Cost and Usage Report configurations, AWS itself may take up to 24 hours to deliver the first report.

🔍 Troubleshooting Common Issues​

Error: "Access Denied"​

Cause: Incorrect permissions or role configuration Solution:

  • Verify the Role ARN is correct
  • Check that all required policies are attached
  • Ensure External ID matches exactly

Error: "Role Cannot Be Assumed"​

Cause: Trust policy configuration issue Solution:

  • Verify CloudWise Account ID in trust policy
  • Check External ID configuration
  • Ensure role name matches

Error: "No Cost Data Available"​

Cause: Missing Cost Explorer permissions or AWS CUR not yet delivered Solution:

  • Add the CloudWise Cost Explorer custom policy
  • Allow up to 24 hours for AWS to deliver the first Cost and Usage Report for a brand-new CUR configuration (CloudWise itself scans hourly)
  • Check AWS Cost Explorer is enabled in your account

Data Appears Incomplete​

Cause: Insufficient read permissions Solution:

  • Add ReadOnlyAccess managed policy
  • Verify access to all required services
  • Check for any SCPs blocking access

🏢 Multi-Account Setup​

AWS Organizations Setup​

If using AWS Organizations:

  1. Master Account Setup:

    • Set up CloudWise role in the master account
    • Enable Cost Explorer and detailed billing
    • Configure consolidated billing preferences

  2. Member Account Setup:

    • Create CloudWise roles in each member account
    • Or use cross-account roles from master account
    • Ensure proper SCPs allow required permissions

  3. CloudWise Configuration:

    • Add each account separately in CloudWise
    • Use consistent naming convention
    • Set up consolidated reporting views

🛡️ Security Best Practices​

1. Principle of Least Privilege​

  • Only grant required permissions
  • Regularly review and audit roles
  • Use condition policies where appropriate

2. External ID Security​

  • Treat External ID as a secret
  • Don't share between different tools
  • Rotate periodically for enhanced security

3. Monitoring & Auditing​

  • Enable CloudTrail for role usage
  • Monitor assume role activities
  • Set up alerts for unusual access patterns

4. Regular Maintenance​

  • Review role permissions quarterly
  • Update policies as CloudWise adds features
  • Remove unused or old roles

📊 What Happens Next?​

After successful setup:

  1. Data Collection (6-8 hours):

    • Historical cost data (up to 12 months)
    • Current resource inventory
    • Usage patterns and trends

  2. Analysis & Recommendations (48-72 hours):

    • Cost optimization opportunities
    • Right-sizing recommendations
    • Reserved Instance suggestions

  3. Ongoing Monitoring:

    • Daily cost updates
    • Real-time budget alerts
    • Anomaly detection

🆘 Need Help?​

⚡ Quick Setup: Most users complete setup in under 10 minutes!
🔒 Secure: Read-only access with external ID verification
📈 Comprehensive: Full cost visibility and optimization insights