Sessions d’assistance

Une session d’assistance accorde à ClickHouse un accès temporaire à des fins de diagnostic via le ClickHouse Connector. Cette page explique ce qu’est une session, comment l’activer et la désactiver, ce que les ingénieurs du support ClickHouse peuvent faire pendant celle-ci et comment l’auditer.

Qu’est-ce qu’une session d’assistance ?

Une session d’assistance est une fenêtre de temps limitée pendant laquelle l’outil de diagnostic accepte les commandes des ingénieurs du support ClickHouse. En dehors d’une session, il refuse toute commande, même lorsque son WebSocket sortant est connecté. Il n’existe aucune autre voie d’exécution, et ClickHouse ne peut pas ouvrir une session à votre place. ClickHouse Cloud ne se connecte jamais à votre environnement ; il reçoit uniquement ce que l’outil de diagnostic envoie sur son canal sortant. Les sessions ne régissent que les diagnostics. Les commandes de cycle de vie des services en mode managé transitent par le canal distinct de l’executor, qu’une session d’assistance n’ouvre ni ne contrôle ; voir services managés. Vous contrôlez les sessions par deux biais :

La passerelle de sessions, une API authentifiée intégrée à l’outil de diagnostic. Elle expose POST /v1/clctl/session/enable, POST /v1/clctl/session/disable et GET /v1/clctl/session/status. Chaque appel requiert un OIDC ID token de courte durée dont l’adresse e-mail figure dans votre liste d’autorisation des opérateurs.
Le fichier de session local sur les installations en VM Linux, écrit sur l’hôte avec un accès root.

Le transport de la passerelle dépend de la cible. Une passerelle sur VM expose un TLS auto-signé dont chaque opérateur épingle l’empreinte. Une passerelle Kubernetes écoute localement dans le pod en HTTP ; vous y accédez via kubectl port-forward (le tunnel s’appuie sur le TLS de l’API server) ou via un Ingress qui termine le TLS avec un certificat émis par une CA. Vous définissez votre posture de session, y compris la liste d’autorisation des opérateurs, lors de clicklink clctl init.

Activation et désactivation des sessions

Kubernetes
VM Linux

La passerelle écoute sur le port 8443 du pod de l’outil de diagnostic. Avec un accès au cluster, accédez-y via un port-forward :

CONNECTOR_NAMESPACE='clicklink'   # l’espace de noms du connecteur choisi lors de l’initialisation
kubectl -n "${CONNECTOR_NAMESPACE}" port-forward statefulset/clicklink-connector-troubleshooter 8443:8443

Ensuite, dans un autre terminal, activez une session :

clicklink clctl troubleshoot session enable \
  --gateway-url http://localhost:8443 \
  --duration 4h \
  --reason "<référence du ticket>"

Vérifiez-la ou désactivez-la de la même façon :

clicklink clctl troubleshoot session status --gateway-url http://localhost:8443
clicklink clctl troubleshoot session disable --gateway-url http://localhost:8443

L’identité OIDC de l’appelant doit figurer dans la liste d’autorisation des opérateurs. Les appelants non authentifiés ou non autorisés reçoivent une erreur 401 ou 403, et la passerelle consigne la tentative. Pour permettre aux opérateurs de travailler sans identifiants de cluster, exposez la passerelle via l’Ingress facultatif du chart, qui termine TLS à l’aide d’un certificat émis par une CA ; consultez la configuration.

Avec un accès root sur l’hôte, gérez directement la session. Le démon et la CLI lisent et écrivent le state file /var/lib/clicklink/session.json de façon atomique :

sudo clicklink clctl troubleshoot session enable --duration 4h --reason "<référence du ticket>"
sudo clicklink clctl troubleshoot session status
sudo clicklink clctl troubleshoot session disable

La passerelle est également disponible sur une VM pour les appelants sans accès root. Elle utilise un certificat TLS auto-signé ; chaque utilisateur de session enregistre donc une fois l’empreinte du certificat de la passerelle :

clicklink clctl troubleshoot gateway trust \
  --gateway-url https://<hôte-vm>:8443 \
  --gateway-fingerprint <empreinte-sha256>

L’empreinte est stockée dans ~/.clicklink/clctl.yaml. Une connexion échoue de manière sécurisée lorsque le certificat présenté ne correspond pas à cette empreinte. Si la passerelle présente plutôt un certificat émis par votre propre CA, indiquez ce CA bundle avec --gateway-ca sur chaque commande de session.

Expiration de la session

Les sessions expirent automatiquement. La durée par défaut est de 4 heures ; session enable --duration accepte une durée pouvant aller jusqu’à 24 heures. À l’expiration ou dès que vous exécutez session disable, l’outil de diagnostic cesse d’accepter les commandes. La désactivation révoque l’accès immédiatement : aucun redémarrage ni aucune coordination avec ClickHouse.

Liste d’autorisation des opérateurs

Chaque appel vers la passerelle est autorisé selon une liste d’adresses e-mail d’opérateurs. La comparaison porte sur l’adresse e-mail attestée par le jeton OIDC validé, et jamais sur une valeur fournie par le client.

Kubernetes : définissez clctl.gateway.allowedOperators dans votre superposition de values. Le chart génère la liste dans une ConfigMap ; ainsi, une modification des valeurs suivie de helm upgrade renouvelle la liste d’autorisation sans redémarrer le pod.
VM Linux : la liste d’autorisation se trouve dans /etc/clicklink/allowed-operators.txt, écrit par clicklink clctl init à partir des adresses e-mail d’opérateurs que vous fournissez.

Sur les deux cibles, la passerelle relit le fichier lors de la requête suivante dès que 30 secondes se sont écoulées depuis la dernière lecture. Les modifications prennent effet sans redémarrage.

Ce que les opérateurs peuvent faire pendant une session

Tant qu’une session est active, les ingénieurs du support ClickHouse peuvent exécuter deux types de commandes. Le SQL en lecture seule s’exécute sur vos clusters sous l’utilisateur pcm_troubleshooter, dont les grants sont limités à la liste d’autorisation de tables de la session. L’outil de diagnostic rejette par ailleurs tout statement qui ne commence pas par SELECT, WITH, SHOW, DESCRIBE ou EXPLAIN. Cet utilisateur ne dispose que de grants SELECT table par table, sans aucun privilège d’écriture, de DDL ni d’administration. La liste d’autorisation par défaut couvre les tables system telles que system.parts, system.merges, system.replicas, system.metrics et system.settings. system.query_log et system.text_log ne peuvent pas y être ajoutées : le démon refuse toute configuration qui les mentionne, de sorte qu’aucun grant n’est jamais provisionné sur ces tables. La liste d’autorisation par défaut inclut en revanche system.processes, dont la colonne query affiche le texte des statements en cours d’exécution. Retirez-la de troubleshooter.allowedTables (surcouche Helm) ou de troubleshooter.allowed_tables (configuration file de la VM) si le texte des requêtes en cours ne doit jamais être visible pendant une session. Les vues Kubernetes en lecture seule correspondent aux verbes get, list et watch sur les pods, le statut des pods, les logs des pods, les services, les configmaps, les événements, les PersistentVolumeClaims, les deployments, les statefulsets et les replicasets dans les namespaces accordés. Les ensembles d’accès sont rattachés aux ServiceAccounts Kubernetes sur les deux cibles d’installation. En l’absence d’ensemble provisionné, l’outil de diagnostic refuse purement et simplement les commandes de type kubectl. L’executor provisionne le scraper pour un service managé, mais pas l’outil de diagnostic ; voir sessions d’assistance pour un service managé. Le RBAC de l’outil de diagnostic ne contient aucune permission exec, delete ou patch : les opérateurs ne peuvent donc pas ouvrir de shell dans vos pods ni modifier quoi que ce soit au cours d’une session. L’énumération complète des grants et du RBAC figure dans la référence modèle de privilèges.

Audit log

Chaque commande exécutée pendant une session est ajoutée à /var/log/clicklink/troubleshoot-audit.log sous la forme d’un objet JSON par ligne (NDJSON). Les commandes bloquées sont elles aussi enregistrées, le champ blocked_by en précisant la raison (par exemple session inactive). submitted_by correspond à l’Organization ID sur le canal de commande : votre propre org ID. L’ingénieur ClickHouse concerné est enregistré côté ClickHouse Cloud, et non dans ce fichier. Une entrée de commande de session se présente ainsi :

{
  "timestamp": "2026-06-22T22:30:00.123456789Z",
  "command_id": "11111111-2222-4333-8444-555555555555",
  "submitted_by": "<org-id>",
  "command_type": "sql",
  "command_text": "SELECT database, table, active, count() FROM system.parts GROUP BY ALL",
  "instance_id": "analytics",
  "status": "completed",
  "duration_ms": 42,
  "output_lines": 12
}

status indique le résultat de la commande : completed, error ou rejected. Les appels passant par la passerelle sont journalisés séparément. Chaque appel, y compris ceux qui sont rejetés, est émis sous la forme d’une ligne structurée clctl.gateway dans le log propre de l’outil de diagnostic : le journal sur une VM, le log du conteneur sur Kubernetes. Cette ligne contient submitted_by (l’e-mail attesté par le jeton validé, jamais une valeur fournie par le client) et command_type (clctl.session.enable, clctl.session.disable ou clctl.session.status). Elle contient également reason (le --reason passé à l’activation), remote_addr et status. status vaut ok, unauthorized, forbidden, rate_limited, bad_request, conflict ou error : les accès refusés apparaissent donc eux aussi dans le log. Les modifications locales de session sur une VM ne constituent pas des entrées d’audit log. L’utilisateur hôte à l’origine de l’appel est enregistré dans enabled_by au sein de /var/lib/clicklink/session.json et affiché par session status. Sur une VM, consultez l’audit log avec clicklink clctl troubleshoot audit tail. Sur Kubernetes, le log se trouve à l’intérieur du pod de l’outil de diagnostic, et l’image du conteneur ne comporte aucun shell : invoquez donc le reader intégré du binary via kubectl exec :

CONNECTOR_NAMESPACE='clicklink'   # the connector namespace you chose at init
kubectl -n "${CONNECTOR_NAMESPACE}" exec statefulset/clicklink-connector-troubleshooter -- \
  /clicklink clctl troubleshoot audit tail

Le journal d’audit est un simple fichier situé dans votre environnement ; transmettez-le à votre propre SIEM comme n’importe quel autre journal d’hôte ou de conteneur.

Masquage

Tout ce que renvoie l’outil de diagnostic est masqué avant de quitter votre environnement. Des modèles intégrés couvrent les adresses IPv4 et IPv6, les jetons Bearer, les clés d’accès AWS, les adresses e-mail, les JWT, les clés privées SSH et les informations d’identification incluses dans les chaînes de connexion. Vous pouvez les étendre ou les remplacer dans /etc/clicklink/redaction-patterns.yaml ; une entrée portant le même nom qu’un modèle intégré le remplace. Le démon refuse de démarrer si le fichier de modèles n’est pas valide, et clicklink clctl preflight le valide : ainsi, une configuration de masquage défectueuse échoue explicitement.

Architecture : toutes les connexions établies par le connecteur et les flux de données associés aux sessions.
Configuration : paramètres de passerelle, de liste d’autorisation et de masquage.
FAQ : questions sur la révocation, l’audit et l’egress des données.

Premiers pas

Services et infrastructure

Bring Your Own Cloud

Données et intégrations

Se connecter et exécuter des requêtes

Gestion des accès

Sécurité et conformité

Supervision et sauvegardes

Outils et agents d’IA

API Cloud

Facturation

Assistance

ClickHouse Private

Qu’est-ce qu’une session d’assistance ?

Activation et désactivation des sessions

Expiration de la session

Liste d’autorisation des opérateurs

Ce que les opérateurs peuvent faire pendant une session

Audit log

Masquage

​Qu’est-ce qu’une session d’assistance ?

​Activation et désactivation des sessions

​Expiration de la session

​Liste d’autorisation des opérateurs

​Ce que les opérateurs peuvent faire pendant une session

​Audit log

​Masquage

​Pages associées

Qu’est-ce qu’une session d’assistance ?

Activation et désactivation des sessions

Expiration de la session

Liste d’autorisation des opérateurs

Ce que les opérateurs peuvent faire pendant une session

Audit log

Masquage

Pages associées