Skip to main content
This page takes you from an enrollment token to a verified connector in managed mode, where the executor applies the service lifecycle ClickHouse Cloud drives. The connector installs on a Kubernetes cluster (Helm) or a Linux VM (systemd). Token enrollment is the standard flow. When your environment cannot reach your connector endpoint directly, see air-gapped and mirrored installs. To observe ClickHouse you run yourself, without the executor, pass --no-managed.

​
Prerequisites

​
Register your environment

Before you enroll, your account team registers your environment and enables managed mode for your organization. Give them:
  • your AWS account id, region, and EKS cluster name
  • whether the connector runs on a Linux VM or in the cluster
  • the node group for platform components
  • the namespace prefix for services (default ns-)
  • how your cluster pulls ClickHouse images: through the registry access ClickHouse Cloud sets up for your account, or your own mirror
ClickHouse Cloud then issues your connector endpoint and a single-use enrollment token. The token identifies your environment, so enrollment needs no extra id.

​
For every install

  • Connector v0.17.0 or later. Earlier releases have no managed mode, platform commands, or instances create. The installer serves the latest release unless you pass --version.
  • Your connector endpoint and enrollment token, provided during registration.
  • Egress on port 443 to https://<subdomain>.<connector-domain> and https://<subdomain>.enroll.<connector-domain>, plus releases.clicklink.clickhouse.com and Amazon ECR Public at install time. In managed mode the executor also reaches Amazon ECR and STS when a platform sync or create pulls a chart from ECR. If any of these is unreachable, see air-gapped and mirrored installs.
  • An Amazon EKS cluster for managed mode. init refuses managed mode on any other cluster and points to --no-managed for an install without the executor.
  • Cluster admin for the executor’s grant. The grant creates a ClusterRole, a ClusterRoleBinding, and a ValidatingAdmissionPolicy that confines the executor to namespaces under your prefix. On Kubernetes, the kubeconfig you run init with needs it. On a VM, the host’s kubeconfig needs it; when the host has no admin, init prints the command to run from a host that does.
  • No ClickHouse yet. A managed install starts with no services; the ones the executor creates register themselves. In managed mode init registers no ClickHouse you run yourself (on Kubernetes it refuses --instance and --instance-namespace). To observe such a cluster, install a separate connector deployment with --no-managed. --ch-user-suffix lets the two deployments share an instance without colliding on the connector’s users. That deployment needs a reachable native listener, secure 9440 or plaintext 9000, auto-detected on Kubernetes. It also needs ClickHouse admin access for provisioning: a passwordless default user, a password passed with --ch-admin-password-stdin or at the prompt, or CR injection for operator-managed instances.
  • cosign wherever you download release artifacts. The installer always verifies the SHA-256 checksum. With cosign installed it also verifies the release signature, and with CLICKLINK_REQUIRE_COSIGN=1 it refuses to proceed without cosign.

​
For Kubernetes (Helm) installs

  • A kubeconfig whose current context points at the EKS cluster. It must be able to create and read the connector namespace, apply Secrets, create ServiceAccounts, Roles, and RoleBindings, install the chart, and grant the executor its cluster-wide access.
  • AWS credentials on the workstation (environment or profile) with eks:DescribeCluster and ec2:DescribeVpcs. init uses them to read your cluster VPC’s CIDR blocks for the NetworkPolicy. If the lookup fails, it warns and leaves that list for you to fill in.
  • The CIDRs behind your connector endpoint, to enable the chart’s default-deny NetworkPolicy at install time. Without them, init stages the policy disabled and prints how to enable it later.
  • A default StorageClass, or a class to pass with --storage-class; the troubleshooter and the executor keep state on PersistentVolumeClaims.
  • Image pull access: cluster nodes must be able to pull the public ECR image, or a mirror you host.

​
For Linux VM (systemd) installs

  • Any systemd Linux host, amd64 or arm64. Linux builds run in FIPS mode.
  • Root access for the installer and for init.
  • Free ports 8082, 8084, and 8086 for health and metrics, 9999 on the loopback interface for the executor’s local API, and 8443 when the support-session gateway is enabled.
  • Admin access to the Kubernetes API server for provisioning and the executor’s grant: a kubeconfig on the host, --server and --ca-data, or the prompts. Access bundles are anchored to Kubernetes ServiceAccounts on both targets. In managed mode the kubeconfig’s current context must point at the EKS cluster you manage; init refuses to grant through any other context.
On a VM, --skip-provision is the only way around the Kubernetes API server requirement, and it is stage-only. It skips ClickHouse user provisioning, the executor’s grant, the unit enable, and verification, so it produces no running connector by itself. On Kubernetes it skips ClickHouse user provisioning only. The executor’s grant is still applied, because the chart’s executor cannot schedule without the granted ServiceAccount.

​
Install and enroll

1

Get your connector endpoint and enrollment token

Both come from your account team once your environment is registered. The endpoint has the form:
The token is single-use and expires quickly, so enroll soon after you receive it. Treat it as a secret: the CLI reads it from a hidden prompt or the first line of stdin, never from command-line arguments, disk, or logs. If it expires before you enroll, ask your account team for a fresh one.
2

Install and verify the CLI

One command installs a verified clicklink binary. It detects your platform (macOS or Linux, amd64 or arm64), downloads the current release, and verifies the SHA-256 checksum. With cosign installed it also verifies the release signature. It installs into /usr/local/bin when that is writable, otherwise into ~/.local/bin (add that to your PATH if needed; --bin-dir overrides). For a Kubernetes install, run it on any workstation with kubeconfig access to the cluster:
For a VM install, run the same script on the host with --host. After the verified download it creates the clicklink system user, the /etc/clicklink, /var/lib/clicklink, and /var/log/clicklink directories, and the systemd units for all three components. It seeds /etc/clicklink/redaction-patterns.yaml with a starter set of patterns (an existing file is preserved), so the next step is enrollment:
Both forms accept --version vX.Y.Z to pin a release. Re-running either is safe: the host install backs up the previous binary and preserves your live configuration. To inspect the script before running it, or to fetch and verify the release tarball yourself, see manual download and verification.
3

Enroll and install the connector

init --enroll redeems your token, obtains a signed client certificate and the executor’s cluster-wide grant, then installs and verifies the connector.On a terminal, init asks Enable managed mode (ClickHouse manages the lifecycle of ClickHouse services in this cluster)? with yes preselected. Pass --managed to skip the prompt, or --no-managed for an observe-only install without the executor. An unattended fresh install with neither flag leaves managed mode off (a --force re-run keeps the replaced configuration’s posture), so always pass --managed in scripts.
From your workstation, with the kube context pointed at your EKS cluster, run:
Paste the enrollment token at the hidden prompt. init reads the cluster’s name, region, and AWS account from the current context’s EKS ARN, so you type nothing about the cluster. It then prompts for:
  • the connector namespace (default clicklink)
  • a StorageClass, only when the cluster marks no default
  • the CIDRs behind your connector endpoint, for the NetworkPolicy egress allowlist (leave empty to stage the policy disabled)
  • the support-session posture and, if enabled, the operator email allowlist
init redeems the token and saves the enrollment bundle as handoff.yaml in the working directory. It stages the Helm values overlay clicklink-values.yaml with the executor block and your cluster VPC’s ranges as the NetworkPolicy’s API server CIDRs. It creates the namespace, applies the clicklink-hmac Secret, generates the private key inside the clicklink-mtls Secret, and writes the CSR. It grants the executor’s cluster-wide access into the connector namespace and has ClickHouse Cloud sign the client certificate. It installs the clicklink-connector Helm release with its built-in Helm client (no helm binary required) and verifies health.For unattended runs, answer the prompts with flags instead. Use the saved bundle as the entry point, or pipe the enrollment token to --enroll as the first line of stdin:
Pass --no-gateway instead of --operators to disable support sessions; the two flags are mutually exclusive.
When the install verifies, init prints Managed mode is on with the command that prepares your first service. Continue with create a service.
4

Verify success

init verifies the install before it reports success. On Kubernetes it polls the /livez endpoint of each enabled component, the executor included, for up to five minutes. When the support-session gateway is enabled, it also requires the gateway to answer unauthenticated probes with 401. On a VM it waits for each daemon’s /livez, then runs the full preflight suite. The suite checks config, files, port conflicts, network reachability, ClickHouse connectivity, systemd unit state for all three units, per-component access, disk, and redaction patterns.To confirm by hand on Kubernetes:
All connector pods should be Running and ready: the scraper, the troubleshooter, and the executor.To confirm by hand on a VM:
It exits 0 when every check passes and 2 on any failure, and prints the failing checks.
5

Clean up

The enrollment bundle handoff.yaml (mode 0600, in the working directory) lets re-runs and recovery during the install proceed without a second token. It holds the connector’s API secret in plaintext, so delete it once the install has verified:
The running connector holds its own copy of the credentials; upgrades and configuration changes never need the file. If you need init again later, request a fresh enrollment token from your account team and run init --enroll --force.

​
Air-gapped and mirrored installs

Two independent pieces can move out of band, depending on what your environment can reach. The executor needs nothing extra. It authenticates with the same client certificate and API credentials as the other components. You apply its cluster-wide grant through your kubeconfig, not over the network. Bundle delivery. If you prefer not to redeem a token online, your account team can deliver the enrollment bundle directly during onboarding; run clicklink clctl init --handoff <bundle-file> in place of --enroll. --handoff replaces only the token redemption. Certificate signing still happens over the enrollment endpoint, so use --handoff alone only when that endpoint is reachable from where you run init. Out-of-band certificate signing. When the enrollment endpoint is unreachable from where you run init, add --no-auto-sign: init stages everything and writes clicklink.csr. Send the CSR to your account team, then complete the install with the returned certificate and chain. On a VM, run sudo clicklink clctl init --signed-cert client.crt --chain ca-chain.crt. On Kubernetes, run clicklink clctl init --signed-cert client.crt --chain ca-chain.crt --target helm --target-namespace <connector-namespace> --values clicklink-values.yaml; the staged run prints an equivalent kubectl patch plus helm upgrade --install sequence. Only the CSR travels; the private key never leaves your environment. On Kubernetes, --chart accepts a chart name resolved through --chart-repo, an oci:// reference, a direct URL, or a local archive or directory. --chart-version defaults to the CLI’s own version, so the binary and chart move together. To serve images from your own registry, mirror the container image and set image.repository in the values overlay. If your egress path presents a private CA to the connector, pass --api-private-ca. The connector then verifies your connector endpoint against the system roots plus the CA chain from the enrollment bundle. The installer works from a mirror too: host the release artifacts and install.sh on your own mirror and point at it with CLICKLINK_MIRROR_URL.

​
Manual download and verification

When you prefer not to pipe the installer, fetch and verify the release yourself. The block detects your platform and architecture; run it as is on macOS or Linux, amd64 or arm64:
Verify the signature with cosign before extracting anything:
On a workstation (Kubernetes installs), extract the tarball and install the binary:
On a VM, extract the tarball and run sudo ./install.sh from the extracted directory. Next to its release artifacts, it performs the same host install as --host.

​
If something fails

Re-run the same command. init is idempotent: re-runs converge on the same state, keep your existing config and staged files, and skip completed work. When a step fails partway through, the CLI prints the exact recovery commands; they are safe to repeat. If enrollment is refused, the token was already redeemed, invalid, or expired. For a redeemed token, re-run with --handoff handoff.yaml, which exists until the cleanup step. Otherwise ask your account team for a fresh token. If enrollment fails with a transport error, re-run the same command. A refused re-run means the first attempt spent the token, so request a fresh one. If managed mode is refused because the cluster is not EKS, re-run with --no-managed to install without the executor. On a VM, a kubeconfig whose current context points elsewhere is refused too: switch context with kubectl config use-context and re-run. If the executor’s grant cannot be applied:
  • On a VM, init does not fail. It stages the bundle and prints a warning with the exact command to run from a kubeconfig that has cluster admin. The verifying preflight reports the executor’s state as it is. Run the printed command, then re-run the same init command to verify:
  • On Kubernetes, a refused grant stops init before the chart is deployed, because the executor binds to the granted ServiceAccount and cannot start without it. The staged overlay, Secrets, and CSR are kept, and init prints the two commands to run from a host with cluster admin. Run them, then re-run the same init command to continue:
--force is an explicit reset; a routine retry does not need it. It overwrites the kept config or values overlay, regenerates the client key, and supersedes an unexpired client certificate (a 409 from the signing endpoint means one already exists). It preserves the connector’s cluster UUID and its managed-mode posture. Unattended re-runs keep the posture, and on a terminal the prompt defaults to it, unless you pass --managed or --no-managed. Use --force to rotate credentials or supersede a certificate; see operations for the full re-run and recovery model.
Last modified on September 22, 2026