AWS Onboarding Wizard

The AWS onboarding wizard creates a unified AWS integration that consolidates asset inventory, cost and usage reporting, and additional metadata into a single setup flow. One CloudFormation deployment provisions all required IAM roles and OIDC trust, and CloudQuery automatically creates separate syncs for each feature you enable.

If you need to define the IAM roles and policies manually, see AWS (Manual Setup) and AWS Cost & Usage.

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
• If enabling Cost Metrics: access to AWS Billing and Cost Management

Step 1: Select configuration mode

1. Navigate to Data Pipelines → Integrations.
2. Click Create Integration and select AWS.
3. Choose how to configure what CloudQuery syncs from your AWS account.

• All features: enables all three features automatically — Asset Inventory, Cost Metrics, and Additional Metadata. Recommended for most users.
• Individual features: lets you choose which features to enable from the list below.
• Manual services and tables configuration: lets you select individual AWS services or specific tables to sync. Does not set up Cost Metrics.

If you selected Individual features, choose from the following:

If you selected Manual services and tables configuration, choose the AWS services or individual tables you want to sync. Cost Metrics are not available in this mode.

Step 2: Choose authentication method and account scope

Select how CloudQuery authenticates with AWS, and whether you are syncing a single account or an entire organization.

Authentication method:

• Guided: CloudQuery generates a CloudFormation template that provisions all required IAM roles and OIDC trust automatically based on the features selected in the previous step. Recommended for most users.
• Manual: Provide your own IAM role ARNs. Use this if your organization manages IAM roles through infrastructure-as-code (Terraform, CDK) or restricts CloudFormation usage. See AWS (Manual Setup) for instructions on how to create the required IAM roles.

Account scope:

• Multiple accounts: for AWS Organizations with multiple member accounts. CloudQuery discovers your organizational structure and provisions roles across accounts automatically.
• Single account: for a standalone AWS account.

Step 3: Deploy the CloudFormation stack (guided only)

If you chose Guided, a single CloudFormation stack provisions everything required for your selected features.

1. First, in a new browser tab, make sure you are logged in to AWS Console with the account that will be deploying the CloudFormation stack. If you selected to sync from multiple accounts and want to sync an organization, log in either with a root account or a delegated admin account.
2. If you are syncing multiple accounts, your management account must have trusted access enabled between CloudFormation and AWS Organizations. You can enable it via AWS Organizations → Services → CloudFormation StackSets or by running:

aws organizations enable-aws-service-access --service-principal member.org.stacksets.cloudformation.amazonaws.com

3. Click Open AWS console. This opens the AWS CloudFormation console with a pre-configured stack template.
4. Review the stack parameters. The stack pre-fills the OIDC trust relationship parameters (audience, issuer URL, subject) for CloudQuery.
5. Check the I acknowledge that AWS CloudFormation might create IAM resources with custom names checkbox and click Create stack.

Depending on the features you selected, the stack creates:

• An IAM management role (for organization-wide account discovery, if multi-account)
• IAM sync roles used by CloudQuery when running syncs
• An OIDC identity provider (trust relationship with CloudQuery Platform)
• CUR-specific IAM roles and S3 bucket access (if Cost Metrics is enabled)

CloudQuery Platform polls for the stack deployment status and updates the wizard automatically when the stack finishes deploying.

If you chose Manual, enter the IAM role ARN(s) you have provisioned in your AWS account and click Continue.

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:

1. Expand organizational units to see child OUs and accounts.
2. Select the organizational units you want CloudQuery to sync from.
3. Click Submit to provision IAM roles for the selected OUs.

CloudQuery creates member roles in each account within the selected organizational units and displays provisioning status. For Single account mode this step is skipped automatically.

Step 5: Verify CUR access (Cost Metrics only)

If you enabled Cost Metrics, the wizard verifies that CloudQuery can access the S3 bucket where your CUR 2.0 Parquet export is stored.

Step 6: Test connections

CloudQuery runs a connection test for each enabled feature to validate AWS connectivity before creating the syncs.

If any test fails, the wizard shows an error with a suggested fix. Correct the issue and click Retry.

Step 7: Specify the schedule and destination

You can specify how often the integration data gets refreshed from the cloud provider. We recommend scheduling syncs to run daily to keep your asset inventory and insights up to date.

If you choose to sync to an external destination (other than CloudQuery), the synced data will not be visible in CloudQuery directly.

Review your selected configuration and click Create to finalize. CloudQuery will start syncing the data.

Verify the integration

After your first syncs complete, browse your AWS resources in the Asset Inventory under the Compute, Storage, Identity, and other categories.

You can also 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

Troubleshooting

Re-entering an existing setup

If you want to modify any of the existing configuration to add or remove synced tables, navigate to Data Pipelines → Integrations and edit the individual integration definitions.

Next steps

• 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

Related resources

• AWS CloudFormation documentation
• AWS IAM OIDC identity providers
• AWS Organizations and organizational units
• AWS CUR 2.0 documentation
• CloudQuery AWS integration on Hub