General Integration Setup Guide
Prerequisites
- A CloudQuery Platform account with admin access
Creating the integration
In the sidebar, go to Data Sources → Integrations and click Add new integration:
Search for the name of your integration. In the example below, the search is for Microsoft Entra ID (Azure AD):
On the next screen, enter an Integration Name to identify the integration later (if unsure, use the name of the integration).
Fill in the required configuration fields for the integration. Most integrations present a guided form with fields for authentication credentials and configuration options.
Some integrations use a YAML specification field instead of a guided form. For those, store sensitive values as secrets in the Secrets section and reference them using placeholders such as ${MY_SECRET_VALUE}. See the integration’s documentation for the required format.
Testing your connection
When you’re ready, click Continue. The platform creates a test connection job that validates your configuration by attempting to authenticate with the source and fetch a small amount of data.
During the test:
- A progress bar shows the test is running (tests can take up to 60 seconds)
- If the test succeeds, the integration is saved and ready to use in a sync
- If the test fails, an error message is displayed with details about what went wrong
Common test connection failures
| Issue | Cause | Fix |
|---|---|---|
| Authentication error | Invalid credentials or expired tokens | Verify the secrets in the Secrets section match your provider’s credentials |
| Permission denied | Role or service account lacks required permissions | Check that the IAM role, service account, or service principal has the correct access policies |
| Connection timeout | Network connectivity issue | Verify the platform can reach the provider’s API endpoints (check firewall rules, VPC configuration, or proxy settings) |
| Invalid configuration | Syntax error or missing required field | Check that all required fields are filled in correctly; refer to the integration’s documentation for the expected format |
You can re-run the test after making changes without leaving the page.
Select a destination
Pick a destination from the dropdown. To sync to the CloudQuery default destination, and to use the platform features built on it, leave CloudQuery selected. To sync to a destination you already created, select it here instead.
Configure sync schedule
In the Schedule dropdown, choose Daily, Weekly or Monthly, or choose No schedule to trigger runs manually. Preset schedules run at midnight UTC. The scheduled time is shown below the dropdown.
If you want to run syncs at a different frequency or at a different time, choose Custom and enter a cron expression. The actual frequency and time of the sync will be explained below the input.
After your first sync
Once you create a sync and it completes, verify your data arrived by opening the SQL Console. Run a query against one of the tables your integration syncs, for example:
SELECT count(*) FROM <YOUR_TABLE_NAME>You can find the full list of tables for each integration in the CloudQuery Hub.
Browse your synced resources visually in the Asset Inventory, which provides a unified view across all connected integrations.
Next steps
- Set up a sync to schedule when your data is fetched and to which destinations
- Browse synced resources in the Asset Inventory
- Run advanced queries in the SQL Console
- See provider-specific guides for detailed setup instructions:
Last updated on