Adding Your AWS Account

Introduction

Connecting your AWS account to CloudWrangler is quick and secure. This guide covers all three setup methods and helps you choose the right one for your needs.

Before You Begin

Prerequisites

• AWS account with administrator access
• Your 12-digit AWS Account ID
• Permission to create IAM roles
• (Optional) AWS CLI installed for CLI method

What You'll Need

• Account Name: A friendly name for identification (e.g., "Production", "Development")
• AWS Account ID: Your 12-digit AWS account identifier
• Regions: Which AWS regions to monitor (defaults to all)

Section 1: Account Information

When you start adding an account, you'll provide basic information:

Account Name

Choose a descriptive name that helps you identify this account:

• "Production" - Your production environment
• "Development" - Dev/test environment
• "Customer XYZ" - Client-specific account
• "Billing Account" - Your organization's billing account

AWS Account ID

Your 12-digit AWS account identifier. Find it:

• AWS Console: Top right corner, click on account name
• AWS CLI: aws sts get-caller-identity --query Account --output text
• Billing: Account Settings page

Regions to Monitor

Select which AWS regions CloudWrangler should scan:

• All Regions (recommended) - Discovers resources in all AWS regions
• Specific Regions - Choose only the regions you use
• Common choices: us-east-1, us-west-2, eu-west-1

Section 2: Setup Methods

CloudWrangler offers three methods to create the required IAM role. Choose the one that best fits your workflow.

Method 1: CloudFormation (Recommended)

CloudFormation is the fastest and most reliable method. It automatically creates the IAM role with correct permissions.

Why CloudFormation?

• Fastest setup (2-3 minutes)
• Automatically configures all permissions correctly
• Easy to audit and update
• Supports Infrastructure as Code workflows
• Can be deployed via CLI or Console

Step-by-Step Instructions:

1. Get the CloudFormation URL

   • In the CloudWrangler UI, click CloudFormation Quick Create
   • This generates a pre-filled CloudFormation URL

2. Open AWS CloudFormation Console

   • The link opens in a new tab
   • You'll be in the AWS CloudFormation Console
   • The template is already selected

3. Review the Template

   • Click View in Designer (optional) to see the resources
   • The template creates:
     • IAM role named CloudWranglerAccessRole
     • Trust policy with External ID protection
     • Read-only permissions policy

4. Acknowledge IAM Resource Creation

   • Check the box: "I acknowledge that AWS CloudFormation might create IAM resources"
   • This is required for any template that creates IAM roles

5. Create the Stack

   • Click Create stack
   • Wait 2-3 minutes for stack creation to complete
   • Status will change to CREATE_COMPLETE

6. Verify in CloudWrangler

   • Return to the CloudWrangler tab
   • Click Verify Connection
   • Connection status should show green checkmark

CloudFormation Template Details:

The template creates a single IAM role with:

Resources:
  CloudWranglerAccessRole:
    Type: AWS::IAM::Role
    Properties:
      RoleName: CloudWranglerAccessRole
      AssumeRolePolicyDocument:
        Version: '2012-10-17'
        Statement:
          - Effect: Allow
            Principal:
              AWS: arn:aws:iam::119632503960:root
            Action: sts:AssumeRole
            Condition:
              StringEquals:
                sts:ExternalId: !Ref ExternalId
      ManagedPolicyArns:
        - arn:aws:iam::aws:policy/ReadOnlyAccess

Troubleshooting CloudFormation:

• "Role already exists" - Delete the existing role or use a different name
• "Insufficient permissions" - You need IAM administrator access
• Stack fails to create - Check CloudFormation events tab for details
• Can't find the stack - Make sure you're in the correct AWS region

Method 2: AWS Console Manual Setup

If you prefer manual configuration or can't use CloudFormation, you can create the role manually in the AWS Console.

When to Use Console Setup:

• Your organization doesn't allow CloudFormation
• You want to understand each permission manually
• You need to customize the role name
• You're learning AWS IAM concepts

Step-by-Step Instructions:

1. Open IAM Console

   • Go to AWS Console → IAM → Roles
   • Click Create role

2. Select Trusted Entity

   • Choose AWS account
   • Select Another AWS account
   • Enter Account ID: 119632503960
   • Check Require external ID
   • Enter your CloudWrangler Workspace ID (shown in UI)

3. Attach Permissions Policy

   • Search for ReadOnlyAccess
   • Check the box next to ReadOnlyAccess (AWS managed policy)
   • Click Next

4. Name the Role

   • Role name: CloudWranglerAccessRole
   • Description: "Read-only access for CloudWrangler infrastructure monitoring"
   • Click Create role

5. Verify in CloudWrangler

   • Return to CloudWrangler
   • Click Verify Connection
   • Connection should succeed

Trust Policy Document:

The trust policy should look like this:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "AWS": "arn:aws:iam::119632503960:root"
      },
      "Action": "sts:AssumeRole",
      "Condition": {
        "StringEquals": {
          "sts:ExternalId": "YOUR-WORKSPACE-ID"
        }
      }
    }
  ]
}

Permissions Policy:

Attach the AWS managed policy: arn:aws:iam::aws:policy/ReadOnlyAccess

Troubleshooting Manual Setup:

• External ID mismatch - Copy the exact ID from CloudWrangler UI
• Wrong account ID - CloudWrangler account must be 119632503960
• Policy not attached - Verify ReadOnlyAccess policy is attached to the role
• Can't assume role - Check trust policy syntax and External ID

Method 3: AWS CLI

For DevOps teams and automation, use the AWS CLI to create the role programmatically.

When to Use CLI:

• You're automating account onboarding
• You prefer command-line tools
• You're adding multiple accounts
• You want to script the process

Step-by-Step Instructions:

1. Set Environment Variables

export WORKSPACE_ID="your-workspace-id-from-ui"
export AWS_ACCOUNT_ID="119632503960"
export ROLE_NAME="CloudWranglerAccessRole"

2. Create Trust Policy File

cat > trust-policy.json <<EOF
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "AWS": "arn:aws:iam::${AWS_ACCOUNT_ID}:root"
      },
      "Action": "sts:AssumeRole",
      "Condition": {
        "StringEquals": {
          "sts:ExternalId": "${WORKSPACE_ID}"
        }
      }
    }
  ]
}
EOF

3. Create the IAM Role

aws iam create-role \
    --role-name ${ROLE_NAME} \
    --assume-role-policy-document file://trust-policy.json \
    --description "CloudWrangler read-only access role"

4. Attach ReadOnlyAccess Policy

aws iam attach-role-policy \
    --role-name ${ROLE_NAME} \
    --policy-arn arn:aws:iam::aws:policy/ReadOnlyAccess

5. Verify in CloudWrangler
   • Add the account in the UI
   • Click Verify Connection

Complete Script:

Here's a complete script to create the role:

#!/bin/bash
set -e
 
# Configuration
WORKSPACE_ID="your-workspace-id"
CLOUDWRANGLER_ACCOUNT="119632503960"
ROLE_NAME="CloudWranglerAccessRole"
 
# Create trust policy
cat > /tmp/trust-policy.json <<EOF
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "AWS": "arn:aws:iam::${CLOUDWRANGLER_ACCOUNT}:root"
      },
      "Action": "sts:AssumeRole",
      "Condition": {
        "StringEquals": {
          "sts:ExternalId": "${WORKSPACE_ID}"
        }
      }
    }
  ]
}
EOF
 
# Create role
echo "Creating IAM role..."
aws iam create-role \
    --role-name ${ROLE_NAME} \
    --assume-role-policy-document file:///tmp/trust-policy.json \
    --description "CloudWrangler read-only access"
 
# Attach policy
echo "Attaching ReadOnlyAccess policy..."
aws iam attach-role-policy \
    --role-name ${ROLE_NAME} \
    --policy-arn arn:aws:iam::aws:policy/ReadOnlyAccess
 
echo "Role created successfully!"
 
# Cleanup
rm /tmp/trust-policy.json

Troubleshooting CLI:

• "Role already exists" - Delete the existing role with aws iam delete-role
• "Access denied" - Ensure your AWS CLI credentials have IAM permissions
• "Invalid parameter" - Check JSON syntax in trust-policy.json
• Can't attach policy - Role must exist before attaching policies

Section 3: Verification

After creating the IAM role, CloudWrangler verifies the connection.

How Verification Works

CloudWrangler attempts to:

1. Assume the IAM role using the External ID
2. Call sts:GetCallerIdentity to verify access
3. List EC2 regions to test read permissions
4. Store the connection if successful

Verification States

Success (Green Checkmark)

• Connection verified successfully
• Role can be assumed
• Read permissions confirmed
• Resource discovery can begin

Pending (Yellow Warning)

• Verification not yet attempted
• Waiting for background job
• Click "Verify Now" to trigger manually

Failed (Red Error)

• Cannot assume role
• Permission issues detected
• See error message for details
• Check troubleshooting guide below

Manual Verification

To manually verify the connection:

1. Click Verify Connection button
2. Wait 5-10 seconds for result
3. Green checkmark = Success
4. Red error = See error message

Troubleshooting Verification Failures

Error: "Access Denied"

• Check the trust policy includes the correct External ID
• Verify CloudWrangler account ID is 119632503960
• Ensure role exists in your AWS account

Error: "Role not found"

• Double-check the role name (default: CloudWranglerAccessRole)
• Verify you created the role in the correct AWS account
• Wait a few minutes for IAM to propagate

Error: "External ID mismatch"

• External ID must match your Workspace ID exactly
• Copy the ID from CloudWrangler UI
• Update the trust policy with correct External ID

Error: "Insufficient permissions"

• Verify ReadOnlyAccess policy is attached
• Check the policy attachment was successful
• Try detaching and re-attaching the policy

Section 4: Managing Multiple Accounts

CloudWrangler supports unlimited AWS accounts for comprehensive infrastructure visibility.

Adding Additional Accounts

To add more AWS accounts:

1. Click Add Account button
2. Repeat the setup process for each account
3. Use the same External ID (Workspace ID) for all accounts
4. Each account gets its own IAM role

Best Practices for Multiple Accounts

Naming Convention

• Use descriptive names: "Production", "Staging", "Development"
• Include environment or team: "API-Production", "Frontend-Dev"
• Add customer names for client accounts: "Client-Acme-Prod"

Organization

• Group related accounts (all prod, all dev)
• Use consistent role names across accounts
• Document which accounts are monitored

AWS Organizations

• Create a StackSet to deploy roles across all accounts
• Use consistent External IDs
• Centralize role management

Switching Between Accounts

View data from different accounts:

1. Use the Account Selector dropdown in the header
2. Select specific account to view its resources
3. Choose "All Accounts" for aggregated view
4. Filters apply to the selected account

Account Management

Edit Account

• Update account name
• Change enabled regions
• Modify connection settings

Refresh Account

• Manually verify connection
• Trigger resource discovery
• Update resource inventory

Remove Account

• Disconnect from CloudWrangler
• Stop resource discovery
• Archive historical data (optional)
• IAM role remains in your AWS account (you must delete manually)

Multi-Account Cost Savings

With multiple accounts connected:

• View consolidated cost savings across all accounts
• Filter findings by specific accounts
• Compare costs between environments
• Identify cross-account optimization opportunities

Security Considerations

External ID Protection

The External ID prevents "confused deputy" attacks:

• Each workspace has a unique External ID
• All accounts in a workspace use the same External ID
• Only CloudWrangler with your Workspace ID can assume roles
• Never share your External ID publicly

Least Privilege

CloudWrangler follows least-privilege principles:

• Uses AWS managed ReadOnlyAccess policy
• Cannot modify any resources
• Cannot delete or create resources
• All API calls appear in CloudTrail

Audit Trail

Monitor CloudWrangler's access:

• All AWS API calls appear in CloudTrail
• Filter by role name: CloudWranglerAccessRole
• Review assumed role sessions
• Alert on unexpected API calls

Revoking Access

To revoke CloudWrangler's access:

1. In AWS: Delete the IAM role

   aws iam detach-role-policy \
       --role-name CloudWranglerAccessRole \
       --policy-arn arn:aws:iam::aws:policy/ReadOnlyAccess
    
   aws iam delete-role --role-name CloudWranglerAccessRole

2. In CloudWrangler: Remove the account

   • Click Remove on the account card
   • Confirm deletion

Access is immediately revoked.

Next Steps

Now that your account is connected:

Frequently Asked Questions

Q: How many accounts can I connect? A: Unlimited. CloudWrangler supports as many AWS accounts as you need.

Q: Can I use a custom IAM policy instead of ReadOnlyAccess? A: Yes, but ensure it includes permissions for EC2, RDS, ElastiCache, ELB, VPC, and S3 (for Flow Logs).

Q: Does CloudWrangler support AWS Organizations? A: Yes. You can create a StackSet to deploy the role across all member accounts automatically.

Q: Can I change the role name? A: Yes. Enter a custom role name when adding the account. Just ensure you create the role with that name.

Q: How often does CloudWrangler assume the role? A: During resource discovery (every 12 hours) and when you manually refresh. Sessions last 15 minutes.

Q: Will this increase my AWS costs? A: No. API calls for resource discovery are free. VPC Flow Logs (optional) have costs (~$0.50/GB).

Q: Can CloudWrangler access my data? A: No. ReadOnlyAccess allows listing resources and metadata only. It cannot read S3 bucket contents, RDS data, or secrets.