AWS Account Setup

Overview

Connecting your AWS account to CloudWrangler requires deploying a read-only IAM role. This guide shows you three ways to deploy the role.

Prerequisites

• AWS account with IAM permissions to create roles
• CloudWrangler workspace and project ID
• AWS CLI installed (optional, for CLI method)

Step 1: Get Your Project ID

Your Project ID is used as the External ID for security:

1. Log in to CloudWrangler
2. Go to Settings → AWS Accounts
3. Click Add AWS Account
4. Copy the Project ID (it looks like 550e8400-e29b-41d4-a716-446655440000)

Step 2: Deploy IAM Role

Choose one of three methods:

Option A: CloudFormation (Recommended)

Fastest and easiest method:

1. In CloudWrangler, click Add AWS Account
2. Click the CloudFormation Quick Create button
3. This opens AWS CloudFormation Console in a new tab
4. Review the stack parameters:
   • Stack name: CloudWrangler-Access-Role
   • ExternalId: Your Project ID (pre-filled)
   • CloudWranglerAccountId: 119632503960 (pre-filled)
5. Check ✅ "I acknowledge that AWS CloudFormation might create IAM resources"
6. Click Create stack
7. Wait ~2 minutes for completion

Option B: AWS CLI

For automation or GitOps workflows:

# Download the CloudFormation template
curl -O https://cloudwrangler-public.s3.amazonaws.com/cloudformation-role.yaml
 
# Deploy the stack
aws cloudformation create-stack \
    --stack-name CloudWrangler-Access-Role \
    --template-body file://cloudformation-role.yaml \
    --parameters \
        ParameterKey=ExternalId,ParameterValue=YOUR-PROJECT-ID \
        ParameterKey=CloudWranglerAccountId,ParameterValue=119632503960 \
    --capabilities CAPABILITY_NAMED_IAM
 
# Wait for completion
aws cloudformation wait stack-create-complete \
    --stack-name CloudWrangler-Access-Role

Replace YOUR-PROJECT-ID with your actual Project ID.

Option C: Manual IAM Role Creation

For custom setups or restricted environments:

1. Go to IAM Console → Roles → Create role
2. Select AWS account
3. Choose Another AWS account
4. Enter Account ID: 119632503960
5. Check ✅ Require external ID
6. Enter your Project ID as the External ID
7. Click Next
8. Attach policy: ReadOnlyAccess (AWS managed policy)
9. Click Next
10. Name: CloudWranglerAccessRole
11. Click Create role

Step 3: Add Account in CloudWrangler

1. Go to Settings → AWS Accounts
2. Click Add AWS Account
3. Fill in the form:
   • Account Name: Friendly name (e.g., "Production")
   • AWS Account ID: Your 12-digit account ID
   • Role Name: CloudWranglerAccessRole (default)
   • Regions: Select regions to scan (or leave empty for all)
4. Click Add Account

CloudWrangler will immediately verify it can assume the role.

Step 4: Verification

After adding the account:

1. CloudWrangler attempts to assume the role
2. If successful, status shows Verified ✅
3. Resource discovery starts automatically
4. Check the Resource Inventory page in ~1 minute

Verification Statuses

• 🟢 Verified: Role assumption successful (checked within last hour)
• 🟡 Pending: Not yet verified or verification in progress
• 🔴 Failed: Cannot assume role (see error message)

What Happens Next?

After successful verification:

1. Automatic Discovery: CloudWrangler discovers resources in all enabled regions
2. Periodic Refresh: Resources are re-discovered every 12 hours
3. Continuous Monitoring: Role is verified every hour

Discovered Resources

CloudWrangler automatically discovers:

• Compute: EC2 instances, Auto Scaling Groups
• Databases: RDS instances, Aurora clusters
• Caching: ElastiCache Redis/Memcached
• Load Balancers: ALB, NLB, Classic ELB
• Networking: VPCs, subnets, route tables, gateways, peering connections
• Storage: S3 buckets (metadata only)

Discovery typically takes 30-60 seconds per region.

Troubleshooting

"Role Verification Failed"

Common causes and solutions:

1. Wrong External ID

# Verify the trust policy
aws iam get-role --role-name CloudWranglerAccessRole \
    --query 'Role.AssumeRolePolicyDocument'

The trust policy should include your Project ID as the sts:ExternalId.

2. Missing ReadOnlyAccess Policy

# Check attached policies
aws iam list-attached-role-policies --role-name CloudWranglerAccessRole

You should see arn:aws:iam::aws:policy/ReadOnlyAccess.

3. Wrong CloudWrangler Account ID

The trust policy should trust account 119632503960.

4. Role Name Mismatch

If you used a different role name, update it in CloudWrangler settings.

"No Resources Found"

If discovery finds zero resources:

1. Wait 2-3 minutes for discovery to complete
2. Check you have resources in the enabled regions
3. Verify the role has ReadOnlyAccess attached
4. Check Discovery Jobs page for task status
5. Look for error messages in the job logs

"Access Denied" Errors

If you see permission errors:

1. Ensure ReadOnlyAccess policy is attached
2. Check CloudTrail for specific denied API calls
3. Some AWS services require additional permissions (rare)

Managing Regions

You can control which regions CloudWrangler scans:

1. Go to Settings → AWS Accounts
2. Click on your account
3. Click Edit Regions
4. Select/deselect regions
5. Click Save

Reducing regions speeds up discovery and reduces API calls.

Updating the Role

If you need to update the IAM role:

1. Update the CloudFormation stack (recommended)
2. Or manually update the role in IAM Console
3. Changes take effect immediately (no need to reconnect)

Removing an Account

To disconnect an account:

1. Go to Settings → AWS Accounts
2. Click on the account
3. Click Delete Account
4. Confirm deletion

This removes all data from CloudWrangler. The IAM role in your AWS account remains (delete it manually if needed).

Security Best Practices

1. ✅ Use CloudFormation for consistent deployments
2. ✅ Restrict External ID access (only share with CloudWrangler)
3. ✅ Enable CloudTrail to audit API calls
4. ✅ Review CloudWrangler's API calls periodically
5. ✅ Use separate AWS accounts for dev/prod
6. ✅ Limit regions to only those you use

Next Steps