Skip to main content

​
Components

The ClickHouse Connector runs two daemons, both built into the clicklink binary:
  • The scraper reads an allowlist of ClickHouse system tables on a fixed interval, buffers the results locally, and ships them to your connector endpoint together with infrastructure metadata and health status.
  • The troubleshooter holds an outbound command channel to your connector endpoint and executes read-only diagnostics during an active support session. Outside a session it executes nothing.
On Kubernetes, both run as workloads deployed by the clicklink-connector Helm chart in a namespace you choose (default clicklink). On a Linux VM, they run as the clicklink-scraper and clicklink-troubleshooter systemd units under an unprivileged clicklink system user.

​
Connections

Every connection the connector makes is outbound. The complete list: Every API request carries an Authorization header with an HMAC-SHA256 signature computed over the method, path, timestamp, and a hash of the body, so requests cannot be replayed or altered in transit even inside the TLS channel. Inbound, the connector exposes only local health and metrics ports, plus the opt-in session gateway described on the support sessions page. ClickHouse’s control plane never connects to any of them.

​
Certificate lifecycle

The connector authenticates to your endpoint with a client certificate it obtains and maintains itself:
  • Enrollment. clicklink clctl init generates a private key locally and a certificate signing request with your organization ID as the common name and your endpoint host as the single DNS SAN. The private key never leaves your environment.
  • First issuance. The CSR is submitted to the enrollment signing endpoint at /v1/pcm/cert/sign, authenticated with HMAC. If an unexpired certificate already exists for your organization, the endpoint refuses with a 409 and the CLI prints how to complete with the existing certificate or supersede it deliberately with --force.
  • Automatic renewal. Each daemon checks certificate lifetime every 12 hours and requests a renewed 30-day certificate through /v1/pcm/cert/renew (mTLS plus HMAC) once 10 days remain. On Kubernetes each daemon writes the renewed certificate back to the clicklink-mtls Secret through an exact-name RBAC grant; on a VM the TLS directory is writable by the daemon user. No operator action is needed for renewal.
The connector verifies your endpoint’s server certificate against the system trust store, or against the CA bundle delivered at enrollment when your endpoint uses a private CA.

​
Data flow

​
What leaves your environment

  • Metrics from allowlisted system tables. The scraper’s default set is metric_log, asynchronous_metric_log, tables, warnings, and server_settings. The allowlist is explicit configuration; the scraper reads nothing outside it.
  • Infrastructure metadata. Instance, infrastructure, and backup inventory synced through the API.
  • Health and self-metrics. Component status and the connector’s own operational metrics.
  • Support session output. Results of read-only diagnostics run during a session you enabled, after redaction.

​
What never leaves by default

  • Raw query text, on the scrape path. system.query_log is deliberately excluded from the default scrape set because its query columns can carry literal values, and with them PII or secrets; re-adding it is a per-deployment override you make knowingly. During a support session the default table allowlist does include system.processes, which shows the text of live queries; see support sessions for trimming it.
  • Credentials. Configuration files hold no credentials, ClickHouse stores only bcrypt hashes of the connector users’ passwords, and secrets stay in Kubernetes Secrets or root-readable files on the host. Nothing in the scrape or sync paths transmits them.
  • Unredacted troubleshooter output. Everything the troubleshooter returns passes through redaction patterns (built-in plus your own) before it leaves. See support sessions.

​
Trust boundaries

  • Your environment is the boundary. ClickHouse Cloud receives only what the scraper ships and what an active support session returns. It never initiates a connection inward.
  • The session gateway is yours. It is reachable only inside your environment (over kubectl port-forward on Kubernetes, or locally on a VM) unless you opt into exposing it through an Ingress. ClickHouse’s control plane never connects to it.
  • ClickHouse access is read-only. The pcm_scraper and pcm_troubleshooter users hold per-table SELECT grants, plus one scraper-only system grant that flushes log tables to disk and nothing else; no INSERT, DDL, or user-management grants exist. The exact listing is in the privilege model.
  • Kubernetes access is namespace-scoped. All RBAC is granted through Roles in the connector and instance namespaces, with read-only verbs on workload resources and exact-name access to the connector’s own Secrets. There is no exec, delete, or patch permission.
  • Network policy. On Kubernetes the chart can render a NetworkPolicy that denies all connector egress except the CIDRs you list. Enforcement depends on your cluster running an enforcing CNI; without one the policy is inert. See configuration.
  • Host hardening on VMs. The units run as a non-login system user with ProtectSystem=strict, NoNewPrivileges, read-only configuration paths, and FIPS mode enabled.
For the connector’s exact grants and RBAC rules, see the privilege model reference. If ClickHouse operates the clusters for you instead, the trust model is different; see the BYOC architecture and BYOC privilege pages.
Last modified on August 18, 2026