ClickHouse

ClickHouse Cloud connects with an API key created in your organization settings. An API key belongs to exactly one organization, so one key connects one organization, and each organization connects to a workspace once. Keys are encrypted before they are stored, and the agent never sees them.

1. Open ClickHouse Cloud, go to your organization's API Keys.
2. Click New API key and choose the Developer (read-only) role: Polylane only reads during sync.
3. Copy both the key ID and the key secret; the secret is shown only once.
4. Paste both values into Polylane.
5. Polylane validates the key and starts syncing.

Polylane discovers your services, including state, tier, region, cloud provider, ClickHouse version, replica sizing, and connection endpoints. Connection hostnames are used for cross-cloud linking, so applications that reach a service through an environment variable link to it on the map.

Monitoring raises an issue when services sit degraded, failed, stopped, or partially running; idle and waking services are ordinary lifecycle for idle-scaled services and stay healthy. The ClickHouse Cloud control plane reports metrics as a live snapshot with no history, so agents read current values on demand and services carry no metric charts.

Troubleshooting

"Invalid API key" error

• Both the key ID and the key secret are required; either one alone cannot authenticate.
• Check that the key has not been deleted or disabled in ClickHouse Cloud's API key settings.
• Keys with an expiry stop working when they expire; create a fresh key and rotate it in Polylane.

Missing resources

• ClickHouse Cloud can take a few minutes to sync everything.
• Trigger a manual Sync from the account header to refresh.

Rate limits

• ClickHouse Cloud allows 10 API requests per 10 seconds per key. A dedicated key for Polylane avoids sharing that budget with other tooling.

Disconnecting

Disconnect the account in Polylane, then delete the API key from your ClickHouse Cloud organization settings.

Connecting ClickHouse Cloud needs no browser: the same endpoint the console calls fits in a CI job. One authenticated POST creates the connection and starts the first sync.

Prerequisites

• A Polylane API key with the cloud_accounts:write and cloud_accounts:read scopes. See API keys and OAuth.
• Your workspace ID, which starts with ws_. Read it from GET /v1/workspaces with the same key.
• A ClickHouse Cloud API key ID and secret from your organization's API Keys, created with the Developer (read-only) role.

Create the connection

curl -X POST https://api.polylane.com/v1/cloud_accounts \
  -H "x-api-key: $POLYLANE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "clickhouse",
    "workspaceId": "ws_0abc123",
    "keyId": "<key-id>",
    "keySecret": "<key-secret>"
  }'

An API key belongs to exactly one organization, so one call connects one organization.

The response lists what was connected, with the first sync already running. Trimmed to the two fields the rest of the flow reads:

{
  "success": true,
  "result": {
    "provider": "clickhouse",
    "accounts": [{ "id": "acc_34gky74ibc92h8t2efn8csrh", "status": "syncing" }],
    "failures": []
  }
}

An account that is already connected lands in failures instead of accounts, so repeating the call never duplicates a connection.

Wait for the first sync

Poll each returned account by its id until status reaches ready (new on registration, syncing while resources stream in):

until [ "$(curl -s "https://api.polylane.com/v1/cloud_accounts/$WORKSPACE_ID/$ACCOUNT_ID" \
  -H "x-api-key: $POLYLANE_API_KEY" | jq -r '.result.status')" = "ready" ]; do
  sleep 15
done

Give the loop a deadline so a failed connect fails the job instead of hanging it. Once the account is ready, its resources are in the topology and Polylane has started its first check.

Disconnect from the API

Deleting the connection stops every sync and check and deletes the credentials Polylane held. The call needs the cloud_accounts:delete scope:

curl -X DELETE "https://api.polylane.com/v1/cloud_accounts/$WORKSPACE_ID/$ACCOUNT_ID" \
  -H "x-api-key: $POLYLANE_API_KEY"

Then revoke the ClickHouse Cloud credential on the provider side, as described under Disconnect below.