Skip to main content

​
Components

The ClickHouse Connector runs three daemons, all built into the clicklink binary:
  • The executor holds an outbound command channel to your connector endpoint and applies the lifecycle commands ClickHouse Cloud sends for the services it manages in your cluster. The commands are create, scale, stop and start, restart, backup and backup deletion, delete, and platform updates you have approved. Every action is a Kubernetes API call. It opens no connection to ClickHouse and holds no credentials to your buckets or IAM. It runs only in managed mode.
  • The scraper reads an allowlist of ClickHouse system tables on a fixed interval and buffers the results locally. It ships them to your connector endpoint with infrastructure metadata and health status.
  • The troubleshooter holds an outbound command channel to your connector endpoint and runs read-only diagnostics during an active support session. Outside a session it runs nothing.
On Kubernetes, the clicklink-connector Helm chart deploys the daemons in a namespace you choose (default clicklink). The executor is a single-replica Deployment that keeps its command state on a persistent volume. On a Linux VM, the daemons run as the clicklink-scraper, clicklink-troubleshooter, and clicklink-executor 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 over the method, path, timestamp, and a hash of the body. Requests cannot be replayed or altered in transit, even inside the TLS channel. Inbound, each daemon exposes one local health port: 8082 for the scraper, 8084 for the troubleshooter, 8086 for the executor. That port serves /livez, /readyz, /healthz, and the daemon’s Prometheus metrics at /metrics; there is no separate metrics port. The executor’s local command API binds to loopback only, and no Service exposes it. The only other listener is the opt-in session gateway; see support sessions. ClickHouse Cloud never connects to any of them.

​
Certificate lifecycle

The connector authenticates to your endpoint with a client certificate it obtains and maintains itself. All three daemons present the same certificate.
  • Enrollment. clicklink clctl init generates a private key and a certificate signing request locally. The CSR carries 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. init submits the CSR 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. The CLI then prints how to complete with the existing certificate or supersede it with --force.
  • Automatic renewal. All three daemons check the certificate lifetime every 12 hours. Once 10 days remain, they request a renewed 30-day certificate through /v1/pcm/cert/renew (mTLS plus HMAC). On Kubernetes the renewed certificate is written back to the clicklink-mtls Secret through an exact-name RBAC grant; on a VM each daemon writes it to /etc/clicklink/tls. Renewal needs no operator action.
The connector verifies your endpoint’s server certificate against the system trust store. When api.tls.ca_file (VM) or api.tls.caFile (Helm) is set, the CA chain from your enrollment bundle is appended to those roots.

​
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. Service, infrastructure, and backup inventory synced through the API. For a managed service this is its state, current and expected replica counts, and the running server version and configuration version.
  • Health and self-metrics. Component status and the connector’s own operational metrics. The executor’s heartbeat also reports whether its command channel is connected. It carries the outcome of the last platform update, the platform component versions, and the digest of the last bundle it applied. On a VM install it adds whether its Kubernetes access bundle is ok, expiring, expired, or absent.
  • Command results. For each lifecycle command the executor runs: progress while it converges, then success or failure with the error text on failure.
  • Service definitions you submit. clicklink clctl instances create sends your environment ID, cloud and region, the service name, its bucket names and IAM role ARN, and an idempotency key. It also sends two hashes of the default user’s password (SHA-256 and double SHA-1).
  • 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 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. The default session table allowlist does include system.processes, which shows the text of live queries; see support sessions for trimming it.
  • Your table data and backups. They stay in buckets in your account. The executor holds no credentials to your buckets and cannot read them.
  • Credentials. init writes no credentials into configuration files. ClickHouse stores only bcrypt hashes of the connector users’ passwords, and secrets stay in Kubernetes Secrets or root-readable files on the host. The default user password of a managed service is generated on your side and shown once; only its hashes are submitted. Nothing in the scrape or sync paths transmits a credential.
  • 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 connector sends: scrapes, heartbeats and status, command results, 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 Cloud never connects to it.
  • ClickHouse access is read-only. The pcm_scraper and pcm_troubleshooter users hold per-table SELECT grants, the scraper’s READ ON REMOTE (needed for clusterAllReplicas()), and one scraper-only SYSTEM FLUSH LOGS grant. No INSERT, DDL, or user-management grants exist. The executor has no ClickHouse user. The exact listing is in the privilege model.
  • The scraper and troubleshooter cannot change your cluster. Their RBAC comes from Roles in the connector and service namespaces. Those Roles grant read-only verbs on workload resources and exact-name access to the connector’s own Secrets. There is no exec, delete, or patch permission.
  • The executor changes cluster state in service namespaces as pcm-executor. It creates and deletes namespaces carrying the service prefix (ns- by default) and deletes pods to restart them. Inside those namespaces it writes the ClickHouseCluster, Backup, and ScalingOverride objects and the Secrets, ServiceAccounts, and Services a service needs. It also writes the Role and RoleBinding that give the scraper read access. A ValidatingAdmissionPolicy denies any write from that ServiceAccount outside the prefix. The exceptions, all in its home namespace, are its own token renewal, the clicklink-instance-registry ConfigMap, and, on Kubernetes, the renewed client certificate in the mTLS Secret. The policy fails closed when it cannot be evaluated. Admission does not run on reads, so its reads of those resource families are not confined by prefix.
  • The executor changes platform namespaces only as pcm-platform, during an update you approved. clicklink clctl platform approve mints that identity’s token for 2 hours; it is never renewed. With it the executor may write only Deployments, Services, ConfigMaps, Secrets, Jobs, and PodDisruptionBudgets. Namespaces, CRDs, ServiceAccounts, RBAC, webhook and admission configurations, PriorityClasses, and the StorageClass are applied with your credentials during approval. See platform updates.
  • The executor holds no credentials to your buckets or IAM. clicklink clctl executor prepare creates a service’s data and backup buckets and its IAM role. clicklink clctl executor teardown removes them. Both run with your credentials. The role trusts only that service’s pods, so neither the executor nor ClickHouse can assume it. Its only cloud calls go to Amazon ECR and STS. It logs in to the registry when a platform sync or create pulls a chart. During a platform update it checks the images under the read-only pull role.
  • Network policy. On Kubernetes the chart renders a default-deny NetworkPolicy for each daemon. Egress is allowed only to DNS, the CIDRs you list for your connector endpoint, and the Kubernetes API server CIDRs. The scraper and troubleshooter policies also allow the ClickHouse Services in namespaces the executor manages (selected by the label it stamps on them) or that you list by name. The executor’s policy has no ClickHouse rule. If a platform bundle’s charts live in Amazon ECR, add the ECR and STS ranges (or your registry mirror) to allowEgressCIDRs. Without them the sync cannot pull the charts under an enforcing CNI. Without an enforcing CNI 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 provisions and operates the cluster itself, the trust model differs; see the BYOC architecture and BYOC privilege pages.
Last modified on September 22, 2026