General Integration Setup Guide
Prerequisites
- A CloudQuery Platform account with admin access
- At least one destination configured (CloudQuery Platform includes a default ClickHouse destination)
Creating the integration
Go to Data Pipelines → Integrations and click Create 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).
If applicable, fill out the YAML specification. The link to the integration documentation will have more information about the format required.
Most integrations require authentication. Use the Secrets section to store sensitive values as environment variables. Reference them in the YAML configuration using placeholders such as ${MY_SECRET_VALUE}. This keeps credentials out of the YAML spec itself.
Testing your connection
When you’re ready, click Test Connection. 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 YAML | Syntax error in the configuration | Check the YAML for indentation issues or invalid field names — refer to the integration’s documentation linked below the editor |
You can re-run the test after making changes without leaving the page.
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: