Connecting to ClickHouse
Connect your ClickHouse Cloud account to CloudZero to bring your ClickHouse cost and usage data into a unified view of all your cloud and AI spend. CloudZero organizes your ClickHouse costs, along with your other costs, into categories (called Dimensions) that matter most to your business. For example: business unit, team, product, feature, environment, customer, or virtually anything else. Once connected and organized, you can quickly answer questions about your spend that matter to your stakeholders.
This guide covers creating a ClickHouse Cloud API key and configuring the connection in CloudZero. CloudZero ingests daily organization-level cost data along with service and ClickPipes metadata. CloudZero only reads your ClickHouse data and never modifies it.
ClickHouse reports costs in ClickHouse Credits (CHC). One CHC is equivalent to one US dollar.
What you need
- CloudZero user with data configuration permissions
- A ClickHouse Cloud account with permissions to create API keys
Step 1: Copy your Organization ID
- Sign in to ClickHouse Cloud.
- In the bottom-left of the console, open your Organization and select Organization Details.
- Copy the Organization ID.
Step 2: Create an API key in ClickHouse
For full details, see ClickHouse's API key documentation.
- In the ClickHouse Cloud console, go to Settings > API keys.
- Select New API Key.
- Enter a descriptive name (for example, "CloudZero Integration") in API key name.
- Set an Expiration date that matches your security policy.
- From the Roles list, select the roles this key needs. To see what a role grants, hover over the permissions link below its name (for example, 21 permissions).
| You need | Roles |
|---|---|
| Cost data and tags | Service API Reader. Roles without service access, including Member and Billing, return no services even though they reach your cost data, so your ClickHouse tags are not ingested. |
| ClickPipes metadata | Add a role that includes the View and manage ClickPipes permission. Service API Admin includes it; Service API Reader does not. |
- Select Generate API Key.
- Copy the Key ID and Key Secret immediately. ClickHouse displays the Key Secret only once.
ClickHouse does not offer a view-only ClickPipes permission. Its console permissions reference lists only
control-plane:service:manage-clickpipes, so granting View and manage ClickPipes also allows creating and deleting ClickPipes. CloudZero only reads this data.
Step 3: Configure the connection in CloudZero
- In CloudZero, go to Settings > Cloud Connections.
- Select Create Connection + and select the ClickHouse tile.
- Enter the connection details:
- Select Create Connection.
What to expect
After you connect, CloudZero begins ingesting your ClickHouse cost data. Your ClickHouse costs appear across the platform within 24 hours. Once data is available, you can view costs broken down by service, data warehouse, ClickPipe, region, cloud provider, cost metric (compute, storage, backup, data transfer, and others), and tags.
From there, your ClickHouse costs work like any other cost data in CloudZero. For example, you can organize them by team or product using Dimensions, track trends in Dashboards, set Budgets, or ask questions in the AI Hub.
If the connection shows an error and no cost data appears, check the API key's ClickPipes permission. A key without View and manage ClickPipes connects successfully, but CloudZero cannot ingest cost data for a service that uses ClickPipes. To resolve this, create a key with a role that includes the permission and update the connection to use it.
Connection details
Tags
CloudZero ingests any tags you have set on your ClickHouse Cloud services. Tags appear with your original key names (for example, environment, team, project) and are available for use in Dimensions. New keys are picked up automatically at each ingestion.
Tag ingestion depends on the API key being able to read your services, so the key needs the Service API Reader role described in Step 2.
Tags are set through the ClickHouse Cloud API or the ClickHouse Terraform provider.
Have questions or feedback? Reach out to your account manager.
Updated 17 days ago