AWS Setup

AWS CloudFormation Setup Guide for Cloud Sweeper

This guide walks you through securely connecting your AWS account to Cloud Sweeper using a cross-account IAM role. Follow each step carefully to avoid common mistakes.

1. Deploy the CloudFormation Template

  1. Sign in to the AWS Console: AWS Console
  2. Open CloudFormation: Search for "CloudFormation" in the AWS search bar and select it.
  3. Create a New Stack:
    • Click Create stack > With new resources (standard).
    • Under Specify template, choose Upload a template file.
    • Click Choose file and select the cloudsweeper.yaml template provided by Cloud Sweeper.
    • Click Next.
  4. Stack Details:
    • Stack name: Enter a name (e.g., CloudSweeper-Role).
    • VendorAccountId: Enter 382429920650 (Cloud Sweeper’s AWS account ID).
    • ExternalId: Leave blank to let AWS auto-generate a secure External ID.
    • Click Next.
  5. Configure Options: Add tags if desired (optional). Click Next.
  6. Review and Create: Review all settings. Check the box to acknowledge IAM resource creation. Click Create stack.
  7. Wait for Completion: Wait until the stack status is CREATE_COMPLETE.

2. Retrieve Role ARN and External ID

  1. Go to the Stack Outputs: Select your stack in CloudFormation. Click the Outputs tab. Note the RoleArn and ExternalIdActual values.
  2. Get the Actual External ID:
    • The ExternalIdActual is a reference to a secret in AWS Secrets Manager.
    • Go to Secrets Manager in the AWS Console.
    • Find the secret name from the ExternalIdActual output.
    • Click the secret, then Retrieve secret value.
    • Copy the value of external_id.

3. Configure Cloud Sweeper

  • Role ARN: From CloudFormation Outputs.
  • External ID: The value you retrieved from Secrets Manager.
  • Region: The AWS region where your resources are.

Troubleshooting

  • No Output or Errors? Ensure you are in the correct AWS region. Make sure the stack status is CREATE_COMPLETE. You must have permissions to create IAM roles and access Secrets Manager.
  • RoleDefinitionWithSameNameExists? If you see this error, a role with the same name may already exist. Try a different name or wait a few minutes for changes to propagate.

Security Notes

  • The External ID is a secret—never share it publicly.
  • The IAM role only allows Cloud Sweeper to scan and tag resources, not delete them.
Need help? Contact Support
How to Update Existing Stack

When to Update: If Cloud Sweeper adds new permissions or features, you may need to update your CloudFormation stack to grant additional access. This process is simple and won't change your existing ExternalId or require reconfiguration in Cloud Sweeper.

Important: Your ExternalId Will NOT Change

The ExternalId is only generated once during initial stack creation. When you update the stack, it remains unchanged, so you won't need to reconfigure Cloud Sweeper.

Steps to Update CloudFormation Stack:

  1. Go to CloudFormation Service:
    • Log into AWS Console
    • Navigate to CloudFormation service (search for it in the top search bar)
  2. Select Your Stack:
    • Find your stack (likely named something like "CloudSweeper-Role" or similar)
    • Click on the stack name to select it
  3. Update Stack:
    • Click the Update button at the top right
    • Select Replace current template
  4. Upload New Template:
    • Choose Upload a template file
    • Click Choose file and select your updated cloudsweeper.yaml file
    • Click Next
  5. Review Parameters:
    • Important: Keep the existing parameters (VendorAccountId, ExternalId) unchanged
    • Don't modify the ExternalId field
    • Click Next
  6. Configure Stack Options:
    • Leave everything as default
    • Click Next
  7. Review Changes:
    • Scroll down to the Change set preview section
    • You should see the changes to the IAM policy (e.g., adding new permissions)
    • Check the box: "I acknowledge that AWS CloudFormation might create IAM resources"
    • Click Submit
  8. Wait for Completion:
    • The stack status will show UPDATE_IN_PROGRESS
    • Wait for it to change to UPDATE_COMPLETE (usually takes 1-2 minutes)
    • Refresh the page to see status updates

What's Actually Changing:

The update will only modify the IAM policy attached to the CloudSweeperAccess role (adding new permissions). Everything else remains the same:

  • Role name stays the same
  • ExternalId stays the same
  • Trust relationship stays the same
  • All existing permissions remain intact

Troubleshooting Updates:

  • Update Failed? Ensure you have permissions to update IAM roles. Check the CloudFormation Events tab for specific error messages.
  • No Changes Detected? Make sure you uploaded the latest version of the cloudsweeper.yaml template.
  • Stack Rollback? Check the Events tab to see what caused the rollback. You may need to fix the template or permissions.