Référence de la CLI - ClickHouse Documentation

Le connecteur est fourni sous la forme d’un unique binaire nommé clicklink ; les commandes à exécuter se trouvent sous clicklink clctl. Cette page présente les commandes utilisées lors de l’installation et des opérations quotidiennes. Exécutez n’importe quelle commande avec --help pour afficher son aide complète. Les flags des sous-arborescences troubleshoot, scraper, preflight, executor, instances create et platform, ainsi que les flags globaux --endpoint et --cluster, peuvent également provenir des variables d’environnement CLCTL_* (dont le nom est indiqué dans l’aide de chaque flag) ou du fichier ~/.clicklink/clctl.yaml. Le flag global -v journalise les requêtes d’API admin effectuées par une commande ; -vv ajoute le corps des requêtes. Les commandes instances et commands, ainsi que executor teardown, interrogent l’API locale de l’executor. Deux flags globaux permettent de la sélectionner : --endpoint <url> (par défaut http://127.0.0.1:9999, variable d’environnement CLCTL_ENDPOINT) et --cluster <name> (variable d’environnement CLCTL_CLUSTER), qui désigne le cluster managé lorsqu’une commande en requiert un. Sur Kubernetes, ouvrez d’abord un kubectl port-forward vers le Deployment de l’executor ; consultez services managés.

clicklink clctl init

Initialise le connecteur à partir d’un jeton d’inscription, d’un bundle d’inscription enregistré ou d’un certificat signé transmis hors bande. Une seule exécution prépare la configuration, provisionne l’accès à ClickHouse, obtient le certificat client mTLS, effectue le déploiement (chart Helm ou unités systemd) et vérifie l’état de santé. Avec --managed, elle active également l’executor pour le cluster EKS qu’elle détecte et accorde à l’executor un accès à l’échelle du cluster. Vous pouvez relancer la commande sans risque : init conserve la configuration et l’UUID du cluster, remplace les informations d’identification de façon atomique et réutilise une clé client existante, sauf si vous spécifiez --force. Consultez l’onboarding pour connaître le processus complet et les services managés pour savoir ce que fait l’executor.

Points d’entrée

Un seul point d’entrée est obligatoire.

Indicateur	Description
`--enroll <url>`	Le flux standard. Utilise l’endpoint de votre connector (`https://<subdomain>.<connector-domain>`) et échange un jeton d’inscription à usage unique, demandé sans écho dans un terminal ou lu sur la première ligne de stdin. Écrit le bundle obtenu dans `handoff.yaml` (mode 0600) et poursuit comme avec `--handoff handoff.yaml`. Le jeton n’apparaît jamais dans la ligne de commande, sur le disque ou dans les logs.
`--handoff <path>`	Initialise à partir d’un bundle d’inscription enregistré. Les réexécutions et la récupération utilisent cette option une fois que `handoff.yaml` existe.
`--signed-cert <path>`	Phase 2 du flux air-gapped : installe un certificat client signé hors bande et termine l’installation par étapes. `--chain <path>` remplace facultativement la chaîne de CA associée.

Indicateurs courants

Indicateur	Description
`--target <shape>`	Shape de déploiement : `systemd` (par défaut ; bootstrap de la VM sur laquelle vous vous trouvez) ou `helm` (mise en stage du chart `clicklink-connector` depuis un poste de travail disposant d’un kubeconfig).
`--instance <spec>`	ClickHouse instance que vous exploitez vous-même, sous forme de paires `key=value` séparées par des virgules (`name`, `host`, `port`, `secure`, `database`, `namespace`, `cluster`) ; répétable. Ignore les prompts interactifs relatifs à l’instance. Refusé en mode managé sur Kubernetes : c’est un déploiement distinct installé avec `--no-managed` qui observe une telle instance.
`--env <label>`	Label d’environnement injecté dans chaque métrique émise sous `scraper.labels.env` (par défaut `production`). Passez `staging` pour une installation de staging.
`--operators <emails>`	E-mails des opérateurs, séparés par des virgules, autorisés à ouvrir des sessions de support ; active la passerelle de sessions et ignore le prompt.
`--no-gateway`	Désactive la passerelle de sessions (aucune session gérée par OIDC) ; ignore le prompt. Sur une VM, root sur l’hôte peut toujours gérer les sessions via le fichier de session local.
`--managed`	Active le mode managé : exécute l’executor afin que ClickHouse Cloud gère le cycle de vie des services ClickHouse de ce cluster ; ignore le prompt. Nécessite un EKS cluster Amazon.
`--no-managed`	Laisse le mode managé (l’executor) désactivé ; ignore le prompt.
`--from-terraform <path>`	Sorties d’un module racine Terraform, telles qu’affichées par `terraform output -json` (`-` lit stdin). Renseigne `--cluster-name`, `--server` et `--ca-data` sur une VM, ou `--target-namespace` ainsi que le rôle IRSA et le sélecteur de nœuds de la surcouche managée sur Kubernetes. Un indicateur en contradiction avec le fichier est refusé.
`--force`	Écrase un config ou une surcouche existante et régénère la client key ; vaut également acceptation du remplacement d’un certificat auto-signé non expiré. L’UUID du cluster est conservé, même avec `--force`.
`--skip-provision`	Stage uniquement : ignore le provisionnement des accès ClickHouse par rôle (et, sur la cible systemd, l’activation et la vérification de l’unit). Exécutez `clicklink clctl {scraper,troubleshoot} access provision` séparément. `--target helm` applique malgré tout le grant de l’executor ; une VM l’ignore également.
`--ch-user-suffix <suffix>`	Suffix optionnel pour les usernames ClickHouse provisionnés (`pcm_scraper` devient `pcm_scraper_<suffix>`), afin qu’un second déploiement du connector puisse partager une instance sans entrer en conflit avec les utilisateurs du premier.
`--ch-admin-password-stdin`	Lit le password de l’Admin ClickHouse depuis stdin lorsque le provisioning SQL en nécessite un ; une exécution dans un terminal affiche un prompt à la place.

Options de signature (phase 1 uniquement)

Option	Description
`--no-auto-sign`	Uniquement à cette étape : ignore la signature automatique de la CSR via l’endpoint d’inscription, pour les flux de signature en environnement isolé du réseau ou hors bande.
`--sign-endpoint <url>`	Remplace l’endpoint de signature d’inscription (par défaut : dérivé de l’endpoint du bundle par insertion du label DNS `enroll`). Doit être une URL HTTPS.

Indicateurs réservés à Kubernetes

Valables uniquement avec --target helm.

Indicateur	Description
`--target-namespace <ns>`	Espace de noms dans lequel le chart est installé et où ses secrets sont créés (par défaut : `clicklink` ; demandé dans un terminal).
`--instance-namespace <ns>`	Espace de noms de l’instance ClickHouse cible ; initialise la détection du Service natif et les invites relatives à l’instance. Refusée avec `--managed` : une installation managée n’enregistre aucune instance existante.
`--storage-class <name>`	StorageClass des volumes d’état de l’outil de diagnostic et de l’executor (par défaut : la StorageClass par défaut du cluster ; demandée ou obligatoire si le cluster n’en définit aucune).
`--values <path>`	Chemin de la surcouche de valeurs préparée (par défaut : `clicklink-values.yaml`).
`--chart <ref>`	Chart à déployer : un nom résolu dans `--chart-repo`, ou une référence directe `oci://`, une URL ou une référence locale pour les installations en miroir (par défaut : `clicklink-connector`).
`--chart-repo <url>`	Dépôt Helm dans lequel le nom du chart est résolu (par défaut : `https://releases.clicklink.clickhouse.com/charts`) ; ignoré pour les références `--chart` directes.
`--chart-version <ver>`	Version du chart à déployer (par défaut : la version de publication de ce binaire).
`--ch-pod <ref>`	Pod ClickHouse utilisé pour les étapes de provisionnement dans le pod, sous forme de nom ou de sélecteur de labels `k=v` (par défaut : un pod Running associé au Service de chaque instance).
`--api-private-ca`	Votre connector endpoint fournit un certificat émis par la CA du bundle d’inscription : prépare `api.tls.caFile` pour qu’il pointe vers la chaîne de CA montée, laquelle est ajoutée aux racines système.
`--egress-cidrs <cidrs>`	CIDR de votre connector endpoint, séparés par des virgules, pour la NetworkPolicy de refus par défaut du chart : celle-ci est préparée activée avec ces valeurs dans `networkPolicy.allowEgressCIDRs` (demandés dans un terminal en mode managé). À défaut, la policy est préparée désactivée, à vous de l’activer ultérieurement.
`--platform-bundle <path\|from-api>`	Manifeste de plateforme rendu (le fichier lu par `clicklink clctl platform approve --bundle`), ou `from-api` pour récupérer, via l’API du connector, celui que ClickHouse Cloud a rendu pour votre infrastructure inscrite. Avec `--managed` et `--from-terraform`, installe, s’ils sont absents, Karpenter et ses pools de nœuds, le contrôleur AWS Load Balancer, la StorageClass `gp3-encrypted` ainsi que les composants épinglés par le bundle. Voir Terraform sur AWS.
`--server-instance-families <families>`	Nécessite `--platform-bundle`. Familles d’instances EC2 arm64 à stockage d’instance avec NVMe local pour le NodePool `clickhouse-server`, séparées par des virgules (par défaut : `m7gd`). Les indicateurs de pool ne s’appliquent qu’aux nouveaux NodePools ; les pools existants ne sont pas modifiés.
`--keeper-instance-families <families>`	Nécessite `--platform-bundle`. Familles d’instances EC2 arm64 du NodePool `clickhouse-keeper`, séparées par des virgules (par défaut : `m7g`).
`--server-pool-limits <limits>`	Nécessite `--platform-bundle`. Limites de ressources `key=quantity` du NodePool `clickhouse-server`, séparées par des virgules (par défaut : `cpu=1000,memory=4Ti`).
`--keeper-pool-limits <limits>`	Nécessite `--platform-bundle`. Limites de ressources `key=quantity` du NodePool `clickhouse-keeper`, séparées par des virgules (par défaut : `cpu=100,memory=400Gi`).

Options réservées aux VM

Valable uniquement avec --target systemd.

Option	Description
`--server <url>`	URL du serveur d’API Kubernetes vers lequel pointent les bundles d’accès (par défaut : kubeconfig de cet hôte, sinon demandée).
`--ca-data <base64>`	`certificate-authority-data` encodé en Base64 pour `--server` (par défaut : kubeconfig de cet hôte, sinon demandée).
`--cluster-name <name>`	Nom du cluster EKS piloté par le mode managed (par défaut : l’unique cluster EKS présent dans le kubeconfig de cet hôte ; demandé dans un terminal).
`--no-instance`	Démarre avec un registre d’instances vide et ignore les invites relatives aux instances.

Conflits entre indicateurs

--handoff, --enroll et --signed-cert s’excluent mutuellement ; un seul doit être spécifié.
Les indicateurs propres à Kubernetes sont rejetés sauf avec --target helm ; --server, --ca-data, --cluster-name et --no-instance sont rejetés avec --target helm (le processus Helm lit le kubeconfig du poste de travail et détecte l’instance in-cluster).
--no-instance et --instance s’excluent mutuellement.
--managed et --no-managed s’excluent mutuellement, et --cluster-name est rejeté avec --no-managed. Avec --target helm, --instance et --instance-namespace sont rejetés avec --managed.
--no-auto-sign et --sign-endpoint s’excluent mutuellement, et tous deux (ainsi que --api-private-ca, --managed, --no-managed et --cluster-name) sont rejetés avec --signed-cert.
--platform-bundle nécessite --target helm, --managed et --from-terraform, et est rejeté avec --no-managed ou --signed-cert. Les quatre indicateurs de pool sont rejetés sans --platform-bundle, et sont refusés si les NodePools existent déjà.
--operators et --no-gateway s’excluent mutuellement.
--skip-provision rejette --ch-pod, --ch-user-suffix, --server, --ca-data et --ch-admin-password-stdin (aucun provisionnement n’est effectué).

clicklink clctl preflight

Exécute la suite de vérifications du connecteur, regroupées par catégorie : configuration, fichiers, réseau, ClickHouse, systemd, accès, disque, masquage. Chaque vérification indique une réussite, un avertissement, un échec ou une omission. Le code de sortie 0 signifie que toutes les vérifications ont réussi (les avertissements ne sont pas bloquants) ; le code de sortie 2 signifie qu’au moins une a échoué. Par défaut, la commande s’exécute localement. Avec --k8s-namespace, elle exécute le binaire du connecteur dans son propre pod via kubectl exec et affiche le rapport localement (les vérifications systemd sont toujours ignorées dans les pods). Avec les options du canal distant, elle exécute à la place le binaire installé sur une VM distante.

Option	Description
`--config <path>`	Chemin vers le fichier de configuration du connecteur ; pour une cible distante, chemin sur cet hôte.
`--output <fmt>`, `-o`	Format de sortie : `text` (par défaut) ou `json`.
`--timeout <dur>`	Délai d’expiration global pour toutes les vérifications (par défaut : `30s`).
`--skip-systemd`	Ignore les vérifications de l’état des unités systemd (hôtes sans systemd).
`--k8s-namespace <ns>`	Espace de noms du chart du connecteur ; exécute preflight dans le pod du connecteur via `kubectl exec`.
`--k8s-component <name>`	Pod du connecteur dans lequel exécuter la commande : `scraper` (par défaut) ou `troubleshooter`.
`--k8s-pod <ref>`	Nom du pod ou remplacement du sélecteur de labels `k=v` (par défaut : les labels de composant du chart).
`--k8s-container <name>`	Conteneur dans lequel exécuter la commande (par défaut : le nom du composant).

Les options --k8s-* et les options du canal distant s’excluent mutuellement ; choisissez une cible.

clicklink clctl troubleshoot session

Active, désactive et inspecte la session de support : la période limitée pendant laquelle le composant de dépannage accepte les commandes. Sans session active, le démon refuse toutes les commandes, même lorsque son WebSocket est connecté. Consultez les sessions de support. Les commandes s’exécutent dans l’un des deux modes suivants :

Fichier local (par défaut) : lit et écrit le fichier d’état de session sur l’hôte sur lequel le composant de dépannage s’exécute (par défaut, /var/lib/clicklink/session.json).
Gateway : avec --gateway-url, obtient un jeton d’ID OIDC et appelle à la place la gateway de session du composant de dépannage depuis votre poste de travail.

Options communes

Option	Description
`--session-file <path>`	Chemin du fichier d’état de session (par défaut : `/var/lib/clicklink/session.json`).
`--config <path>`	Fichier de configuration du connecteur ; le chemin du fichier de session est déterminé à partir de sa section `troubleshooter`.
`--gateway-url <url>`	URL de base de la passerelle de session. Lorsqu’elle est définie, la commande obtient un jeton Bearer OIDC et appelle la passerelle au lieu d’utiliser le fichier d’état local. S’exclut mutuellement avec `--session-file` et `--config`.
`--gateway-audience <aud>`	Claim d’audience auquel le jeton OIDC est associé (par défaut : `clicklink-clctl`, qui correspond également à la valeur par défaut de la passerelle). Ne le définissez que si l’audience de la passerelle a été reconfigurée.
`--gateway-issuer <url>`	Émetteur OIDC que la passerelle valide. Une valeur vide sélectionne le flux Google ; définissez-le avec `--oidc-client-id` pour exécuter le flux Device Code avec un fournisseur d’identité autre que Google.
`--oidc-client-id <id>`	ID de client OIDC public pour le flux Device Code, enregistré auprès de `--gateway-issuer` avec le grant Device Code activé.
`--token-file <path>`	Fichier contenant un jeton d’ID OIDC préémis, utilisé comme jeton Bearer et contournant les autres fournisseurs de jetons.
`--gateway-ca <path>`	Bundle d’AC vérifiant le certificat de la passerelle (certificat fourni par vos soins). Lorsqu’il n’est pas défini, la commande utilise un certificat épinglé via `gateway trust` ; une passerelle autosignée sans certificat épinglé échoue de manière sécurisée.

activation de session

Indicateur	Description
`--duration <dur>`	Durée pendant laquelle la session reste active (par défaut : `4h`, maximum : `24h`).
`--reason <text>`	Raison facultative en texte libre enregistrée avec la session (jusqu’à 256 caractères).
`--user <name>`	Identité de l’opérateur à enregistrer en mode fichier local ; par défaut, `$SUDO_USER` ou `$USER` est utilisé. En mode gateway, l’e-mail attesté par le token fait autorité.

L’activation échoue si une session est déjà active ; désactivez-la d’abord ou attendez qu’elle expire.

session disable

Désactive immédiatement la session. Cette commande est sans effet lorsqu’aucune session n’est active.

état de la session

Indique si la session est active, qui l’a activée et à quelle date elle expire. --output (-o) sélectionne table (par défaut) ou json. Sur Kubernetes, accédez à la passerelle à l’aide d’un transfert de port :

kubectl -n <connector-namespace> port-forward \
  statefulset/clicklink-connector-troubleshooter 8443:8443
clicklink clctl troubleshoot session enable \
  --gateway-url http://localhost:8443 \
  --duration 1h --reason "support ticket 1234"

clicklink clctl troubleshoot gateway trust

Sur une VM, la passerelle de session utilise un certificat TLS auto-signé. Cette commande enregistre l’empreinte SHA-256 du certificat dans ~/.clicklink/clctl.yaml afin que les commandes session puissent le vérifier ; si une empreinte épinglée ne correspond plus, la vérification échoue de manière sécurisée. La relation de confiance est établie hors bande de l’une des deux manières suivantes :

Avec les options du canal distant, la commande lit le certificat sur la VM via le canal déjà authentifié, puis l’épingle.
Sans canal, transmettez --gateway-fingerprint avec la valeur SHA-256 journalisée par le connecteur lors de la génération du certificat ; la commande n’épingle le certificat récupéré que s’il correspond. Si vous omettez l’option, l’empreinte présentée s’affiche sans qu’aucune empreinte ne soit épinglée.

Indicateur	Description
`--gateway-url <url>`	URL de base de la passerelle à approuver (obligatoire), par exemple `https://<vm-host>:8443`. Doit être en `https://`.
`--gateway-fingerprint <sha256>`	Empreinte SHA-256 attendue issue du journal du connecteur, vérifiée avant l’épinglage. Les deux-points et la casse sont ignorés.
`--remote-cert-file <path>`	Chemin du certificat de la passerelle sur la VM, lu via le canal (par défaut : `/var/lib/clicklink/gateway/tls/server.crt`).

clicklink clctl troubleshoot gateway trust \
  --gateway-url https://<vm-host>:8443 \
  --gateway-fingerprint <sha256-from-connector-log>

Sur Kubernetes, le pinning n’est pas utilisé : exposez la passerelle via un Ingress avec un certificat émis par une CA, ou utilisez un port-forward.

clicklink clctl troubleshoot audit tail

Affiche les dernières entrées du journal d’audit de l’utilitaire de dépannage : JSON délimité par des sauts de ligne, avec une entrée pour chaque commande acceptée ou bloquée par le démon. Il ouvre le journal en lecture seule.

Indicateur	Description
`--lines <n>`, `-n`	Nombre d’entrées finales à afficher (50 par défaut).
`--path <path>`	Chemin du fichier journal d’audit (par défaut : `/var/log/clicklink/troubleshoot-audit.log`).

L’image d’exécution du connecteur ne contient pas de shell ; sur Kubernetes, cette commande est donc le lecteur pris en charge :

kubectl -n <connector-namespace> exec <troubleshooter-pod> -- \
  /clicklink clctl troubleshoot audit tail

Provisionnement des accès

clicklink clctl scraper access provision et clicklink clctl troubleshoot access provision créent et, avec --force, renouvellent le bundle d’accès par instance d’un composant : l’utilisateur ClickHouse en lecture seule et ses privilèges, ainsi que le ServiceAccount Kubernetes, les RBAC et le jeton utilisés par le composant. init exécute cette opération directement lors de l’installation ; les commandes autonomes permettent de la relancer ou de renouveler les identifiants.

Indicateur	Description
`--instance <name>`	Nom de l’instance issu de la configuration (obligatoire).
`--server <url>`	URL du serveur d’API Kubernetes (obligatoire).
`--ca-data <base64>`	Certificat CA du cluster encodé en Base64 pour le kubeconfig généré.
`--config <path>`	Fichier de configuration du connecteur à partir duquel lire l’instance.
`--target <shape>`	`systemd` (par défaut : envoie le bundle vers une VM via un canal distant, ou le génère localement avec `--provider local`) ou `helm` (transfère le bundle sous forme de secret Kubernetes pour le chart).
`--target-namespace <ns>`	Espace de noms dans lequel le secret du bundle est créé (obligatoire avec `--target helm`).
`--instance-namespace <ns>`	Espace de noms de l’instance ClickHouse cible ; avec cet indicateur, la commande n’a besoin d’aucune entrée de registre pour `--instance`.
`--force`	Écrase un bundle existant : permet de relancer l’opération ou de renouveler les identifiants.
`--secret-name <name>`	Remplace le nom du secret du bundle (par défaut `clicklink-connector-<component>-access-<instance>`).
`--output-dir <path>`	(`--target helm` ou `--provider local`) Répertoire racine dans lequel le bundle est créé (par défaut : `./<component>/` dans le répertoire de travail pour `helm`, le répertoire d’accès du composant pour `local`).
`--audit-log <path>`	Journal d’audit du provisionnement, au format NDJSON, en mode ajout (par défaut `clctl-audit.log` à côté du répertoire de sortie du bundle ; `none` le désactive).
`--ch-admin-user <name>`	Utilisateur administrateur ClickHouse pour appliquer les privilèges (par défaut `default`).
`--ch-admin-password-stdin`	Lit le mot de passe de l’administrateur ClickHouse depuis l’entrée standard.
`--ch-user-suffix <suffix>`	Suffixe facultatif pour le nom d’utilisateur ClickHouse provisionné.
`--ch-user-via <mode>`	Méthode de provisionnement de l’utilisateur ClickHouse : `sql` (par défaut ; applique les privilèges générés en tant que `--ch-admin-user`) ou `cr` (écrit l’utilisateur dans la ressource personnalisée de l’instance, pour les instances gérées par un opérateur sans administrateur compatible SQL).
`--apply-ch-grants`	(`--target helm`) Applique les privilèges générés dans le pod via `kubectl exec` au lieu de vous laisser le faire.
`--ch-pod <ref>`, `--ch-pod-namespace <ns>`, `--ch-container <name>`	(`--target helm` avec `--apply-ch-grants` ou `--ch-user-via cr`) Sélectionne le pod ClickHouse et le conteneur dans lesquels exécuter la commande.
`--token-duration <dur>`	Durée de vie du jeton ServiceAccount (par défaut `2160h`, 90 jours ; EKS limite les attributions à 24 heures).
`--skip-restart`	Ignore le redémarrage du composant après le provisionnement.
`--dry-run`	Affiche le plan et quitte ; aucune écriture dans Kubernetes, à distance ou dans ClickHouse.

Renouvelez les identifiants d’un composant pour une instance :

clicklink clctl scraper access provision --target helm \
  --target-namespace <connector-namespace> \
  --instance <instance-name> --instance-namespace <clickhouse-namespace> \
  --server <kubernetes-api-server-url> \
  --apply-ch-grants --ch-pod <clickhouse-pod-or-label-selector> --ch-pod-namespace <clickhouse-namespace> \
  --force

clicklink clctl executor access

init --managed applique le grant cluster-wide de l’executor avec vos credentials. Lorsque ce n’est pas possible, init affiche les commands à exécuter depuis un kubeconfig disposant des droits d’admin du cluster : access apply seul sur une VM (le bundle est déjà préparé), ou access grant puis access apply sur Kubernetes. Voir onboarding.

executor access grant

Génère le bundle d’accès à l’échelle du cluster de l’executor dans <output-dir>/_cluster/ : un ServiceAccount, un ClusterRole et un ClusterRoleBinding, ainsi qu’une ValidatingAdmissionPolicy qui restreint le ServiceAccount aux namespaces situés sous le prefix de namespace de l’executor. Vérifiez le RBAC généré avant de l’appliquer.

Flag	Description
`--cluster`	Génère le bundle à l’échelle du cluster (obligatoire pour cet usage ; sans ce flag, la commande génère un bundle par service pour `--instance`).
`--config <path>`	Fichier de configuration du connector (variable d’environnement `CLCTL_EXECUTOR_CONFIG`).
`--sa-namespace <ns>`	Namespace d’origine du ServiceAccount de l’executor (par défaut `clicklink-system` ; le namespace du connector dans le cas d’une installation Kubernetes).
`--context <name>`	Context kubeconfig du cluster managé, comme pour `prepare`.
`--server <url>`, `--ca-data <base64>`	URL du Kubernetes API server et CA à intégrer dans le kubeconfig (par défaut : ceux du context kube).
`--output-dir <path>`	Racine de sortie (par défaut `/etc/clicklink/access/executor` ; variable d’environnement `CLCTL_EXECUTOR_OUTPUT_DIR`).
`--force`	Écrase un bundle existant.
`--dry-run`	Affiche le plan sans écrire de fichiers.

executor access apply

Applique le bundle grant généré à l’échelle du cluster : le Namespace d’origine du ServiceAccount, le ServiceAccount, le ClusterRole et le ClusterRoleBinding, ainsi que la policy d’admission, puis génère le token du ServiceAccount dans le bundle. Il n’enregistre aucun service.

Flag	Description
`--cluster`	Applique le bundle à l’échelle du cluster depuis `<output-dir>/_cluster/` (obligatoire pour cet usage).
`--config <path>`	Fichier de configuration du connector (variable d’environnement `CLCTL_EXECUTOR_CONFIG`).
`--context <name>`	Context kubeconfig du cluster managé, comme pour `prepare`.
`--output-dir <path>`	Racine de sortie (par défaut `/etc/clicklink/access/executor` ; variable d’environnement `CLCTL_EXECUTOR_OUTPUT_DIR`).
`--token-duration <dur>`	Durée de vie du token ServiceAccount (par défaut `2160h`, soit 90 jours).
`--dry-run`	Affiche ce qui serait appliqué, sans rien exécuter.

clicklink clctl executor access grant --cluster --sa-namespace <connector-namespace> --server <kubernetes-api-server-url> --output-dir <dir>
clicklink clctl executor access apply --cluster --output-dir <dir>

clicklink clctl executor prepare

Prépare, de votre côté, tout ce dont la création d’un service managé a besoin, en une seule exécution idempotente qui s’arrête à la première erreur. La commande choisit ou valide le nom du service et crée les buckets de données et de sauvegarde ainsi que le rôle IAM (ou vérifie un rôle que vous fournissez). Sur une VM, elle génère et applique également le bundle d’accès de l’executor pour le namespace du service ; sur Kubernetes, le bundle est ignoré car l’executor s’exécute avec le ServiceAccount de son pod. Elle génère ensuite le mot de passe de l’utilisateur default (affiché une seule fois) et écrit le corps de création destiné à instances create. Voir services managés. Sur une VM, elle s’exécute sur l’hôte du connecteur. Pour une installation Kubernetes, elle s’exécute sur un poste de travail disposant de credentials AWS et d’un contexte kube pour le cluster managé. Ce poste de travail doit également disposer d’une copie de la configuration du connecteur (--config), d’un port-forward vers l’API locale de l’executor et d’un --output-dir accessible en écriture.

Option	Description
`--config <path>`	Fichier de configuration du connecteur (obligatoire ; variable d’environnement `CLCTL_EXECUTOR_CONFIG`). C’est à partir de lui qu’est généré le bundle d’accès, et le contexte kube doit concorder avec son `executor.cluster`.
`--instance <name>`	Nom du service (variable d’environnement `CLCTL_EXECUTOR_INSTANCE`). Par défaut : un nom généré, enregistré dans `<output-dir>/_prepare/<eks-cluster-name>.name` et repris lors de l’exécution suivante.
`--new-name`	Ignore le nom enregistré lors d’une exécution précédente et en choisit un nouveau.
`--context <name>`	Contexte kubeconfig du cluster managé : un nom, ou un motif (une seule correspondance est retenue, plusieurs déclenchent une invite) ; variable d’environnement `CLCTL_CONTEXT`. Par défaut : l’unique contexte, sinon un sélecteur.
`--server <url>`, `--ca-data <base64>`	URL du serveur d’API Kubernetes et CA à intégrer au kubeconfig de l’executor (par défaut : ceux du contexte kube).
`--data-bucket <name>`, `--backup-bucket <name>`	Buckets à vérifier ou à créer (par défaut `<cluster>-clickhouse-data-<rand>` et `<cluster>-clickhouse-backup-<rand>`).
`--role-name <name>`	Nom du rôle IAM (par défaut `CH-S3-<instance>-<region>-00-Role`).
`--role-arn <arn>`	Fournissez votre propre rôle IAM : vérifie sa relation de confiance et ses grants S3, sans jamais créer ni modifier d’IAM.
`--restore-from <name>`	Service à partir des sauvegardes duquel celui-ci effectue sa restauration ; le rôle IAM obtient également un accès en lecture à son bucket de sauvegarde.
`--region <region>`	Région AWS (par défaut : la région du cluster désigné par le contexte kube).
`--token-duration <dur>`	Durée de vie du jeton ServiceAccount (par défaut `2160h`, soit 90 jours).
`--force`	Régénère un bundle d’accès complet au lieu de le réutiliser.
`--output-dir <path>`	Racine de sortie (par défaut `/etc/clicklink/access/executor` ; variable d’environnement `CLCTL_EXECUTOR_OUTPUT_DIR`).
`--output <fmt>`	`text` (par défaut) ou `json`. Aucun des deux ne contient le mot de passe.
`--dry-run`	Exécute chaque étape en mode simulation ; rien n’est créé ni écrit.

clicklink clctl executor teardown

Supprime ce que prepare a créé pour un service que ClickHouse Cloud a supprimé, à savoir : le rôle IAM, le nom enregistré et l’enregistrement du service dans l’executor ; sur une VM, également les ClusterRole et ClusterRoleBinding du service, le bundle d’accès local ainsi que l’entrée du registry. L’executor doit être en cours d’exécution et le service à l’état terminated (ou stale) ; l’exécution est refusée tant que le namespace du service contient encore un cluster ClickHouse. Les buckets créés par prepare, avec leurs données et leurs sauvegardes, sont conservés sauf si vous en demandez la suppression, et les buckets conservés reçoivent le nouveau tag clicklink:retained-from=<name>. La commande lit tout avant de supprimer quoi que ce soit. Voir supprimer un service.

Flag	Description
`--instance <name>`	Nom du service (variable d’environnement `CLCTL_EXECUTOR_INSTANCE`).
`--config <path>`	Fichier de configuration du connector (variable d’environnement `CLCTL_EXECUTOR_CONFIG`) ; lu depuis `/etc/clicklink/config.yaml` sur l’hôte du connector s’il est omis. Fournit `delete_instance_data`.
`--context <name>`	Contexte kubeconfig du cluster managé, comme pour `prepare`.
`--delete-data`	Supprime les données du service même lorsque `delete_instance_data` est désactivé. Nécessite `--yes`.
`--delete-backups`	Supprime le bucket de sauvegarde et les sauvegardes qu’il contient (conservées par défaut). Nécessite `--yes`.
`--yes`	Confirme `--delete-data` et `--delete-backups` ; sans ce flag, l’exécution s’arrête après l’étape d’enregistrement et indique les buckets qui seraient vidés.
`--data-bucket <name>`, `--backup-bucket <name>`	Remplacent les buckets figurant dans l’enregistrement de l’executor (par défaut : ceux liés au rôle du service ou taggés pour lui).
`--role-name <name>`	Nom du rôle IAM (par défaut `CH-S3-<instance>-<region>-00-Role`).
`--region <region>`	Région AWS (par défaut : celle du cluster).
`--namespace-prefix <prefix>`	Préfixe du namespace du service (par défaut `ns-`) ; doit correspondre à une configuration chargée.
`--output-dir <path>`	Racine de sortie (par défaut `/etc/clicklink/access/executor`).
`--output <fmt>`	`text` (par défaut) ou `json`.
`--dry-run`	Affiche ce qui serait supprimé et quitte sans rien supprimer.

clicklink clctl instances

instances create

Soumet une création préparée à ClickHouse Cloud via votre connector endpoint, avec les identifiants propres au connector. La création est activée par environnement ; voir créer un service. La commande affiche le nom prononçable attribué par ClickHouse Cloud, l’état, ainsi qu’une indication watch: qui utilise votre service name. Le corps de la création provient du fichier écrit par prepare, ou de la combinaison des quatre flags --deployed-name, --data-bucket, --backup-bucket et --irsa-role-arn. Un retry effectué avec les mêmes entrées renvoie la première création.

indicateur	Description
`--from-prepare <path>`	Corps de création écrit par `executor prepare` (`<output-dir>/_prepare/<instance>.create.json`), hashes du mot de passe de l’utilisateur `default` inclus. Mutuellement exclusif avec `--deployed-name` et `--default-user-password-file`.
`--deployed-name <name>`, `--data-bucket <name>`, `--backup-bucket <name>`, `--irsa-role-arn <arn>`	Les entrées préparées, sous forme de flags ; requis conjointement.
`--default-user-password-file <path>`	Fichier contenant le mot de passe de l’utilisateur `default` (première ligne), pour la variante par flags. En son absence, la commande génère un mot de passe et l’affiche une seule fois ; un retry doit alors le fournir via ce fichier, sinon le service conserve le premier mot de passe tandis qu’un nouveau s’affiche.
`--config <path>`	Fichier de configuration du connector (variable d’environnement `CLCTL_EXECUTOR_CONFIG` ; `/etc/clicklink/config.yaml` par défaut lorsqu’il existe). Fournit l’endpoint, ses identifiants et l’identity de l’environnement.
`--connector-namespace <ns>`	Kubernetes uniquement, lorsque cet hôte ne dispose ni du fichier de configuration du connector ni des fichiers d’identifiants : le namespace du connector dont la ConfigMap et les Secrets les fournissent (`clicklink` par défaut). Chaque lecture du cluster est annoncée.
`--connector-configmap <name>`	ConfigMap contenant le `config.yaml` de l’executor dans ce namespace (`clicklink-connector-executor` par défaut).
`--hmac-secret-name <name>`, `--mtls-secret-name <name>`	Secrets contenant les identifiants d’API et le certificat client lorsque les fichiers sont absents (valeurs par défaut `clicklink-hmac` et `clicklink-mtls`). La paire de certificat est conservée en mémoire.
`--context <name>`	Contexte Kube pour ces lectures (variable d’environnement `CLCTL_CONTEXT`) ; un pattern ou le picker interactif, comme pour les commandes `executor`.
`--idempotency-key <key>`	Clé qu’un retry réutilise pour récupérer la première création (par défaut : dérivée de l’environnement et du service name).
`--wait`	Interroge l’API locale de l’executor jusqu’à ce que le service soit `running`. Échoue immédiatement si une création a échoué pour ce nom, ou lorsque le service passe à `terminating`, `terminated` ou `stale`.
`--wait-timeout <dur>`	Durée pendant laquelle `--wait` interroge avant d’échouer (`30m` par défaut).

instances list

Affiche au format JSON tous les services connus de l’executor. --cluster <name> filtre par cluster managé.

instances get

Affiche un service, au format JSON, avec le storage avec lequel il a été créé. --name <name> est obligatoire, de même que le cluster : passez --cluster, définissez CLCTL_CLUSTER, ou renseignez-le dans ~/.clicklink/clctl.yaml. Les trois sous-commandes ci-dessous envoient des commands directement à l’API locale de l’executor, en contournant ClickHouse Cloud. Ne les exécutez que si votre account team vous le demande. Chacune requiert --name <name> et le cluster (--cluster, CLCTL_CLUSTER, ou ~/.clicklink/clctl.yaml), et chacune affiche la command au format JSON. Passez son id à commands get pour en suivre l’avancement ; le result d’une command en échec contient son error.

instances scale

Définit le nombre de répliques de serveur d’un service via un ScalingOverride. --server-replicas <n> est obligatoire et doit être supérieur à zéro. L’executor signale la commande comme running lorsqu’il applique l’override, puis comme completed lorsque les répliques sont prêtes.

instances patch

Modifie un service en place. --create-nlb est le seul patch disponible ; sans lui, la commande échoue avec le message nothing to patch. Il provisionne un NLB interne sous la forme d’un Service Kubernetes, sur AWS uniquement, afin qu’un scraper situé en dehors du cluster puisse joindre les serveurs. L’executor renseigne par backfill le host du scraper à partir du répartiteur de charge lors de sa prochaine synchronisation.

instances delete

Supprime un service du cluster. Cette commande arrête le service et attend l’arrêt ordonné de l’opérateur. Elle désinstalle ensuite la charge de travail, supprime l’espace de noms ns-<name> ainsi que les artefacts du scraper, attend la disparition de l’espace de noms, puis marque le service comme terminated. Les buckets et l’IAM role du service sont conservés ; executor teardown les supprime à l’aide de vos credentials. Réexécuter une suppression déjà terminée est un no-op. La procédure normale consiste à supprimer le service dans ClickHouse Cloud ; voir supprimer un service.

Commandes clicklink clctl

commands list

Affiche les commandes enregistrées par l’executor, au format JSON, les plus récentes en premier. Le champ result d’une commande ayant échoué contient l’erreur correspondante ; une synchronisation de plateforme en attente de votre approbation y indique la commande platform approve exacte à exécuter.

Flag	Description
`--status <status>`	Filtre : `pending`, `running`, `completed` ou `failed`.
`--action <action>`	Filtrer par action, par exemple `create_instance` ou `sync_platform`.
`--cluster <name>`	Filtrer par cluster géré.

commands get

clicklink clctl commands get <id> affiche une commande, avec son étape et son résultat.

clicklink clctl platform approve

Autorise une modification de plateforme avec vos propres identifiants de cluster. La commande lit le bundle préparé par l’executor, en calcule le hachage et effectue le rendu de chaque chart qu’il contient exactement comme le fera l’executor. Elle applique la moitié « permissions » avec le contexte kube que vous choisissez, crée si nécessaire l’identity pcm-platform de l’executor et émet son jeton. Elle n’envoie aucune requête à votre connector endpoint. La moitié « permissions » regroupe les Namespaces, CustomResourceDefinitions, ServiceAccounts, ClusterRoles et bindings, Roles et bindings, configurations de webhook et d’admission, PriorityClasses, ainsi que la StorageClass. L’executor n’applique ensuite que la moitié « charges de travail », et uniquement tant que ce jeton reste valide. Voir mises à jour de plateforme. Pour un accès direct au registre de ClickHouse, exécutez l’approbation sur la VM EC2 du connector : la CLI utilise son profil d’instance pour endosser le rôle de récupération en lecture seule, indépendamment des identifiants de votre kubeconfig. Les autres registres de charts ECR utilisent les identifiants AWS ambiants. Voir identifiants de registre.

Indicateur	Description
`--config <path>`	Fichier de configuration du connector (variable d’environnement `CLCTL_EXECUTOR_CONFIG`). Fournit le préfixe de namespace ; sur un poste de travail, une copie de la configuration du connector.
`--context <name>`	Contexte kubeconfig du cluster managé, disposant des droits cluster-admin ; un nom ou un motif (variable d’environnement `CLCTL_CONTEXT`). Par défaut : l’unique contexte, sinon un sélecteur.
`--ttl <dur>`	Durée de vie du jeton de plateforme (par défaut `2h`). L’executor ne le renouvelle jamais.
`--output-dir <path>`	Racine d’accès : le bundle préparé y est lu et le jeton y est écrit, dans `_platform` (par défaut `/etc/clicklink/access/executor` ; variable d’environnement `CLCTL_EXECUTOR_OUTPUT_DIR`).
`--secret-namespace <ns>`	Installations Kubernetes : lit le bundle préparé depuis l’API locale de l’executor et livre le bundle de jeton sous forme de Secret dans ce namespace (le namespace du connector) plutôt que dans `<output-dir>/_platform`.
`--secret-name <name>`	Nom du Secret pour `--secret-namespace` (par défaut `clicklink-platform-bundle`) ; doit correspondre au `executor.platformBundleSecret` du chart.
`--endpoint <url>`	Installations Kubernetes : l’API locale de l’executor, accessible via un `kubectl port-forward` (par défaut `http://127.0.0.1:9999` ; variable d’environnement `CLCTL_ENDPOINT`).
`--bundle <path>`	Remplacement : un manifeste de plateforme déjà rendu et transmis hors bande, lu à la place du bundle préparé. Normalement omis.
`--dry-run`	Effectue le rendu et liste la moitié « permissions » sans l’appliquer ni émettre de jeton.

clicklink clctl platform reset

Pour les clusters de test sans services : désinstalle les releases de la plateforme dans l’ordre inverse des dépendances et supprime le bundle de token de plateforme de l’executor, afin de pouvoir rejouer la première installation. Avant toute modification, la commande liste les clusters ClickHouse présents dans les namespaces dont ce connector est propriétaire et refuse de continuer s’il en existe. Les CustomResourceDefinitions, le RBAC et la StorageClass sont conservés. Exécutez à nouveau platform approve avant la prochaine synchronisation de la plateforme.

Flag	Description
`--bundle <path>`	Chemin vers le manifest de plateforme généré (obligatoire, lu après la vérification d’absence de cluster).
`--config <path>`	Fichier de configuration du connector (variable d’environnement `CLCTL_EXECUTOR_CONFIG`).
`--context <name>`	Context du kubeconfig du cluster managé, avec les droits cluster-admin.
`--output-dir <path>`	Racine d’access dont le bundle `_platform` est supprimé (par défaut `/etc/clicklink/access/executor`).
`--secret-namespace <ns>`, `--secret-name <name>`	Installations Kubernetes : supprime à la place le Secret du bundle de plateforme dans le namespace du connector (nom par défaut `clicklink-platform-bundle`).
`--dry-run`	Vérifie la présence de services et affiche le plan de réinitialisation sans modifier le cluster.

Options du canal distant

preflight, gateway trust et access provision partagent un ensemble d’options qui déterminent comment accéder à une VM cible :

Option	Description
`--provider <name>`	Canal d’exécution : `ssh`, `aws` (SSM) ou `gcp` (IAP) pour les VM distantes, ou `local` lors de l’exécution directement sur la VM cible. Déduit des options propres à chaque fournisseur s’il n’est pas défini ; vaut `aws` par défaut lorsqu’aucune n’est définie. `local` n’est jamais déduit : sur la VM elle-même, passez donc toujours `--provider local`.
`--ssh-host <host>`, `--ssh-user <user>`, `--ssh-port <port>`, `--ssh-identity-file <path>`	Informations de connexion SSH (`--provider ssh`) ; l’utilisateur, le port et la clé sont définis par défaut à partir de votre configuration SSH.
`--instance-id <id>`, `--region <region>`, `--profile <name>`	Instance EC2, région (par défaut `us-east-1`) et profil de configuration partagée pour SSM (`--provider aws`).
`--project <id>`, `--zone <zone>`, `--instance-name <name>`	Projet, zone et instance pour le tunneling IAP (`--provider gcp`).

​clicklink clctl init

​Points d’entrée

​Indicateurs courants

​Options de signature (phase 1 uniquement)

​Indicateurs réservés à Kubernetes

​Options réservées aux VM

​Conflits entre indicateurs

​clicklink clctl preflight

​clicklink clctl troubleshoot session

​Options communes

​activation de session

​session disable

​état de la session

​clicklink clctl troubleshoot gateway trust

​clicklink clctl troubleshoot audit tail

​Provisionnement des accès

​clicklink clctl executor access

​executor access grant

​executor access apply

​clicklink clctl executor prepare

​clicklink clctl executor teardown

​clicklink clctl instances

​instances create

​instances list

​instances get

​instances scale

​instances patch

​instances delete

​Commandes clicklink clctl

​commands list

​commands get

​clicklink clctl platform approve

​clicklink clctl platform reset

​Options du canal distant