Skip to main content

​
Composants

Le ClickHouse Connector exécute trois démons, tous intégrés au binaire clicklink :
  • L’executor maintient un canal de commandes sortant vers votre connector endpoint et applique les commandes de cycle de vie que ClickHouse Cloud envoie pour les services qu’il gère dans votre cluster : création, scale, arrêt et démarrage, redémarrage, sauvegarde et suppression de sauvegarde, suppression, ainsi que les mises à jour de plateforme que vous avez approuvées. Chaque action se traduit par un appel à la Kubernetes API. Il n’ouvre aucune connexion vers ClickHouse et ne détient aucun identifiant pour vos buckets ni pour votre IAM. Il s’exécute uniquement en mode managé.
  • Le scraper lit une liste d’autorisation de tables système ClickHouse à intervalle fixe et met les résultats en tampon localement. Il les transmet à votre connector endpoint avec les métadonnées d’infrastructure et le health status.
  • Le troubleshooter maintient un canal de commandes sortant vers votre connector endpoint et exécute des diagnostics en lecture seule pendant une session d’assistance active. En dehors d’une session, il n’exécute rien.
Sur Kubernetes, le Helm chart clicklink-connector déploie les démons dans un namespace de votre choix (clicklink par défaut). L’executor est un Deployment à réplique unique qui conserve l’état de ses commandes sur un volume persistant. Sur une VM Linux, les démons s’exécutent en tant qu’unités systemd clicklink-scraper, clicklink-troubleshooter et clicklink-executor, sous un utilisateur système clicklink non privilégié.

​
Connexions

Toutes les connexions établies par le connector sont sortantes. Voici la liste complète : Chaque requête d’API comporte un en-tête Authorization contenant une signature HMAC-SHA256 portant sur la méthode, le chemin, l’horodatage et une empreinte du corps. Les requêtes ne peuvent être ni rejouées ni altérées en transit, même à l’intérieur du canal TLS. En entrée, chaque démon expose un port de santé local : 8082 pour le scraper, 8084 pour le troubleshooter, 8086 pour l’executor. Ce port dessert /livez, /readyz, /healthz, ainsi que les metrics Prometheus du démon sur /metrics ; il n’existe pas de port distinct pour les metrics. L’API de commandes locale de l’executor n’écoute que sur l’interface de bouclage, et aucun Service ne l’expose. Le seul autre écouteur est la passerelle de sessions optionnelle ; voir sessions d’assistance. ClickHouse Cloud ne se connecte jamais à aucun d’entre eux.

​
Cycle de vie du certificat

Le connector s’authentifie auprès de votre endpoint à l’aide d’un certificat client qu’il obtient et gère lui-même. Les trois démons présentent le même certificat.
  • Inscription. clicklink clctl init génère localement une clé privée ainsi qu’une demande de signature de certificat. La CSR porte l’identifiant de votre organisation comme nom commun et l’hôte de votre endpoint comme unique SAN DNS. La clé privée ne quitte jamais votre environnement.
  • Première émission. init soumet la CSR à l’endpoint de signature d’inscription /v1/pcm/cert/sign, authentifié par HMAC. Si un certificat non expiré existe déjà pour votre organisation, l’endpoint refuse la demande avec une erreur 409. La CLI indique alors comment poursuivre avec le certificat existant ou le remplacer à l’aide de --force.
  • Renouvellement automatique. Les trois démons vérifient la durée de vie du certificat toutes les 12 heures. Dès qu’il ne reste plus que 10 jours, ils demandent un certificat renouvelé de 30 jours via /v1/pcm/cert/renew (mTLS et HMAC). Sur Kubernetes, le certificat renouvelé est réécrit dans le Secret clicklink-mtls grâce à un grant RBAC portant sur un nom exact ; sur une VM, chaque démon l’écrit dans /etc/clicklink/tls. Le renouvellement ne requiert aucune intervention de l’opérateur.
Le connector vérifie le certificat serveur de votre endpoint à partir du magasin de certificats de confiance du système. Lorsque api.tls.ca_file (VM) ou api.tls.caFile (Helm) est défini, la chaîne de CA issue de votre bundle d’inscription est ajoutée à ces racines.

​
Flux de données

​
Ce qui quitte votre environnement

  • Métriques issues des tables système autorisées. L’ensemble par défaut du scraper comprend metric_log, asynchronous_metric_log, tables, warnings et server_settings. La liste d’autorisation est explicitement configurée ; le scraper ne lit rien en dehors de celle-ci.
  • Métadonnées d’infrastructure. Inventaire des services, de l’infrastructure et des sauvegardes synchronisé via l’API. Pour un service managé, il s’agit de son état, du nombre de répliques actuel et attendu, ainsi que de la version du serveur en cours d’exécution et de la version de configuration.
  • État de santé et métriques internes. État des composants et métriques opérationnelles propres au connecteur. Le signal de présence de l’executor indique également si son canal de commande est connecté. Il transmet le résultat de la dernière mise à jour de la plateforme, les versions des composants de la plateforme et l’empreinte du dernier bundle appliqué. Sur une installation en VM, il précise en outre si son bundle d’accès Kubernetes est ok, expiring, expired ou absent.
  • Résultats des commandes. Pour chaque commande de cycle de vie exécutée par l’executor : la progression pendant la convergence, puis le succès ou l’échec avec le texte de l’erreur en cas d’échec.
  • Définitions de service que vous soumettez. clicklink clctl instances create envoie l’identifiant de votre environnement, le cloud et la région, le nom du service, ses noms de buckets et l’ARN du rôle IAM, ainsi qu’une clé d’idempotence. Deux hachages du mot de passe du default user sont également envoyés (SHA-256 et double SHA-1).
  • Sortie de session d’assistance. Résultats des diagnostics en lecture seule exécutés pendant une session que vous avez activée, après masquage.

​
Ce qui ne sort jamais par défaut

  • Le texte brut des requêtes, sur le chemin de scrape. system.query_log est exclu de l’ensemble de scrape par défaut, car ses colonnes de requête peuvent contenir des valeurs littérales et, avec elles, des PII ou des secrets. Le réintégrer relève d’un override propre à chaque déploiement. La liste d’autorisation de tables de session par défaut inclut, elle, system.processes, qui expose le texte des requêtes en cours d’exécution ; consultez sessions d’assistance pour la restreindre.
  • Les données de vos tables et vos sauvegardes. Elles restent dans les buckets de votre compte. L’executor ne détient aucun identifiant vers vos buckets et ne peut pas les lire.
  • Les identifiants. init n’écrit aucun identifiant dans les fichiers de configuration. ClickHouse ne stocke que les hashes bcrypt des mots de passe des utilisateurs du connector, et les secrets restent dans des Kubernetes Secrets ou dans des fichiers lisibles uniquement par root sur l’hôte. Le mot de passe du default user d’un service managé est généré de votre côté et affiché une seule fois ; seuls ses hashes sont transmis. Aucun identifiant ne transite par les chemins de scrape ou de synchronisation.
  • La sortie non masquée du troubleshooter. Tout ce que renvoie le troubleshooter passe par les motifs de masquage (intégrés et les vôtres) avant de sortir. Consultez sessions d’assistance.

​
Frontières de confiance

  • Votre environnement constitue la frontière. ClickHouse Cloud ne reçoit que ce que le connector envoie : scrapes, signaux de présence et statut, résultats de commandes, et ce que renvoie une session d’assistance active. Il n’initie jamais de connexion entrante.
  • La passerelle de session vous appartient. Elle n’est joignable que depuis l’intérieur de votre environnement (via kubectl port-forward sur Kubernetes, ou en local sur une VM), sauf si vous choisissez de l’exposer via un Ingress. ClickHouse Cloud ne s’y connecte jamais.
  • L’accès à ClickHouse est en lecture seule. Les utilisateurs pcm_scraper et pcm_troubleshooter disposent de grants SELECT par table, du READ ON REMOTE du scraper (nécessaire à clusterAllReplicas()) et d’un unique grant SYSTEM FLUSH LOGS réservé au scraper. Aucun grant INSERT, DDL ou de gestion des utilisateurs n’existe. L’executor ne possède aucun utilisateur ClickHouse. La liste exacte figure dans le modèle de privilèges.
  • Le scraper et le troubleshooter ne peuvent pas modifier votre cluster. Leur RBAC provient de Roles dans les namespaces du connector et du service. Ces Roles accordent des verbes en lecture seule sur les resources de charge de travail et un accès par nom exact aux Secrets propres au connector. Aucune permission exec, delete ou patch n’est accordée.
  • L’executor modifie l’état du cluster dans les namespaces de service en tant que pcm-executor. Il crée et supprime les namespaces portant le prefix du service (ns- par défaut) et supprime des pods pour les redémarrer. Dans ces namespaces, il écrit les objets ClickHouseCluster, Backup et ScalingOverride ainsi que les Secrets, ServiceAccounts et Services dont un service a besoin. Il écrit également les Role et RoleBinding qui donnent au scraper un accès en lecture. Une ValidatingAdmissionPolicy refuse toute écriture de ce ServiceAccount en dehors du prefix. Les exceptions, toutes dans son namespace d’origine, sont le renouvellement de son propre jeton, le ConfigMap clicklink-instance-registry et, sur Kubernetes, le certificat client renouvelé dans le Secret mTLS. Lorsqu’elle ne peut pas être évaluée, la policy refuse par défaut. L’admission ne s’applique pas aux lectures : ses lectures de ces familles de resources ne sont donc pas limitées par le prefix.
  • L’executor ne modifie les namespaces de la plateforme qu’en tant que pcm-platform, lors d’une mise à jour que vous avez approuvée. clicklink clctl platform approve génère le jeton de cette identité pour 2 heures ; il n’est jamais renouvelé. Avec ce jeton, l’executor ne peut écrire que des Deployments, Services, ConfigMaps, Secrets, Jobs et PodDisruptionBudgets. Les namespaces, CRDs, ServiceAccounts, le RBAC, les configurations de webhook et d’admission, les PriorityClasses et la StorageClass sont appliqués avec vos identifiants lors de l’approbation. Consultez mises à jour de la plateforme.
  • L’executor ne détient aucun identifiant sur vos buckets ni sur votre IAM. clicklink clctl executor prepare crée les buckets de données et de sauvegarde d’un service ainsi que son rôle IAM. clicklink clctl executor teardown les supprime. Les deux s’exécutent avec vos identifiants. Le rôle ne fait confiance qu’aux pods de ce service : ni l’executor ni ClickHouse ne peuvent donc l’endosser. Ses seuls appels cloud vont à Amazon ECR et STS. Il s’authentifie auprès du registry lorsqu’une synchronisation de la plateforme ou une création récupère un chart. Lors d’une mise à jour de la plateforme, il vérifie les images avec le Role de pull en lecture seule.
  • Network policy. Sur Kubernetes, le chart génère une NetworkPolicy en refus par défaut pour chaque démon. L’egress n’est autorisé que vers le DNS, les CIDRs que vous listez pour votre endpoint de connector et les CIDRs du serveur d’API Kubernetes. Les policies du scraper et du troubleshooter autorisent en outre les Services ClickHouse situés dans les namespaces gérés par l’executor (sélectionnés par le label qu’il y appose) ou que vous listez par nom. La policy de l’executor ne comporte aucune règle ClickHouse. Si les charts d’un bundle de plateforme résident dans Amazon ECR, ajoutez les plages ECR et STS (ou celles de votre miroir de registry) à allowEgressCIDRs. Sans elles, la synchronisation ne peut pas récupérer les charts sous un CNI qui applique les NetworkPolicies. Sans un tel CNI, la policy reste inerte. Consultez configuration.
  • Durcissement de l’hôte sur les VMs. Les unités s’exécutent sous un utilisateur système sans connexion, avec ProtectSystem=strict, NoNewPrivileges, des chemins de configuration en lecture seule et le mode FIPS activé.
Pour connaître les grants et les règles RBAC exacts du connector, consultez la référence modèle de privilèges. Si ClickHouse provisionne et exploite lui-même le cluster, le modèle de confiance diffère ; consultez les pages architecture BYOC et privilèges BYOC.