Skip to main content

​
Componentes

El ClickHouse Connector ejecuta tres demonios, todos integrados en el binary clicklink:
  • El executor mantiene un canal de comandos saliente hacia el endpoint del conector y aplica los comandos de ciclo de vida que ClickHouse Cloud envía para los servicios que administra en su cluster. Dichos comandos son: creación, escalado, detención e inicio, reinicio, copia de seguridad y eliminación de copias de seguridad, eliminación y las actualizaciones de plataforma que usted haya aprobado. Cada acción es una llamada a la Kubernetes API. No abre ninguna connection a ClickHouse ni mantiene credenciales de sus buckets ni de IAM. Solo se ejecuta en modo administrado.
  • El scraper lee una lista de permitidos de tablas del sistema de ClickHouse en un interval fijo y almacena los resultados en un búfer local. Luego los envía al endpoint del conector junto con metadata de infrastructure y el health status.
  • El solucionador de problemas mantiene un canal de comandos saliente hacia el endpoint del conector y ejecuta diagnósticos de solo lectura durante una sesión de soporte activa. Fuera de una sesión no ejecuta nada.
En Kubernetes, el gráfico de Helm clicklink-connector despliega los demonios en un espacio de nombres que usted elija (clicklink de forma predeterminada). El executor es una Implementación de una sola réplica que conserva su estado de comandos en un volume persistente. En una Linux VM, los demonios se ejecutan como las systemd units clicklink-scraper, clicklink-troubleshooter y clicklink-executor bajo un usuario de sistema clicklink sin privilegios.

​
Conexiones

Todas las conexiones que establece el connector son salientes. La lista completa: Cada solicitud a la API incluye una cabecera Authorization con una firma HMAC-SHA256 sobre el método, la ruta, la marca de tiempo y un hash del cuerpo. Las solicitudes no pueden reproducirse ni alterarse en tránsito, ni siquiera dentro del canal TLS. En sentido entrante, cada demonio expone un único puerto local de health: 8082 para el scraper, 8084 para el solucionador de problemas y 8086 para el executor. Ese puerto sirve /livez, /readyz, /healthz y las métricas de Prometheus del demonio en /metrics; no hay un puerto de métricas independiente. La API de comandos local del executor se vincula únicamente a loopback y ningún Service la expone. El único listener adicional es el gateway de sesión opcional; consulta sesiones de soporte. ClickHouse Cloud nunca se conecta a ninguno de ellos.

​
Ciclo de vida del certificado

El connector se autentica ante tu endpoint con un certificado de cliente que obtiene y gestiona por sí mismo. Los tres demonios presentan el mismo certificado.
  • Inscripción. clicklink clctl init genera localmente una private key y una solicitud de firma de certificado (CSR). La CSR incluye tu Organization ID como nombre común y el host de tu endpoint como único SAN DNS. La private key nunca sale de tu entorno.
  • Primera emisión. init envía la CSR al endpoint de firma de inscripción en /v1/pcm/cert/sign, autenticado con HMAC. Si ya existe un certificado no expirado para tu organización, el endpoint la rechaza con un 409. La CLI muestra entonces cómo continuar con el certificado existente o sustituirlo mediante --force.
  • Renovación automática. Los tres demonios comprueban la duración del certificado cada 12 horas. Cuando quedan 10 días, solicitan un certificado renovado de 30 días a través de /v1/pcm/cert/renew (mTLS más HMAC). En Kubernetes, el certificado renovado se vuelve a escribir en el secreto clicklink-mtls mediante un grant de RBAC de nombre exacto; en una VM, cada demonio lo escribe en /etc/clicklink/tls. La renovación no requiere ninguna acción del operador.
El connector verifica el server certificate de tu endpoint contra el system trust store. Cuando se establece api.tls.ca_file (VM) o api.tls.caFile (Helm), la CA chain de tu paquete de inscripción se añade a esas raíces.

​
Flujo de datos

​
Qué sale de su entorno

  • Métricas de tablas del sistema incluidas en la lista de permitidas. El conjunto predeterminado del scraper es metric_log, asynchronous_metric_log, tables, warnings y server_settings. La lista de permitidas es una configuración explícita; el scraper no lee nada fuera de ella.
  • Metadatos de infraestructura. Inventario de servicios, infraestructura y copias de seguridad sincronizado mediante la API. En el caso de un servicio gestionado, se trata de su estado, el número actual y previsto de réplicas, y la versión del servidor en ejecución y la versión de la configuración.
  • Estado y métricas del propio sistema. Estado de los componentes y métricas operativas del propio conector. El heartbeat del executor también informa de si su canal de comandos está conectado. Incluye el resultado de la última actualización de la plataforma, las versiones de los componentes de la plataforma y el resumen criptográfico del último paquete aplicado. En una instalación sobre VM añade si su paquete de acceso a Kubernetes está ok, expiring, expired o ausente.
  • Resultados de comandos. Para cada comando de ciclo de vida que ejecuta el executor: el progreso mientras converge y, después, el éxito o el fallo con el texto del error en caso de fallo.
  • Definiciones de servicio que usted envía. clicklink clctl instances create envía el ID de su entorno, la nube y la región, el nombre del servicio, los nombres de sus buckets y el ARN del rol de IAM, y una clave de idempotencia. También envía dos hash de la contraseña del usuario default (SHA-256 y doble SHA-1).
  • Resultados de la sesión de Support. Resultados de diagnósticos de solo lectura ejecutados durante una sesión que habilitó, tras la eliminación de información confidencial.

​
Qué nunca sale de forma predeterminada

  • El texto sin procesar de las consultas, en la ruta de scrape. system.query_log queda excluido del conjunto de scrape predeterminado porque sus columnas de consulta pueden contener valores literales y, con ellos, PII o secretos. Volver a añadirlo es una sobrescritura por implementación. La lista de permitidos predeterminada de tablas de sesión sí incluye system.processes, que muestra el texto de las consultas activas; consulta sesiones de soporte para recortarla.
  • Los datos de tus tablas y las copias de seguridad. Permanecen en buckets de tu cuenta. El executor no dispone de credenciales para tus buckets ni puede leerlos.
  • Las credenciales. init no escribe ninguna credencial en los archivos de configuración. ClickHouse almacena únicamente hashes bcrypt de las contraseñas de los usuarios del connector, y los secretos permanecen en secretos de Kubernetes o en archivos legibles solo por root en el host. La contraseña del usuario default de un servicio gestionado se genera en tu lado y se muestra una sola vez; solo se envían sus hashes. Nada en las rutas de scrape o de sincronización transmite credenciales.
  • La salida sin redactar del solucionador de problemas. Todo lo que devuelve el solucionador de problemas pasa por patrones de redacción (los integrados y los tuyos propios) antes de salir. Consulta sesiones de soporte.

​
Límites de confianza

  • Tu entorno es el límite. ClickHouse Cloud recibe únicamente lo que el connector envía: scrapes, latidos y estado, resultados de comandos y lo que devuelve una sesión de soporte activa. Nunca inicia una conexión hacia dentro.
  • El gateway de sesión es tuyo. Solo es accesible dentro de tu entorno (mediante kubectl port-forward en Kubernetes, o localmente en una VM), salvo que decidas exponerla a través de un Ingress. ClickHouse Cloud nunca se conecta a ella.
  • El acceso a ClickHouse es de solo lectura. Los usuarios pcm_scraper y pcm_troubleshooter tienen grants SELECT por tabla, el READ ON REMOTE del scraper (necesario para clusterAllReplicas()) y un único grant SYSTEM FLUSH LOGS exclusivo del scraper. No existen grants de INSERT, DDL ni de administración de usuarios. El executor no tiene usuario de ClickHouse. El listado exacto está en el modelo de privilegios.
  • El scraper y el solucionador de problemas no pueden modificar tu cluster. Su RBAC proviene de Roles en los espacios de nombres del connector y del servicio. Esos Roles conceden verbos de solo lectura sobre los recursos de workload y acceso por nombre exacto a los secretos propios del connector. No hay permisos de exec, delete ni patch.
  • El executor modifica el estado del cluster en los espacios de nombres de los servicios como pcm-executor. Crea y elimina espacios de nombres que llevan el prefijo del servicio (ns- de forma predeterminada) y elimina pods para reiniciarlos. Dentro de esos espacios de nombres escribe los objetos ClickHouseCluster, Backup y ScalingOverride y los secretos, ServiceAccounts y Services que necesita un servicio. También escribe el Role y el RoleBinding que otorgan al scraper acceso de lectura. Una ValidatingAdmissionPolicy deniega cualquier escritura de ese ServiceAccount fuera del prefijo. Las excepciones, todas en su espacio de nombres de origen, son la renovación de su propio token, el ConfigMap clicklink-instance-registry y, en Kubernetes, el certificado de cliente renovado en el secreto de mTLS. La política falla de forma cerrada cuando no puede evaluarse. La admission no se ejecuta en las lecturas, por lo que sus lecturas de esas familias de recursos no están limitadas por el prefijo.
  • El executor modifica los espacios de nombres de la plataforma únicamente como pcm-platform, durante una actualización que hayas aprobado. clicklink clctl platform approve emite el token de esa identidad con una validez de 2 horas; nunca se renueva. Con él, el executor solo puede escribir Implementaciones, Services, ConfigMaps, secretos, Jobs y PodDisruptionBudgets. Los espacios de nombres, las CRD, los ServiceAccounts, el RBAC, las configuraciones de webhook y de admission, las PriorityClasses y la StorageClass se aplican con tus credenciales durante la aprobación. Consulta actualizaciones de plataforma.
  • El executor no posee credenciales para tus buckets ni para IAM. clicklink clctl executor prepare crea los buckets de datos y de copia de seguridad de un servicio y su rol de IAM. clicklink clctl executor teardown los elimina. Ambos se ejecutan con tus credenciales. El rol solo confía en los pods de ese servicio, de modo que ni el executor ni ClickHouse pueden asumirlo. Sus únicas llamadas a la nube van a Amazon ECR y STS. Inicia sesión en el registry cuando una sincronización de plataforma o una creación descarga un chart. Durante una actualización de plataforma comprueba las imágenes con el rol de pull de solo lectura.
  • Política de red. En Kubernetes, el chart genera una NetworkPolicy de denegación predeterminada para cada demonio. La salida solo se permite hacia DNS, los CIDR que indiques para el endpoint de tu connector y los CIDR del servidor de la API de Kubernetes. Las políticas del scraper y del solucionador de problemas también permiten los ClickHouse Services en los espacios de nombres que administra el executor (seleccionados mediante la etiqueta que les asigna) o los que tú enumeres por nombre. La política del executor no tiene ninguna regla de ClickHouse. Si los charts de un paquete de plataforma residen en Amazon ECR, añade los rangos de ECR y STS (o el espejo de tu registry) a allowEgressCIDRs. Sin ellos, la sincronización no podrá descargar los charts bajo un CNI que aplique políticas. Sin un CNI que aplique políticas, la política queda inerte. Consulta configuración.
  • Endurecimiento del host en VM. Las unidades se ejecutan como un usuario de sistema sin inicio de sesión, con ProtectSystem=strict, NoNewPrivileges, rutas de configuración de solo lectura y el modo FIPS habilitado.
Para conocer los grants y las reglas de RBAC exactas del connector, consulta la referencia del modelo de privilegios. Si ClickHouse aprovisiona y opera el cluster por sí mismo, el modelo de confianza es distinto; consulta las páginas arquitectura de BYOC y privilegios de BYOC.