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 Integration guide.

Prerequisites

• Admin access to CloudQuery Platform
• AWS console access with permissions to create CloudFormation stacks and IAM roles
• If using multi-account mode: access to the AWS Organizations management account

Step 1: Start the wizard

1. Navigate to Data Pipelines → Integrations.
2. Click Create Integration and select AWS.
3. 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

1. Click Open AWS console. This opens the AWS CloudFormation console in a new tab with a pre-configured stack template.
2. Review the stack parameters in the AWS console. The OIDC trust relationship parameters (audience, issuer URL, subject) are pre-filled automatically.
3. Acknowledge the IAM capabilities checkbox and click Create stack.

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 is deployed.

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. The provisioning status is displayed in the wizard.

For Single account mode, this step is skipped — 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:

1. Services — select which AWS services to sync. The top 8 services are highlighted, and you can search for additional services.

2. Regions — choose specific regions or leave the default to sync all regions.

3. 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

4. Click Save to complete the integration setup.

What happens next

After the wizard completes, the AWS integration is ready to use in a sync. The management role ARN and organizational unit configuration are automatically applied — no manual YAML editing required.

Status states

During setup, the wizard displays the current status:

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