Ce que fait le mode managé
L’executor est un démon intégré au même binaireclicklink que le scraper et le troubleshooter. Il maintient un canal WebSocket sortant vers votre endpoint de connector et reçoit les commandes de cycle de vie de ClickHouse Cloud. Il applique chaque commande à l’unique cluster Kubernetes pour lequel il est configuré et en rend compte par ce canal. Comme les autres composants, il n’établit que des connexions sortantes : ClickHouse Cloud ne se connecte jamais à votre cluster, et l’API locale de l’executor est liée à l’interface de bouclage.
Le mode managé est disponible sur Amazon EKS avec un stockage S3 pendant la private preview. Votre account team l’active lors de l’enregistrement de votre environnement. init refuse un contexte kube qui ne pointe pas vers un EKS cluster.
Chaque service nécessite trois cloud resources qui vous appartiennent : un bucket de données, un bucket de sauvegarde et un IAM role que les pods ClickHouse assument pour y accéder. Vous les créez avec vos propres credentials avant que le service n’existe et vous les supprimez une fois celui-ci supprimé. L’executor ne détient aucun credential pour vos buckets ni pour IAM et ne supprime jamais de données. Ses seuls appels cloud vont vers Amazon ECR et STS. Il se connecte au registry lorsqu’une synchronisation de plateforme ou une création télécharge un chart, et vérifie les images sous le rôle de pull en lecture seule lors d’une mise à jour de plateforme. Il n’effectue aucun appel S3 ou IAM. Pour chaque service, il crée un Service Kubernetes de type LoadBalancer, que le controller de répartiteur de charge de votre cluster concrétise sous la forme d’un NLB interne dans votre account.
Sur une VM, l’executor s’exécute en tant que systemd unit clicklink-executor, aux côtés des deux autres. Sur Kubernetes, il s’agit d’un Deployment à réplique unique dans le namespace du connector. Il expose la santé et les metrics sur le port 8086, et son API locale sur 127.0.0.1:9999.
Activer le mode managé
Vous choisissez le mode managé au moment de l’enrôlement : passez--managed à clicklink clctl init, ou répondez au prompt dans un terminal. Sur une VM, init récupère le cluster depuis le kubeconfig de cet hôte (--cluster-name s’il en contient plusieurs EKS cluster) et accorde l’accès cluster-wide de l’executor de manière intégrée. Sur Kubernetes, passez --egress-cidrs avec les CIDR de votre connector endpoint afin que le chart prépare sa NetworkPolicy de refus par défaut à l’état enabled.
L’installation elle-même ne change pas. Consultez l’onboarding pour le déroulement complet et la référence CLI pour les flags.
Créer un service
La création de service via le connector endpoint est activée par environnement ; vérifiez auprès de votre account team avant de commencer. La création d’un service nécessite deux commandes.prepare crée tout ce qui doit l’être de votre côté ; instances create soumet la création à ClickHouse Cloud via votre connector endpoint. ClickHouse Cloud génère la définition du service et transmet la création à l’executor par son canal sortant. L’executor l’applique à votre cluster et renvoie un compte rendu.
Seul prepare a besoin des AWS credentials : il crée les S3 buckets et l’IAM role. instances create a besoin de la configuration et des credentials du connector, et n’accède à l’API locale de l’executor que pour --wait. Sur une VM, exécutez les deux commandes en tant que root sur l’hôte du connector. Sur Kubernetes, exécutez-les toutes deux depuis un poste de travail disposant d’un contexte kube pour le cluster managé :
preparerequiert une copie de la configuration du connector (--config), unkubectl port-forwardvers l’API locale de l’executor et un--output-diraccessible en écriture. Il vérifie le service name auprès de l’executor et refuse de s’exécuter s’il ne parvient pas à le joindre.- Lorsque cet hôte ne possède pas les fichiers de credentials désignés par la configuration,
instances createles lit depuis les Secretsclicklink-hmacetclicklink-mtlset signale chaque lecture. Ajoutez--connector-namespacelorsque le namespace du connector n’est pasclicklink. Seulinstances createdispose de ce fallback.
1
Préparez le service
- Kubernetes
- VM Linux
instances create et toute nouvelle tentative.- Nom. Choisit un nom de service, ou valide celui que vous passez avec
--instance <name>. Un nom généré est enregistré dans<output-dir>/_prepare/<eks-cluster-name>.namepuis repris par l’exécution suivante : une nouvelle tentative réutilise donc les buckets et le role de la première exécution.--new-nameen choisit un autre. La commande refuse un nom que l’executor détient encore, ou dont le namespace contient déjà un ClickHouse cluster. - Stockage. Crée les buckets de données et de sauvegarde ainsi que l’IAM role
CH-S3-<name>-<region>-00-Role. Les noms de bucket par défaut sont<cluster>-clickhouse-data-<rand>et<cluster>-clickhouse-backup-<rand>;--data-bucketet--backup-bucketpermettent de les remplacer. Avec--role-arn, elle vérifie le role que vous fournissez et n’écrit aucune ressource IAM. - Attribution des privilèges et application. Sur une VM, génère le bundle d’accès de l’executor pour le namespace du service (
ns-<name>), applique son RBAC et enregistre le service dans le registry de l’executor. Sur Kubernetes, cette étape est ignorée : l’executor s’exécute avec le ServiceAccount de son pod et enregistre lui-même le service à l’arrivée de la création. - Récapitulatif. Génère le mot de passe de l’USER
defaultet écrit le corps de création dans<output-dir>/_prepare/<name>.create.json(mode0600; il ne contient que les hashes du mot de passe). Affiche la commande suivante sur une ligneNext:.
--context <name> lorsque votre kubeconfig contient plusieurs contextes ; le Context doit pointer vers l’EKS cluster nommé dans executor.cluster de la config. --dry-run exécute chaque étape sans rien créer ni écrire. L’étape de hachage utilise SHA-1, que Go refuse sous GODEBUG=fips140=only ; exécutez prepare sur un host dépourvu de ce paramètre.2
Validez la création
- Kubernetes
- VM Linux
prepare : c’est par son intermédiaire que --wait interroge l’executor.created <spoken-name> (state provisioning) ainsi qu’un hint watch:. <spoken-name> est le nom affecté par ClickHouse Cloud (par exemple amberaws-kq-42), et non le service name que vous avez préparé. Le hint watch: et toutes les commandes clctl utilisent votre service name.Un retry avec les mêmes entrées est sans risque. La clé d’idempotence est par défaut dérivée de votre environnement et du service name : une nouvelle soumission renvoie donc la première création.--wait interroge l’API locale de l’executor toutes les 10 secondes jusqu’à ce que le service soit running, pendant une durée maximale de --wait-timeout (par défaut 30m). La commande échoue immédiatement, en indiquant l’error enregistrée, si l’executor enregistre une création échouée pour ce nom ou si le service passe à l’état terminating, terminated ou stale.3
Vérifier
status est running. Son utilisateur default utilise le mot de passe affiché par prepare. --cluster peut également provenir de la variable d’environnement CLCTL_CLUSTER.Statut
L’executor répond aux requêtes de statut via son API locale, qui écoute sur127.0.0.1:9999 et ne dispose d’aucune authentification propre. Sur une VM, exécutez les commandes sur l’hôte. Sur Kubernetes, ouvrez d’abord un port-forward et faites-y pointer les commandes :
clicklink clctl instances list affiche au format JSON chaque service connu de l’executor. clicklink clctl instances get --name <name> --cluster <eks-cluster-name> en affiche un seul, avec le stockage avec lequel il a été créé. L’executor déduit le statut à partir de la ressource ClickHouseCluster du service (répliques de serveur prêtes par rapport aux répliques attendues) et l’actualise à chaque sync_interval (30 secondes par défaut) :
provisioning: aucune réplique de serveur n’est encore prête, ou leClickHouseClustern’existe pas encorerunning: toutes les répliques de serveur attendues sont prêtesdegraded: certaines répliques de serveur sont prêtes, mais pas toutesterminating: l’executor désinstalle le serviceterminated: le namespace du service n’existe plusstale: le service a été retiré du registre de l’executor sans suppression ;--waitetteardownle traitent commeterminated
clicklink clctl commands list les affiche, filtrées avec --status (pending, running, completed, failed), --action (par exemple create_instance) ou --cluster. clicklink clctl commands get <id> affiche une commande avec son étape et son résultat. Le champ result d’une commande en échec contient l’erreur : pourquoi une création n’a pas convergé, ou quelle mise à jour de plateforme attend votre approbation.
Cycle de vie du service
Une fois qu’un service existe, ClickHouse Cloud le pilote via l’executor. Les commandes qu’il envoie sont les suivantes :- Scale. ClickHouse Cloud définit un nombre fixe de répliques, plafonné par un paramètre ClickHouse Cloud (20 dans la configuration par défaut). Il n’y a pas d’autoscaling.
- Stop et start. L’arrêt ramène les serveurs à zéro et conserve Keeper ; le démarrage rétablit le nombre de répliques. Les données restent dans vos buckets pendant toute l’opération.
- Restart. L’ensemble du service, son Keeper, ou un seul pod.
- Sauvegardes. ClickHouse Cloud les déclenche ; elles sont déposées dans votre bucket de sauvegarde, et leur suppression les efface.
- Mises à niveau de version et changements de configuration. ClickHouse Cloud régénère la définition du service avec la nouvelle version ou le nouveau paramètre. Celle-ci parvient sous la forme d’une commande
create_instance, si bien quecommands list --action create_instanceaffiche également les mises à niveau. L’executor l’applique et attend que les répliques soient de nouveau prêtes. - Delete. Décrit dans supprimer un service.
running.
Les sous-commandes instances scale, instances patch et instances delete envoient les commandes directement à l’API locale de l’executor, en contournant ClickHouse Cloud. Ne les exécutez que si votre account team vous le demande ; la référence CLI décrit le rôle de chacune.
Sessions de support pour un service managé
L’executor raccorde le scraper à chaque service qu’il crée. En revanche, il ne provisionne pas le troubleshooter : une session de support ne peut donc pas exécuter de diagnostics sur un service managé tant que vous ne l’avez pas fait vous-même. Provisionnez-le une fois par service, avec l’espace de noms du servicens-<name>, de la même manière que pour une instance que vous avez enregistrée vous-même :
- Kubernetes
- VM Linux
$CH_DEFAULT_PASSWORD est le mot de passe de l’utilisateur default affiché par prepare. La commande s’authentifie avec celui-ci pour appliquer les privilèges SQL et ne le demande pas de manière interactive. Ajoutez ensuite la paire Secret et ServiceAccount à troubleshooter.accessBundles, puis exécutez helm upgrade, comme indiqué à la section ajout d’instances ClickHouse.--ch-user-via cr ne survivrait pas : c’est ClickHouse Cloud qui détient la définition du service et la réapplique. À la suppression du service, l’executor supprime le bundle du troubleshooter sur une VM. Sur Kubernetes, le Secret du bundle et le ServiceAccount subsistent jusqu’à ce que vous les supprimiez, comme indiqué à la section désinstallation.
Supprimer un service
Aucune commande de suppression n’est mise à disposition des clients via votre connector endpoint : demandez à votre account team de supprimer le service. ClickHouse Cloud le termine, puis l’executor supprime la charge de travail et son namespace (terminating, puis terminated). Rien n’est modifié côté AWS : les buckets, leurs données et l’IAM role subsistent jusqu’à ce que vous les supprimiez.
Une fois que le service indique terminated, démantelez ce que prepare a créé. Exécutez teardown là où vous avez exécuté prepare, avec les mêmes AWS credentials. Sur Kubernetes, cela implique le même poste de travail, la même copie de configuration et le même répertoire de sortie, ainsi qu’un port-forward ouvert vers l’executor :
- Kubernetes
- VM Linux
prepare et fait oublier le service à l’executor, ce qui libère le nom. Sur une VM, elle supprime également les objets RBAC cluster-wide du service, le bundle d’accès local et l’entrée de registry.
Par défaut, elle conserve les données et les sauvegardes du service. Elle re-tague un bucket conservé en remplaçant clicklink:deployed-name par clicklink:retained-from=<name>, afin qu’un service recréé avec le même nom n’en hérite jamais, et le résumé indique où se trouvent les données. Pour les supprimer, ajoutez --delete-data --delete-backups --yes à la même commande.
Sans --yes, l’exécution s’arrête après l’étape de lecture de l’enregistrement et énumère les buckets qu’elle viderait. --dry-run lit tout et n’écrit rien. Un role que vous avez fourni avec --role-arn, ou un bucket que prepare n’a pas créé, est signalé comme conservé et n’est jamais touché. L’exécution est refusée tant que le namespace du service contient encore un ClickHouse cluster. Elle lit tout avant de supprimer quoi que ce soit : une exécution refusée ne change donc rien.
Lorsque le connector est hors ligne
Les services en cours d’exécution ne dépendent pas de l’executor. Le ClickHouse Operator de votre cluster les maintient en fonctionnement, et un connector déconnecté n’interrompt rien de ce qui traite déjà des queries. Tant qu’aucun executor n’est connecté, ClickHouse Cloud ne peut pas lui confier de nouvelles tâches. Une création, une suppression ou une synchronisation de plateforme déjà acceptée est conservée puis réessayée. Une création est réessayée pendant 30 minutes à compter de son dernier rapport de progression, une suppression pendant 2 heures, une synchronisation de plateforme jusqu’à 10 tentatives. Au-delà de ce budget, votre connector endpoint marque la commande comme ayant échoué. Toutes les autres commandes de cycle de vie (scale, stop, start, restart, sauvegarde, suppression de sauvegarde) sont refusées plutôt que mises en file d’attente. Une création ou une suppression que vous soumettez alors qu’aucun executor n’est connecté est refusée de la même manière ; seules les commandes déjà acceptées sont réessayées. Une commande que l’executor a déjà acceptée poursuit son exécution jusqu’à son terme ; un résultat qu’il n’a pas pu remonter est transmis lors de sa prochaine connexion.instances create nécessite que votre connector endpoint soit joignable depuis l’hôte sur lequel elle s’exécute. --wait, instances list, instances get et commands list s’appuient sur l’API locale de l’executor : celui-ci doit donc être en cours d’exécution. Le token d’une approbation de plateforme expire selon sa propre horloge, indépendamment de la connectivité ; voir la fenêtre d’approbation.