AWS Onboarding Wizard
The AWS onboarding wizard automates the setup of IAM roles and trust relationships required for CloudQuery to access your AWS accounts. Instead of manually creating roles and editing YAML, the wizard deploys a CloudFormation stack that provisions everything automatically using OIDC-based authentication.
For manual setup using the AWS CLI, see the AWS manual integration guide.
Prerequisites
- A CloudQuery Platform account with admin access
- AWS console access with permissions to create CloudFormation stacks and IAM roles
- If using multi-account mode: access to the AWS Organizations management account
The CloudFormation stack creates IAM roles with ReadOnlyAccess permissions in your account. Review the stack template before deploying to confirm the permissions meet your organization’s security requirements.
Step 1: Start the wizard
- Navigate to Data Pipelines → Integrations.
- Click Create Integration and select AWS.
- The wizard opens with the connection setup step.
Step 2: Choose account mode
Select your AWS setup:
- Multiple accounts — for AWS Organizations with multiple member accounts. CloudQuery discovers your organizational structure and provisions roles across accounts.
- Single account — for a standalone AWS account not part of an organization.
Step 3: Deploy the CloudFormation stack
- Click Open AWS console. This opens the AWS CloudFormation console in a new tab with a pre-configured stack template.
- Review the stack parameters in the AWS console. The stack pre-fills the OIDC trust relationship parameters (audience, issuer URL, subject).
- Check the I acknowledge that AWS CloudFormation might create IAM resources with custom names checkbox and click Create stack.
The IAM capabilities acknowledgment is required because the stack creates IAM roles. This is standard for CloudFormation stacks that manage IAM resources. See the AWS CloudFormation IAM capabilities documentation for details.
The CloudFormation stack creates:
- A management IAM role with an OIDC trust relationship back to CloudQuery Platform
- Read-only permissions for CloudQuery to access your AWS resources
- A webhook notification so CloudQuery Platform knows when the stack is ready
CloudQuery Platform polls for the stack deployment status automatically. The wizard updates when the stack finishes deploying.
Step 4: Select organizational units (multi-account only)
If you chose Multiple accounts, the wizard displays your AWS organization structure as a tree after the CloudFormation stack deploys:
- Expand organizational units to see child OUs and accounts.
- Select the organizational units you want CloudQuery to sync from.
- Click Submit to provision IAM roles for the selected OUs.
CloudQuery creates member roles in each account within the selected organizational units. The wizard displays provisioning status.
For Single account mode, the wizard skips this step — IAM roles are provisioned automatically after the stack deploys.
Step 5: Select services and configure
After IAM roles are provisioned, the wizard moves to the configuration step:
-
Services — select which AWS services to sync. The top 8 services are highlighted, and you can search for additional services.
-
Regions — choose specific regions or leave the default to sync all regions.
-
Advanced options (optional):
- Initialization concurrency (default: 1000)
- Max retries and backoff settings
- Custom endpoint configuration
- Scheduler strategy (
dfs,round-robin,shuffle) - Table-level options via YAML
-
Click Save to complete the integration setup.
Status states
During setup, the wizard displays the current status:
| Status | Description |
|---|---|
| Deploying | CloudFormation stack is being created in AWS |
| Deployed | Stack created, waiting for OU selection (multi-account) |
| Provisioning | Creating IAM roles for selected organizational units |
| Completed | All roles created, integration ready |
| Failed | Stack deployment or role provisioning failed — check the error message and retry |
What gets synced
The AWS integration can sync over 500 tables across all major AWS services. Some of the most commonly used tables include:
| Category | Tables | Description |
|---|---|---|
| Compute | aws_ec2_instances, aws_lambda_functions | EC2 instances, Lambda functions |
| Storage | aws_s3_buckets, aws_ebs_volumes | S3 buckets, EBS volumes |
| Networking | aws_ec2_vpcs, aws_ec2_security_groups, aws_ec2_subnets | VPCs, security groups, subnets |
| Identity | aws_iam_roles, aws_iam_users, aws_iam_policies | IAM roles, users, policies |
| Databases | aws_rds_instances, aws_rds_clusters | RDS instances and clusters |
The wizard lets you select which AWS services to sync in Step 5. See the full AWS table list for all available tables.
Verify the integration
After your first sync completes, open the SQL Console and run these queries to confirm data arrived:
-- Count synced EC2 instances
SELECT count(*) FROM aws_ec2_instances-- List synced AWS accounts and regions
SELECT DISTINCT account_id, region FROM aws_ec2_instances-- View S3 buckets across accounts
SELECT account_id, name, region FROM aws_s3_buckets LIMIT 10-- Check IAM roles in your accounts
SELECT account_id, role_name FROM aws_iam_roles LIMIT 10You can also browse your AWS resources in the Asset Inventory under the Compute, Storage, Identity, and other categories.
Troubleshooting
| Issue | Cause | Fix |
|---|---|---|
| CloudFormation stack fails to create | Insufficient permissions | Verify your AWS user has cloudformation:CreateStack and iam:CreateRole permissions. Check the Events tab in the CloudFormation console for specific error details. |
Stack stuck in CREATE_IN_PROGRESS | Large organization or slow webhook | Wait up to 10 minutes. If the stack is still deploying, check the CloudFormation console for progress. |
| Provisioning fails for member accounts | StackSet deployment issues | Verify your management account has the CloudFormation StackSets service-linked role. Check that target OUs have accounts. |
| OIDC trust error | Trust relationship misconfigured | The wizard auto-configures this. If it fails, check that your CloudQuery Platform deployment has a valid OIDC issuer. See AWS OIDC documentation. |
| No data after sync | No services selected | Return to the integration and verify you selected at least one AWS service to sync in Step 5. |
Re-entering an existing setup
If you return to an integration that was set up with the wizard, the wizard shows the previously created IAM roles and organizational units. You can reset the connection to reconfigure if needed.
When to use manual setup instead
Use the manual AWS integration guide if:
- Your environment restricts CloudFormation stack creation
- You need custom IAM policies beyond read-only access
- You manage IAM roles through infrastructure-as-code (Terraform, CDK) and want to maintain those definitions externally
- You are in an air-gapped environment without access to the CloudQuery OIDC issuer
Next steps
- Set up a sync to schedule when your AWS data is fetched
- Browse synced resources in the Asset Inventory
- Run advanced queries in the SQL Console
- See the AWS integration documentation for full configuration options and table reference