VM configuration file
On a Linux VM the connector reads/etc/clicklink/config.yaml, written by clicklink clctl init and kept across re-runs unless --force is passed. Keys omitted from the file fall back to the compiled defaults below. Credentials never live in this file.
Top-level keys
| Key | Default | Meaning |
|---|---|---|
pcm_infra_uuid | minted by init | Unique identifier for this connector deployment, carried on every upstream request. Preserved across re-runs, including --force. Do not edit. |
cloud | detected by init | Cloud provider label for this host. Required; the daemons refuse to start when empty. |
region | detected by init | Region label for this host. Required; the daemons refuse to start when empty. |
api | Upstream API connection block, see api. | |
instances | {} | Map of ClickHouse instances by name, see instances. |
scraper | Scraper daemon block, see scraper. | |
troubleshooter | Troubleshooter daemon block, see troubleshooter. | |
observability | Shared logging and port block, see observability. |
api
| Key | Default | Meaning |
|---|---|---|
api.endpoint | from the enrollment bundle | Your org connector API endpoint, https://<subdomain>.<connector domain>. |
api.access_key_file | /etc/clicklink/access-key (written by init) | File holding the HMAC access key (mode 0600). |
api.secret_key_file | /etc/clicklink/secret-key (written by init) | File holding the HMAC secret key (mode 0600). |
api.tls.enabled | true | Present the mTLS client certificate on API connections. |
api.tls.cert_file | /etc/clicklink/tls/client.crt | mTLS client certificate leaf; rewritten automatically on renewal. |
api.tls.key_file | /etc/clicklink/tls/client.key | mTLS client private key. |
api.tls.ca_file | /etc/clicklink/tls/ca.crt | Extra CA chain added to the system roots for server verification; init installs the enrollment bundle’s chain here. |
api.retry.max_retries | 5 | Retry attempts per API request. |
api.retry.initial_delay | 1s | First retry backoff delay. |
api.retry.max_delay | 30s | Backoff ceiling. |
api.retry.jitter_factor | 0.25 | Random jitter applied to backoff delays. |
instances
Each entry underinstances.<name> describes one ClickHouse native-protocol target:
| Key | Default | Meaning |
|---|---|---|
host | Hostname or IP of the ClickHouse native listener. | |
port | Native protocol port (typically 9440 with TLS, 9000 plaintext). | |
database | Database the connector’s sessions default to. | |
secure | false | Use TLS on the native connection. |
max_open_conns | unset | Cap on open connections to this instance. |
max_idle_conns | unset | Cap on idle pooled connections to this instance. |
namespace | Kubernetes namespace of the instance, used to scope the troubleshooter’s Kubernetes reads. | |
cluster | default | ClickHouse cluster name used for distributed queries. |
scraper
| Key | Default | Meaning |
|---|---|---|
scraper.enabled | false (init writes true) | Run the scraper daemon. |
scraper.labels.platform | Label injected into every emitted metric. Required when the scraper is enabled. | |
scraper.labels.env | Environment label, for example production. Required. | |
scraper.labels.region | Region label. Required. | |
scraper.scrape.interval | 2m | How often each instance is scraped. |
scraper.scrape.timeout | 30s | Per-scrape query timeout. |
scraper.scrape.tables | see below | System tables scraped per instance. The default set is metric_log, asynchronous_metric_log, tables, warnings, server_settings; query_log is deliberately excluded so raw SQL text never leaves your boundary by default. |
scraper.buffer.path | /var/lib/clicklink/buffer | On-disk spool for at-least-once delivery while the API endpoint is unreachable. |
scraper.buffer.retention | 168h | Maximum age of spooled data. |
scraper.buffer.max_size_mb | 1024 | Spool size cap in MB. |
scraper.sender.bandwidth_limit_mb | 1.0 | Upload rate limit in MB/s. |
scraper.observability.health_port | 8082 | Scraper health endpoint port. |
scraper.observability.metrics_port | 9092 | Scraper metrics port. |
scraper.access_directory | /etc/clicklink/access/scraper | Root of the scraper’s per-instance access bundles. |
troubleshooter
| Key | Default | Meaning |
|---|---|---|
troubleshooter.enabled | false (init writes true) | Run the troubleshooter daemon. |
troubleshooter.poll_interval | 5s | Session-state poll interval. |
troubleshooter.command_timeout | 60s | Per-command execution timeout. |
troubleshooter.session_timeout | 4h | Default support-session duration. |
troubleshooter.session_file_path | /var/lib/clicklink/session.json | Session state file, shared with the clicklink clctl troubleshoot session commands. |
troubleshooter.access_directory | /etc/clicklink/access/troubleshooter | Root of the troubleshooter’s per-instance access bundles. |
troubleshooter.allowed_tables | see default table allowlist | System tables the troubleshooter may SELECT from. |
troubleshooter.max_open_conns | 5 | Cap on open ClickHouse connections. |
troubleshooter.max_idle_conns | 5 | Cap on idle pooled connections. |
troubleshooter.redaction.workers | 4 | Parallel redaction workers. |
troubleshooter.redaction.patterns_file | /etc/clicklink/redaction-patterns.yaml | Customer-editable redaction patterns; the daemon refuses to start when the file is present but invalid. |
troubleshooter.redaction.metrics_per_pattern | false | Emit a per-pattern match counter metric. |
troubleshooter.redaction.metrics_per_pattern_cap | 50 | Cap on distinct pattern names in the per-pattern metric. |
troubleshooter.audit_log.path | /var/log/clicklink/troubleshoot-audit.log | Append-only NDJSON audit log of every accepted or blocked command. |
troubleshooter.audit_log.max_size_mb | 128 | Rotate the active log file above this size. |
troubleshooter.audit_log.max_files | 5 | Rotated files kept. |
troubleshooter.audit_log.max_age | 168h | Rotated files older than this are pruned. |
troubleshooter.gateway.enabled | false | Serve the session gateway (support sessions over OIDC). |
troubleshooter.gateway.listen_addr | ":8443" (written by init) | Gateway listen address. |
troubleshooter.gateway.audience | clicklink-clctl (written by init) | Audience claim required on operator tokens. |
troubleshooter.gateway.required_hosted_domain | "" | Optional hosted-domain claim guard; tokens from outside the domain are rejected before the allowlist lookup. |
troubleshooter.gateway.allowed_operators_file | /etc/clicklink/allowed-operators.txt (written by init) | Newline-delimited operator email allowlist. Empty means closed. |
troubleshooter.gateway.rate_limit_per_minute | 0 (disabled) | Per-operator request rate limit. |
troubleshooter.gateway.handler_timeout | unset | Server-side request timeout. |
troubleshooter.gateway.jwks_uri | "" | JWKS endpoint for a non-Google identity provider; empty uses Google’s. |
troubleshooter.gateway.issuer | "" | Issuer claim to pin when jwks_uri is set. |
troubleshooter.gateway.tls.enabled | false (init writes true on a VM when support sessions are enabled) | Serve the gateway over TLS with the self-signed certificate the daemon mints when none exists; operators pin its fingerprint. |
troubleshooter.gateway.tls.cert_file | /var/lib/clicklink/gateway/tls/server.crt | Gateway serving certificate. |
troubleshooter.gateway.tls.key_file | /var/lib/clicklink/gateway/tls/server.key | Gateway serving key. |
troubleshooter.gateway.tls.self_signed_dns_names | [] (init prefills the host) | SANs for the self-signed certificate the daemon mints itself when none exists; entries that parse as IP addresses become IP SANs. |
observability
| Key | Default | Meaning |
|---|---|---|
observability.enabled | true | Serve health and metrics endpoints. |
observability.log_level | info | Log level. |
observability.health_port | 8080 | Shared health port base. |
observability.metrics_port | 9090 | Shared metrics port base. |
observability blocks overlay this base: the scraper uses 8082/9092, the troubleshooter 8084/9094, and the gateway listens on 8443 when enabled.
Default table allowlist
The troubleshooter’s defaultallowed_tables set, identical to the chart’s troubleshooter.allowedTables default:
system.build_options system.clusters system.columns
system.databases system.tables system.parts
system.parts_columns system.parts_summary system.detached_parts
system.processes system.merges system.mutations
system.replicas system.replication_queue
system.metrics system.events system.asynchronous_metrics
system.disks system.storage_policies
system.settings system.settings_profiles
system.settings_profile_elements
system.functions system.formats system.table_engines
system.users system.roles system.grants
Helm chart values
On Kubernetes the connector is configured through theclicklink-connector chart’s values. clicklink clctl init stages a clicklink-values.yaml overlay with everything below filled in and keeps it across re-runs unless --force is passed. The tables list the chart defaults; standard workload knobs (resources, nodeSelector, tolerations, affinity, serviceAccount.annotations, env, imagePullSecrets) exist on each component with empty defaults and are not repeated per table.
cluster
| Key | Default | Meaning |
|---|---|---|
cluster.pcmInfraUuid | "" (init fills it) | Unique identifier for this connector deployment. Required when any component is enabled; preserved across re-runs. |
cluster.region | "" (init fills it) | Region label. Required. |
cluster.cloud | "" (init fills it) | Cloud provider label. Required. |
image
| Key | Default | Meaning |
|---|---|---|
image.repository | pre-set in the published chart | Connector image repository. The published chart points at the public registry image (multi-arch, cosign-signed); set it only to override, for example an in-boundary mirror. Inspect the published value with helm show values. |
image.tag | "" (tracks the chart’s appVersion; init pins the CLI version) | Image tag. |
image.pullPolicy | IfNotPresent | Kubernetes image pull policy. |
api
| Key | Default | Meaning |
|---|---|---|
api.endpoint | "" (init fills it) | Your org connector API endpoint, shared by both components. |
api.tls.enabled | true | Present the mTLS client certificate on API connections. |
api.tls.caFile | "" (system roots) | CA appended to the system roots for server verification. Set to /etc/clicklink/secrets/mtls/ca.crt (or re-run init with --api-private-ca) when the endpoint serves a private-CA certificate. |
secrets
The chart consumes pre-created Secrets;init creates them before install.
| Key | Default | Meaning |
|---|---|---|
secrets.mtlsSecretName | clicklink-mtls | kubernetes.io/tls Secret holding the mTLS client key, certificate, and CA chain. |
secrets.hmacSecretName | clicklink-hmac | Opaque Secret holding the access-key and secret-key for request signing. |
secrets.mtlsWriteback | true | Let the daemons write the automatically renewed mTLS leaf back into the mTLS Secret. Grants the component ServiceAccounts update on that one Secret by exact name; without it, renewed certificates have nowhere durable to land. |
scraper
| Key | Default | Meaning |
|---|---|---|
scraper.enabled | false (init writes true) | Deploy the scraper. |
scraper.replicaCount | 1 | Scraper replicas. |
scraper.logLevel | info | Log level. |
scraper.ports.health | 8082 | Health endpoint port. |
scraper.ports.metrics | 9092 | Metrics port. |
scraper.instances | {} | Map of ClickHouse instances, same shape as the VM instances fields. |
scraper.labels.platform, scraper.labels.env, scraper.labels.region | "" | Labels injected into every emitted metric. All three are required when the scraper is enabled; the chart errors at render time otherwise. |
scraper.config | {} | Passthrough for any scraper config key not modeled above (scrape interval, buffer, sender, and so on, same schema as the VM scraper block). |
scraper.bufferSizeLimit | 2Gi | Size cap of the scraper’s scratch volume; the scraper has no durable on-disk state. |
scraper.rbac.extraSecretNames | [] | Additional Secret names the scraper ServiceAccount may get, exact names only. |
scraper.accessBundles | {} | Per-instance access bundles keyed by instance name, each with secretName and serviceAccountName. Mounted at /etc/clicklink/access/scraper/<instance>/; created by clicklink clctl scraper access provision --target helm. |
troubleshooter
| Key | Default | Meaning |
|---|---|---|
troubleshooter.enabled | false (init writes true) | Deploy the troubleshooter (a single-replica StatefulSet). |
troubleshooter.logLevel | info | Log level. |
troubleshooter.ports.health | 8084 | Health endpoint port. |
troubleshooter.ports.metrics | 9094 | Metrics port. |
troubleshooter.instances | {} | Map of ClickHouse instances, same shape as scraper.instances. |
troubleshooter.sessionTimeout | 4h | Default support-session duration. |
troubleshooter.allowedTables | the default table allowlist | Tables the troubleshooter’s ClickHouse user may SELECT. This is the security review surface to edit in your overlay; a hardcoded denylist (query_log, text_log) applies in the command validator regardless of what is listed here. |
troubleshooter.auditLog.path | /var/log/clicklink/troubleshoot-audit.log | Audit log location, on the state volume so the trail survives pod rescheduling. |
troubleshooter.auditLog.maxSizeMb | 128 | Rotate above this size. |
troubleshooter.auditLog.maxFiles | 5 | Rotated files kept. |
troubleshooter.auditLog.maxAge | 168h | Rotated files older than this are pruned. |
troubleshooter.redaction.workers | 4 | Parallel redaction workers. |
troubleshooter.redaction.patternsConfigMap | "" | Name of a ConfigMap whose redaction-patterns.yaml key holds custom patterns; the chart mounts it at /etc/clicklink/redaction-patterns.yaml. When empty, only the built-in patterns apply. |
troubleshooter.redaction.metricsPerPattern | false | Emit a per-pattern match counter metric. |
troubleshooter.redaction.metricsPerPatternCap | 50 | Cap on distinct pattern names in the per-pattern metric. |
troubleshooter.config | {} | Passthrough for any troubleshooter config key not modeled above (poll interval, command timeout, connection caps, and so on). |
troubleshooter.rbac.extraSecretNames | [] | Additional Secret names the troubleshooter ServiceAccount may get, exact names only. |
troubleshooter.accessBundles | {} | Per-instance access bundles, same shape as scraper.accessBundles, mounted at /etc/clicklink/access/troubleshooter/<instance>/. |
persistence
| Key | Default | Meaning |
|---|---|---|
persistence.enabled | true | Back the troubleshooter’s state directory with a PersistentVolumeClaim so session state and the audit trail survive restarts. |
persistence.storageClass | "" (cluster default) | StorageClass for the claim; init fills it from --storage-class or the detected default. |
persistence.size | 5Gi | Claim size. |
persistence.accessModes | [ReadWriteOnce] | Claim access modes. |
clctl.gateway
The session gateway for support sessions.| Key | Default | Meaning |
|---|---|---|
clctl.gateway.enabled | false | Serve the session gateway inside the troubleshooter. |
clctl.gateway.listenAddr | ":8443" | Pod-local listen address. |
clctl.gateway.port | 8443 | Container port exposed through the troubleshooter Service and Ingress; matches listenAddr’s port. |
clctl.gateway.audience | clicklink-clctl | Audience claim required on operator tokens. The session client defaults to the same value, so the two only need coordinating when you change this. |
clctl.gateway.requiredHostedDomain | "" | Optional hosted-domain claim the gateway requires, rejecting tokens from outside your workspace before the allowlist lookup. |
clctl.gateway.allowedOperators | [] (closed) | Operator email allowlist, rendered into a ConfigMap; rotation is a values change plus helm upgrade. |
clctl.gateway.jwksUri | "" | JWKS endpoint override for non-Google identity providers; empty uses Google’s. |
clctl.gateway.issuer | "" | Issuer claim to pin. Required for any real deployment that sets jwksUri. |
clctl.gateway.jwksEgressCIDRs | [] | CIDRs the gateway needs to reach for JWKS validation under the default-deny NetworkPolicy; empty blocks every token check. |
clctl.gateway.ingressFromSelector | {} | NetworkPolicy ingress source for the gateway port; empty allows any pod in the chart’s namespace. Set it to your Ingress controller’s namespace label when using an Ingress. |
clctl.gateway.rateLimit.requestsPerMinute | 30 | Per-operator request rate limit. |
clctl.gateway.ingress.enabled | false | Render an Ingress for the gateway. When disabled, operators reach the gateway with kubectl port-forward; no ingress controller or cert-manager is needed. |
clctl.gateway.ingress.className, hosts, tls, annotations | "", [], [], {} | Standard Ingress fields; tls references kubernetes.io/tls Secrets. |
networkPolicy
| Key | Default | Meaning |
|---|---|---|
networkPolicy.enabled | true | Emit a default-deny NetworkPolicy with an egress allowlist. Enforcement requires an enforcing CNI. |
networkPolicy.allowEgressCIDRs | [] | CIDRs behind your connector API endpoint. Under an enforcing CNI the connector has no egress until this is filled in. |
networkPolicy.allowEgressPorts | [443] | Ports opened to allowEgressCIDRs; override when the endpoint listens on a non-default port. |
networkPolicy.clickhouseNamespaces | [] | Namespaces of your ClickHouse Services, matched by the kubernetes.io/metadata.name label. Empty allows no in-cluster ClickHouse access. |
networkPolicy.metricsScrapeSelector | {} | Restrict metrics-scrape ingress to a specific Prometheus namespace by label; empty allows scrape from any pod in the chart’s namespace. |
networkPolicy.kubeletProbeCIDRs | [] | CIDRs kubelet health probes originate from (node IPs). Empty allows probe ingress from any source, matching most CNIs’ kubelet exemption; set explicitly under strict default-deny. |
networkPolicy.apiserverCIDRs | [] | Kubernetes API server CIDRs. Empty emits no API server egress rule, and the daemons fail their first token request on managed Kubernetes until it is set. |