Skip to main content
This page covers the configuration changes you are most likely to make after installing the connector. Every key, with its default and meaning, is in the configuration reference; command flags are in the CLI reference. Creating, scaling, and deleting services is covered in managed services.

​
Configuration surfaces

The connector has one configuration surface per install target.
clicklink clctl init stages a values overlay named clicklink-values.yaml in the working directory and deploys the clicklink-connector chart with it. The overlay is the durable record of your deployment: re-running init keeps it unless you pass --force, so your edits survive re-runs and recovery.
Day-2 commands on this page and in operations use the helm CLI. Only init carries a built-in Helm client.
Edit the overlay, then apply it:
The block reapplies your edited values at the chart version already installed, so a configuration change never doubles as an unplanned upgrade. Moving to a new version is a separate step; see operations. On a mirrored install that uses a chart repository, swap --repo for your mirror.An install from a direct chart reference (oci://, a URL, or a local archive or directory, see private mirrors) has no repository to resolve against. Rerun the upgrade with the reference you installed from:

​
Managed mode

Managed mode runs the executor, which applies the service lifecycle ClickHouse Cloud drives to your cluster. init turns it on at enrollment and fills in the cluster identity (see enable managed mode). The keys below are the ones you might revisit afterwards. To change the posture, re-run init with --force and --managed or --no-managed. Like every init run, this needs an entry point: --handoff if you kept the bundle, or --enroll with a fresh token (see re-runs and recovery). On a VM, --no-managed disables the executor in the configuration but does not stop or disable a running systemd unit. Stop it before changing the configuration:
On Kubernetes, set executor.enabled: false in the values and apply it with helm upgrade to remove the executor Deployment. On both targets the cluster grant remains until you remove it; see stop managed mode.
init stages the executor block in clicklink-values.yaml from the EKS cluster your kube context points at:
  • cluster.namespacePrefix is shared by every component and is the prefix the executor’s grant confines it to. Changing it after install means re-running the grant.
  • executor.cluster is exactly one cluster: name, region, accountId, and inCluster: true, which makes the executor authenticate as the pod’s ServiceAccount. Other keys pass through to the executor verbatim in snake_case, such as s3_storage.
  • executor.serviceAccount stays create: false: init grants cluster-wide access to the pcm-executor ServiceAccount in the connector namespace, and the chart binds to it rather than minting an unbound one.
  • executor.persistence backs /var/lib/clicklink, where the executor keeps its command database and service registry; see storage.
  • executor.platformBundleSecret names the Secret that holds an approved platform update. The mount is optional, so the pod starts before the first approval; see approve a platform update.
  • executor.ports.health serves /livez and /metrics; there is no separate metrics port on any component.
Apply changes with the helm upgrade shown in configuration surfaces.

​
Adding or changing ClickHouse instances

Services the executor creates register themselves, so in managed mode you never add them here. This section applies to a separate connector deployment running without the executor, which observes ClickHouse you run yourself. Pass --ch-user-suffix at its init when the two deployments share an instance. Each entry under instances names a ClickHouse native-protocol endpoint the connector reads from: host, port, database, secure, cluster, and on Kubernetes namespace. max_open_conns and max_idle_conns cap the connection pool. Credentials never live in the configuration; each component resolves its read-only ClickHouse user from the access bundle provisioning creates.
Add the instance to the top-level instances map in clicklink-values.yaml (the same fields as the VM registry). Add its namespace to networkPolicy.clickhouseNamespaces, matched by the namespace’s kubernetes.io/metadata.name label. The chart renders the map into the clicklink-instance-registry ConfigMap that both daemons read. This works only while executor.enabled is false; with the executor on, the render fails because the executor owns that ConfigMap.
Provision read-only access for each component from your workstation. --apply-ch-grants applies the generated ClickHouse grants in-pod via kubectl exec; without it the command creates the Kubernetes side only and leaves ch-grants.sql on disk for you to apply. When the admin user has a password, add --ch-admin-password-stdin and pipe it in.
For an operator-managed instance with no SQL-capable admin, swap --apply-ch-grants for --ch-user-via cr (the pod-selection flags stay); see the CLI reference. Then wire the Secret and ServiceAccount pair each command creates into the matching accessBundles map and run the helm upgrade shown above:
The same access provision commands with --force rotate an instance’s ClickHouse credentials. See operations.

​
Operator allowlist

An allowlist of operator email addresses gates gateway-managed sessions. Every request to the session gateway must carry a short-lived OIDC ID token whose attested email is on the list. An empty allowlist closes the gateway. On a VM, root on the host can also manage sessions directly through the local session file; the allowlist governs the gateway path only. See support sessions for the full trust model.
The allowlist lives in the overlay, and the chart renders it into a ConfigMap. To change it, edit the list and run helm upgrade:

​
Network policy and egress

On Kubernetes the chart ships a default-deny NetworkPolicy with an egress allowlist. NetworkPolicy objects take effect only when your CNI enforces them. Under an enforcing CNI, only cluster DNS and the ClickHouse Service namespaces are reachable until both CIDR lists are filled in. The connector has no egress to your connector endpoint or the Kubernetes API server before then. init stages the policy enabled only when it knows the CIDRs behind your connector endpoint.
The two CIDR lists come from different places:
  • allowEgressCIDRs is yours to supply: the ranges behind your connector endpoint, given at install with --egress-cidrs or at the prompt. Every component needs them to reach your connector endpoint. In managed mode, when the platform charts live in Amazon ECR, add the ECR and STS ranges for your region (or your mirror’s range). Without them the executor’s chart pulls fail under the policy.
  • apiserverCIDRs is derived by init in managed mode from the EKS cluster’s VPC (eks:DescribeCluster and ec2:DescribeVpcs). Every component issues Kubernetes token requests and the executor drives services through the API, so under an enforcing CNI all of them are blocked until it is set. If the lookup fails, init warns and leaves the list empty for you to fill in with your VPC’s CIDR blocks.
Service namespaces are selected two ways. Namespaces the executor creates carry the label clicklink.clickhouse.com/managed-by: executor, and the policy admits them by that label, so a managed install can leave clickhouseNamespaces empty. Only namespaces created outside the executor, for ClickHouse you run yourself, need listing by name. Enable the policy later. When you skipped the endpoint CIDRs at install, init staged enabled: false with allowEgressCIDRs: [] and printed the step to finish it. Once you know the CIDRs, set enabled: true and allowEgressCIDRs in clicklink-values.yaml, confirm apiserverCIDRs holds your VPC’s ranges, and run the helm upgrade shown in configuration surfaces. When the session gateway is enabled, one more egress rule matters: clctl.gateway.jwksEgressCIDRs. The troubleshooter fetches your identity provider’s JWKS to validate operator tokens, so under default-deny an empty list blocks every token check:
The example is the private.googleapis.com range, which covers a Google identity provider reached over Private Google Access. For any other identity provider, supply its range, or the CIDR of the egress proxy that fronts it. Two ingress keys remain: metricsScrapeSelector restricts metrics-scrape ingress to one Prometheus namespace by label, and kubeletProbeCIDRs admits kubelet health probes explicitly under strict default-deny. See the configuration reference for the full key list.

​
Redaction patterns

The troubleshooter redacts its output before it leaves your boundary. Built-in patterns cover ipv4, ipv6, bearer-token, aws-access-key, email, jwt, ssh-private-key, and connection-string-credentials. Add your own patterns in a YAML file. They run first, in file order, then the built-ins; an entry that reuses a built-in’s name replaces it. Each pattern takes name (required, unique), regex (required, Go RE2 syntax), replace (default [REDACTED], supports $1 capture references), and case_insensitive (default false):
On a VM the file is /etc/clicklink/redaction-patterns.yaml. The installer seeds it with a starter set of active patterns (third-party API keys, AWS secret keys, and so on). Trim or extend the set; the installer preserves your version across upgrades. On Kubernetes, put the YAML in a ConfigMap under the key redaction-patterns.yaml and set troubleshooter.redaction.patternsConfigMap to its name; the chart mounts it at the same path.
The troubleshooter refuses to start when a patterns file is present but invalid, and logs the offending entry. A configured but missing file only logs a warning and uses the built-ins. clicklink clctl preflight validates the file, so run it before restarting the daemon.

​
Private mirrors and in-boundary endpoints

The published chart pre-sets image.repository to the public, multi-arch, cosign-signed connector image, so plain installs need no image values. To inspect the published defaults:
To pull through your own registry, override the repository in the overlay:
To install the chart itself from a mirror, init accepts --chart as a chart name resolved in --chart-repo, or as a direct oci:// reference, URL, or local archive or directory. --chart-version defaults to the CLI’s own version so the binary and chart move together.
When your connector endpoint sits behind a private CA inside your boundary, pass --api-private-ca to init. It stages api.tls.caFile: /etc/clicklink/secrets/mtls/ca.crt, and the connector verifies the endpoint against the system roots plus the CA chain from your enrollment bundle. On a VM the equivalent is api.tls.ca_file in /etc/clicklink/config.yaml: init installs the bundle chain at /etc/clicklink/tls/ca.crt, and the connector appends it to the system roots the same way. For fully air-gapped enrollment and certificate signing, see onboarding.

​
Storage

Two components keep state on PersistentVolumeClaims. The troubleshooter’s holds session state and the audit trail:
The executor’s holds its command database and the registry of the services it manages:
init sets both storageClass values to the class you chose. An empty storageClass uses the cluster’s default StorageClass; when the cluster marks no default, init requires one via the prompt or --storage-class. The executor’s claim is annotated helm.sh/resource-policy: keep, so helm uninstall leaves it in place; see uninstall.
Last modified on September 22, 2026