Import your existing AWS account into CloudBooster
- You need **Organization Admin** or **Project Owner** access in CloudBooster.
Import your existing AWS account into CloudBooster
This guide walks you through importing an existing AWS account into CloudBooster using the built-in import wizard. The wizard discovers your live resources, generates an AI-powered narration of your infrastructure, and lets you review and confirm the mapping before CloudBooster begins managing everything through GitOps.
Before you begin
- You need Organization Admin or Project Owner access in CloudBooster.
- You need permission to create IAM roles and CloudFormation stacks in the target AWS account.
- Review the cross-account role security model to understand exactly what permissions CloudBooster requests and how credentials are stored.
Step 1 — Connect AWS
Open the import wizard from the CloudBooster portal: Projects → Import → AWS Account.
- Choose the target project (or create a new one).
- Select AWS as the provider.
- CloudBooster generates a CloudFormation template URL and an external ID.
- In your AWS console, launch the CloudFormation stack using the provided template.
- Return to CloudBooster and click Verify connection.
The wizard confirms that the cross-account IAM role is assumable and lists the regions it can access.
Step 2 — Scan
Once the connection is verified, click Start scan.
CloudBooster performs a read-only discovery across every enabled region. The scan enumerates:
- Compute: EC2 instances, Auto Scaling groups, Launch templates
- Networking: VPCs, subnets, route tables, Internet gateways, NAT gateways, load balancers
- Storage: S3 buckets, EBS volumes
- Databases: RDS instances, DynamoDB tables
- Security: Security groups, IAM roles, KMS keys
- Containers: ECS clusters, EKS clusters
A progress bar shows per-region status. The scan is entirely read-only — no changes are made to your AWS account.
Step 3 — Review dashboard
After the scan completes, the Review Dashboard presents every discovered resource in a searchable, filterable table.
| Column | Description |
|---|---|
| Resource | AWS resource type and logical name |
| Region | AWS region where the resource lives |
| CB Mapping | The CloudBooster resource definition that will manage this asset |
| Status | Mapped, Unmapped, or Conflict |
You can:
- Toggle resources in or out of the import set.
- Override the proposed CB mapping for individual resources.
- Group by tag, region, or resource family.
Step 4 — AI narration
Click Generate narration to produce a human-readable summary of your infrastructure.
CloudBooster's AI analyzes the discovered topology and writes a Markdown document that describes:
- The overall architecture (e.g., "Three-tier web application with a public ALB, two EC2 instances in private subnets, and an RDS PostgreSQL backend").
- Data flow between resources.
- Identified best-practice gaps (e.g., missing encryption, overly permissive security groups).
- Recommended CloudBooster compositions to replace manual configuration.
You can edit the narration inline before it is committed to the project docs.
Step 5 — Confirm
When you are satisfied with the mapping and narration, click Confirm import.
CloudBooster:
- Generates Crossplane Claims for every mapped resource.
- Writes the Claims and the AI narration to the project's GitOps repository.
- Opens a pull request (if GitOps is configured for review) or applies immediately (if auto-apply is enabled).
- Creates a project snapshot so the import can be rolled back.
You receive a confirmation summary showing the number of resources under management, the GitOps commit SHA, and an estimated reconciliation time.
Step 6 — Manage
After confirmation, your resources appear in the CloudBooster portal as first-class managed assets.
From the project view you can:
- Drift detection: CloudBooster continuously compares the live AWS state with the GitOps Claims and surfaces discrepancies.
- Policy enforcement: Apply CB resource policies (e.g., mandatory tagging, encryption requirements).
- Cost insights: See per-resource cost attribution based on AWS CUR data.
- One-click updates: Modify parameters in the portal UI; CloudBooster generates the updated Claim and pushes it through GitOps.
Sample AWS account state
The screenshots in this guide were captured using the following reproducible AWS account configuration. You can recreate this state in a sandbox account to refresh the screenshots without changing the narrative.
Account: 123456789012 (sandbox)
Alias: cb-import-demo
Default region: us-east-1
Secondary region: eu-west-1
Compute
| Resource | Type | Region | Details |
|---|---|---|---|
web-server-01 | EC2 t3.micro | us-east-1a | Amazon Linux 2023, cb-demo-web SG |
web-server-02 | EC2 t3.micro | us-east-1b | Amazon Linux 2023, cb-demo-web SG |
app-asg | Auto Scaling group | us-east-1 | Min 2, max 4, target tracking on CPU |
lt-web | Launch template | us-east-1 | AMI ami-0abcdef1234567890, user data installs nginx |
Networking
| Resource | Type | Region | Details |
|---|---|---|---|
vpc-cbdemo | VPC | us-east-1 | CIDR 10.0.0.0/16 |
subnet-public-a | Subnet | us-east-1a | CIDR 10.0.1.0/24 |
subnet-public-b | Subnet | us-east-1b | CIDR 10.0.2.0/24 |
subnet-private-a | Subnet | us-east-1a | CIDR 10.0.3.0/24 |
subnet-private-b | Subnet | us-east-1b | CIDR 10.0.4.0/24 |
igw-cbdemo | Internet gateway | us-east-1 | Attached to vpc-cbdemo |
alb-web | Application Load Balancer | us-east-1 | Internet-facing, HTTP:80 |
Storage
| Resource | Type | Region | Details |
|---|---|---|---|
cb-demo-assets | S3 bucket | us-east-1 | Versioning enabled, SSE-S3 |
cb-demo-logs | S3 bucket | us-east-1 | Lifecycle: transition to Glacier after 90 days |
web-data-vol | EBS gp3 | us-east-1a | 20 GB, attached to web-server-01 |
Database
| Resource | Type | Region | Details |
|---|---|---|---|
cb-demo-db | RDS PostgreSQL 15 | us-east-1a | db.t3.micro, storage encrypted |
Security
| Resource | Type | Region | Details |
|---|---|---|---|
cb-demo-web | Security group | us-east-1 | Ingress 80/443 from 0.0.0.0/0, egress open |
cb-demo-db | Security group | us-east-1 | Ingress 5432 from cb-demo-web SG only |
EC2InstanceRole | IAM role | us-east-1 | AmazonSSMManagedInstanceCore attached |
Tags (applied to all resources)
| Key | Value |
|---|---|
Project | cb-import-demo |
Environment | sandbox |
ManagedBy | manual |
What if?
No resources found
If the scan completes but the dashboard shows 0 resources, check the following:
- Region coverage: The CloudFormation stack may have restricted CloudBooster to specific regions. Open the stack parameters and verify that
AllowedRegionsincludes the regions where your resources live. - IAM policy: The cross-account role needs
ReadOnlyAccess(or the granular permissions listed in the security model). If the role was created manually instead of via the provided CloudFormation template, compare its policies against the reference. - Resource exclusion: Some resource types (e.g., S3 buckets in opt-in regions) are skipped by default. Expand the Advanced scan settings panel in the wizard and enable the relevant resource families.
- Timing: Very large accounts can take several minutes. Wait for the scan status to show Completed rather than Partial.
Scan failure
If the scan fails with an error message, the most common causes are:
- Expired credentials: The cross-account role has a maximum session duration (default 1 hour). If the wizard was idle for longer than that, click Refresh credentials to re-assume the role.
- Throttling: AWS API rate limits can interrupt large scans. The wizard automatically retries with exponential backoff. If it still fails, reduce the number of scanned regions and try again.
- Permission denied: A specific
AccessDeniederror usually points to a missing IAM action. Copy the error detail from the wizard and compare it against the required actions in the security model. - Network issues: If your organization uses VPC endpoints or SCPs that restrict API calls, ensure that
sts:AssumeRoleand the relevant service endpoints are reachable from CloudBooster's backend.
Ambiguous mappings
Sometimes CloudBooster discovers a resource but cannot confidently map it to a single CB resource definition. This is shown as Ambiguous in the Status column.
- Click the resource row to open the mapping panel. CloudBooster lists the candidate definitions with a confidence score.
- Review the schema compatibility: Each candidate shows which parameters can be inferred from the live resource and which require manual input.
- Pick the best match or select Skip to leave the resource unmanaged.
- If none of the candidates fit, you can Request a new definition from the CloudBooster support team. Include the resource ARN and a brief description of the desired management behavior.
Next steps
- Manage imported resources in the CloudBooster portal
- Read the cross-account role security model
- Import a Terraform stack
- Import a Pulumi stack