FAQ

Frequently asked questions about the ClickHouse Connector

FAQ

Who can change my services, and when?

In managed mode, ClickHouse Cloud changes only the services you asked it to manage. Anyone with access to the executor host or pod can also drive them with local clicklink clctl instances commands; see service lifecycle. ClickHouse Cloud sends lifecycle commands over the executor’s outbound channel:

• create, from the definition you submitted
• scale, to a fixed replica count that ClickHouse Cloud sets (capped by a ClickHouse Cloud setting, 20 in the default configuration)
• stop, start, and restart
• backup and backup deletion
• delete

Version upgrades and configuration changes arrive the same way, as a re-applied service definition; there is no customer approval step for those. A support session is not involved: the executor’s channel is separate from the troubleshooter’s and not gated by session state.

Two things wait for you. Creating a service needs your clicklink clctl executor prepare and clicklink clctl instances create, because only you can create the buckets and the IAM role. Updates to the platform components in your cluster wait too. The executor stages each proposed bundle; your clicklink clctl platform approve approves it and mints a 2-hour token. See platform updates.

Everything the executor does happens through the Kubernetes API. An admission policy confines its writes to namespaces with the service prefix (ns- by default). It also admits three writes in the executor’s own namespace: token renewal, the service registry ConfigMap, and on Kubernetes the renewed client certificate in the clicklink-mtls Secret. Its reads of the same resource families are cluster-wide. Approved platform updates run as a separate pcm-platform identity confined to the platform namespaces. Clusters you operate yourself are never changed: the scraper and troubleshooter are read-only. The exact scopes are on the privilege model page.

What data leaves my environment?

Three surfaces send data out, all over outbound connections the connector opens itself: the scrape path, the executor, and support sessions you enable.

The scraper sends results from a fixed set of system tables: metric_log, asynchronous_metric_log, tables, warnings, and server_settings by default. It also sends health and status heartbeats, service and backup state, and the connector’s own metrics. The default scrape set excludes system.query_log. Raw SQL text, with any literals or personal data inside it, never leaves through the scrape path unless you add that table. During a session, the default table allowlist includes system.processes, which shows live query text; remove it from the allowlist if that must stay hidden.

The executor sends the result of each command it runs and the state and replica counts of each managed service. Its heartbeat reports whether its command channel is connected. It also carries the platform component versions, the digest of the last bundle it applied, and the outcome of the last platform update. On a VM install the heartbeat also reports whether its Kubernetes access bundle is ok, expiring, expired, or absent. When you create a service, clicklink clctl instances create sends your environment ID, cloud and region, the service name, and its bucket names and IAM role ARN. It sends two hashes of the default user’s password; the password itself never leaves.

During an active support session, the troubleshooter also returns command output. That output is bounded to allowlisted ClickHouse tables and read-only Kubernetes views, including pod logs. It passes through redaction (built-in patterns for IPs, credentials, tokens, and keys, plus your own) before it is sent. Your table data, backups, and query history (system.query_log, system.text_log) stay in your environment. Three things do leave:

• rows from the allowlisted metric-history tables (system.metric_log, system.asynchronous_metric_log) ship with every scrape
• live query text is visible in a session through system.processes unless you remove it from the allowlist
• pod logs read during a Kubernetes support session leave after redaction

The complete outbound connection list is on the privilege model page.

How do I stop ClickHouse from changing my clusters?

Run without managed mode. At install time, pass --no-managed to clicklink clctl init, or answer no when it asks. Only the scraper and the troubleshooter are deployed, so ClickHouse cannot create, change, or delete services. The connector still provisions read-only ClickHouse users and ServiceAccounts; see the privilege model.

On an existing install, stop the executor and remove its grant as cluster admin. To stop it, set executor.enabled: false in your Helm values and run helm upgrade, or run systemctl disable --now clicklink-executor on a VM. Then remove the grant. The last command removes the ServiceAccount itself; its namespace is clicklink-system for a VM install and the connector namespace for a Kubernetes install:

kubectl delete validatingadmissionpolicybinding pcm-executor-prefix-guard
kubectl delete validatingadmissionpolicy pcm-executor-prefix-guard
kubectl delete clusterrolebinding pcm-executor-cluster
kubectl delete clusterrole pcm-executor-cluster
kubectl delete serviceaccount pcm-executor -n <executor-namespace>

Services ClickHouse created keep running, but ClickHouse Cloud can no longer scale, upgrade, back up, or delete them, and pending commands for them fail. Platform updates stop too: the executor applies their workload half, and it is no longer running.

What happens if the connector is offline?

Your ClickHouse services are unaffected: the connector sits in no data path, and a managed service keeps running without the executor. The impact is loss of visibility and control. ClickHouse Cloud stops receiving telemetry, and support sessions become unavailable until the connector returns. In managed mode, ClickHouse Cloud shows your environment as offline once no heartbeat has arrived for 5 minutes, and ready again on the next one.

Lifecycle commands behave in two ways while no executor is connected. A create, delete, or platform sync that ClickHouse Cloud already accepted is kept and retried. A create is retried for up to 30 minutes from its last progress report, a delete for up to 2 hours, and a platform sync for up to 10 attempts. After that the command is reported failed. The two horizons are the executor.create_retry_horizon and executor.delete_retry_horizon configuration keys. Every other command (scale, stop, start, restart, backup, backup deletion), and any create or delete submitted while no executor is connected, is refused at submit, not queued. A result the executor could not report is sent on its next connection. See when the connector is offline.

On a VM, the scraper spools scraped data to /var/lib/clicklink/buffer whenever your connector endpoint is unreachable (up to 168 hours or 1024 MB by default). It delivers the spool on reconnect, so an endpoint outage loses no telemetry. A crashed daemon is restarted by systemd on a VM and by the kubelet on Kubernetes. The executor keeps its command state on disk, so a restart resumes commands that were in flight.

To diagnose, check each component’s /livez endpoint (the JSON status field is the signal, not the HTTP code) and run clicklink clctl preflight (with sudo on the VM host). Preflight checks configuration, connectivity, ClickHouse reachability, access, and disk in one pass. See operations; if the connector stays unhealthy, contact ClickHouse Support.

What is deleted when a service is deleted?

The executor stops the service, removes its Kubernetes resources, and deletes its namespace. It reports the service terminated once the namespace is gone. Everything outside Kubernetes stays: the data bucket, the backup bucket, and the service’s IAM role. The executor holds no credentials for your buckets or IAM, so it cannot touch them.

You remove the rest with clicklink clctl executor teardown, run with your credentials. By default it removes the IAM role and keeps the data and the backups; deleting them takes explicit flags. See delete a service.

Where is my default user password?

clicklink clctl executor prepare generates it on your side and prints it exactly once. If you submit with the individual flags instead of --from-prepare, clicklink clctl instances create reads it from --default-user-password-file or mints and prints it. Only its hashes are submitted to ClickHouse Cloud, so neither the connector nor ClickHouse can show it to you again. Store it when it is displayed.

How do I revoke ClickHouse’s access?

In escalating order:

1. End interactive access. Disable the session: sudo clicklink clctl troubleshoot session disable on the VM host, or the same command with --gateway-url through the port-forward on Kubernetes (exact commands on the support sessions page). With no active session the troubleshooter refuses every command, even while connected.
2. Stop managed mode. Stop the executor and remove its grant as described in How do I stop ClickHouse from changing my clusters?. Platform updates already need your approval, so withholding it halts them.
3. Prevent future sessions. Empty the operator allowlist (an empty allowlist closes the gateway) or disable the gateway; on a VM, local session management remains available to root on the host. See the configuration guide.
4. Cut ClickHouse Cloud connectivity. Block egress to your connector endpoint at your network layer, or empty networkPolicy.allowEgressCIDRs under an enforcing CNI. The connector is outbound-only, so ClickHouse Cloud has no inbound path to restore it. Local reads against your ClickHouse continue until you stop or uninstall the workloads, which is the hard stop.
5. Revoke credentials. Drop the pcm_scraper and pcm_troubleshooter ClickHouse users and delete the connector’s Secrets (Kubernetes) or the files under /etc/clicklink (VM).
6. Remove the connector entirely. See operations.

Can I run this air-gapped or through my own mirrors?

Yes. Every install-time artifact can come from inside your boundary:

• Mirror the CLI tarball and container image from releases.clicklink.clickhouse.com and the public registry, then point image.repository at your mirror.
• Pass --chart with an oci:// reference, URL, or local archive. --chart-version defaults to the CLI’s own version.
• If your connector endpoint is served inside your boundary behind a private CA, --api-private-ca (Kubernetes) or api.tls.ca_file (VM) appends the enrollment bundle’s CA chain to the system roots.
• For enrollment without direct connectivity, init --handoff consumes a bundle obtained out of band, and --no-auto-sign plus init --signed-cert completes certificate signing out of band.
• In managed mode, ClickHouse images for your services and platform components can come from your own registry after you import them there; ClickHouse registers that registry for your environment.
• Platform bundles can be handed over out of band and passed to clicklink clctl platform approve --bundle as a file.

See private mirrors and the air-gapped section of onboarding. The connector still needs a route to your connector endpoint at runtime; without one, ClickHouse Cloud receives no telemetry and no lifecycle command reaches the executor.

How are support sessions audited?

Every command executed during a session, accepted or blocked, is appended to /var/log/clicklink/troubleshoot-audit.log as newline-delimited JSON. Each entry records submitted_by (the organization ID on the command channel), the command text, the target instance, the outcome, and blocked_by for rejected commands. Gateway calls, including denied ones, are logged as structured clctl.gateway lines in the troubleshooter’s own log. They are attributed to the token-attested operator email, never a self-reported name. Local session changes on a VM record the invoking host user as enabled_by in /var/lib/clicklink/session.json.

Sessions are time-boxed (4 hours by default, 24 hours maximum). Each enablement records who enabled it, when it expires, and an optional reason, which clicklink clctl troubleshoot session status displays.

Read the audit log with clicklink clctl troubleshoot audit tail. On Kubernetes that command is the supported reader (the runtime image has no shell). With the default persistence.enabled: true, the log lives on the troubleshooter’s persistent volume, so the trail survives pod rescheduling. Disabling persistence makes the audit log and session state pod-lifetime, which the chart marks as suitable for local development only. Rotation keeps 5 files of up to 128 MB for 168 hours by default; see the configuration reference to adjust it, and support sessions for the full trust model.