Servicios administrados

Cree, supervise y dé de baja servicios de ClickHouse que ClickHouse Cloud opera en su cluster a través del executor del conector

En modo administrado, el conector ejecuta un tercer componente: el executor. A través de él, ClickHouse Cloud opera los servicios de ClickHouse en su Kubernetes cluster. Esta página explica cómo crear un servicio, cómo consultar su estado, qué hace ClickHouse Cloud con él y cómo se retira.

​

Qué hace el modo administrado

El executor es un demonio incluido en el mismo binary clicklink que el scraper y el solucionador de problemas. Mantiene un canal WebSocket saliente hacia el endpoint del conector y recibe comandos de ciclo de vida desde ClickHouse Cloud. Aplica cada comando al único Kubernetes cluster para el que está configurado e informa del resultado por ese canal. Al igual que los demás componentes, solo establece conexiones salientes: ClickHouse Cloud nunca se conecta hacia el interior de tu cluster, y la API local del executor se enlaza al loopback.

El modo administrado está disponible en Amazon EKS con S3 storage durante el private preview. Tu account team lo habilita al registrar tu entorno. init rechaza un contexto de kube que no apunte a un EKS cluster.

Cada servicio necesita tres cloud resources de tu propiedad: un bucket de datos, un bucket de copias de seguridad y un IAM role que los ClickHouse pods asumen para acceder a ellos. Los creas con tus propias credentials antes de que exista el servicio y los eliminas una vez que desaparece. El executor no guarda credentials de tus buckets ni de IAM, y nunca elimina datos. Sus únicas llamadas a la nube van a Amazon ECR y STS. Inicia sesión en el registry cuando una sincronización o una creación de plataforma descarga un chart, y comprueba las imágenes con el role de descarga read-only durante una actualización de plataforma. No realiza llamadas a S3 ni a IAM. Para cada servicio crea un Service de Kubernetes de tipo LoadBalancer, que el load-balancer controller de tu cluster materializa como un NLB interno en tu account.

En una VM, el executor se ejecuta como el systemd unit clicklink-executor junto a los otros dos. En Kubernetes es una Implementación de una sola réplica en el Espacio de nombres del conector. Expone el estado de salud y las metrics en el puerto 8086, y su API local en 127.0.0.1:9999.

​

Habilitar el modo gestionado

El modo gestionado se elige durante el enroll: pase --managed a clicklink clctl init o responda al prompt en un terminal. En una VM, init toma el cluster del kubeconfig de este host (--cluster-name cuando contiene más de un EKS cluster) y concede el acceso cluster-wide del executor de forma inline. En Kubernetes, pase --egress-cidrs con los CIDR de su endpoint del conector para que el chart deje su NetworkPolicy de denegación predeterminada enabled.

La instalación en sí no cambia. Consulte el onboarding para ver el flujo completo y la CLI reference para conocer los indicadores.

​

Crear un servicio

La creación de servicios a través del endpoint del conector se habilita por entorno; consúltalo con tu account team antes de empezar.

Crear un servicio requiere dos comandos. prepare crea todo lo necesario en tu lado; instances create envía la solicitud de creación a ClickHouse Cloud a través del endpoint del conector. ClickHouse Cloud genera la definición del servicio y envía la creación al executor por su canal saliente. El executor la aplica a tu cluster e informa del resultado.

Solo prepare necesita AWS credentials: crea los S3 buckets y el IAM role. instances create necesita la configuración y las credentials del conector, y accede a la API local del executor únicamente para --wait. En una VM, ejecuta ambos como root en el host del conector. En Kubernetes, ejecuta ambos desde una workstation con un contexto de kube para el cluster gestionado:

• prepare necesita una copia de la configuración del conector (--config), un kubectl port-forward a la API local del executor y un --output-dir con permisos de escritura. Verifica el nombre del servicio con el executor y se niega a ejecutarse si no logra alcanzarlo.
• Cuando este host no tiene los archivos de credentials indicados en la configuración, instances create los lee desde los Secrets clicklink-hmac y clicklink-mtls y anuncia cada lectura. Añade --connector-namespace cuando el espacio de nombres del conector no sea clicklink. Solo instances create cuenta con este fallback.

1. Prepare el servicio

   Kubernetes

   CONNECTOR_NAMESPACE='clicklink'   # el espacio de nombres del connector que eligió en init
   kubectl -n "${CONNECTOR_NAMESPACE}" get configmap clicklink-connector-executor \
     -o jsonpath='{.data.config\.yaml}' > clicklink-config.yaml
   kubectl -n "${CONNECTOR_NAMESPACE}" port-forward deployment/clicklink-connector-executor 9999:9999 &
   clicklink clctl executor prepare --config clicklink-config.yaml --output-dir ./clicklink-access
   

   Conserve el directorio de salida: contiene el cuerpo de creación y el registro de nombre que leen instances create y cualquier retry.

   VM Linux

   sudo clicklink clctl executor prepare --config /etc/clicklink/config.yaml
   

   El comando ejecuta cuatro pasos en orden y se detiene en el primer fallo:

   1. Nombre. Elige un nombre de service o valida el que usted indique con --instance <name>. El nombre generado se registra en <output-dir>/_prepare/<eks-cluster-name>.name y la siguiente ejecución lo retoma, de modo que un retry reutiliza los buckets y el role de la primera ejecución. Con --new-name se elige otro. El comando rechaza un nombre que el executor todavía mantenga, o cuyo espacio de nombres ya contenga un ClickHouse cluster.
   2. Storage. Crea los buckets de datos y de copia de seguridad y el IAM role CH-S3-<name>-<region>-00-Role. Los nombres de bucket predeterminados son <cluster>-clickhouse-data-<rand> y <cluster>-clickhouse-backup-<rand>; --data-bucket y --backup-bucket los sobrescriben. Con --role-arn se verifica un role aportado por usted y no se escribe nada en IAM.
   3. Conceder y aplicar. En una VM, genera el paquete de access del executor para el espacio de nombres del service (ns-<name>), aplica su RBAC y registra el service en el registry del executor. En Kubernetes este paso se omite: el executor se ejecuta con el ServiceAccount de su pod y registra el service por sí mismo cuando llega la creación.
   4. Resumen. Genera la password del usuario default y escribe el cuerpo de creación en <output-dir>/_prepare/<name>.create.json (mode 0600; solo contiene los hash de la password). Imprime el siguiente comando en una línea Next:.

   prepare imprime la password del usuario default una sola vez, en stderr. Ni el cuerpo de creación ni --output json la contienen, y ClickHouse Cloud solo recibe sus hash. Guárdela antes de continuar. Una nueva ejecución que encuentre el cuerpo de creación conserva los hash ya escritos y así lo indica.

   Use --context <name> cuando su kubeconfig contenga varios contextos; el contexto debe apuntar al EKS cluster indicado en executor.cluster en la configuración. --dry-run ejecuta todos los pasos sin crear ni escribir nada. El paso de hash usa SHA-1, que Go rechaza bajo GODEBUG=fips140=only; ejecute prepare en un host sin esa configuración.

2. Envíe la creación

   Kubernetes

   clicklink clctl instances create \
     --from-prepare ./clicklink-access/_prepare/<name>.create.json \
     --config clicklink-config.yaml \
     --wait
   

   Deja abierto el reenvío de puertos de prepare: --wait sondea el executor a través de él.

   Linux VM

   sudo clicklink clctl instances create \
     --from-prepare /etc/clicklink/access/executor/_prepare/<name>.create.json \
     --config /etc/clicklink/config.yaml \
     --wait
   

   El comando envía el cuerpo preparado al endpoint del conector con las credenciales propias del conector. Imprime created <spoken-name> (state provisioning) y una sugerencia watch:. <spoken-name> es el nombre que asignó ClickHouse Cloud (por ejemplo, amberaws-kq-42), no el nombre del service que preparaste. La sugerencia watch: y todos los comandos clctl usan el nombre de tu service.

   Es seguro reintentar con las mismas entradas. La clave de idempotencia se deriva de forma predeterminada de tu entorno y del nombre del service, por lo que volver a enviar la solicitud devuelve la primera creación.

   --wait sondea la API local del executor cada 10 segundos hasta que el service esté running, durante un máximo de --wait-timeout (valor predeterminado: 30m). Falla de inmediato, indicando el error registrado, cuando el executor registra una creación fallida para ese nombre o el service pasa a terminating, terminated o stale.

3. Verificar

   clicklink clctl instances get --name <name> --cluster <eks-cluster-name>
   

   El service está listo cuando su status es running. Su usuario default toma la contraseña que imprimió prepare. --cluster también puede provenir de la variable de entorno CLCTL_CLUSTER.

​

Estado

El executor responde a las consultas de estado desde su API local, que se enlaza a 127.0.0.1:9999 y no cuenta con autenticación propia. En una VM, ejecute los comandos en el host. En Kubernetes, abra primero un reenvío de puertos y apunte los comandos hacia él:

kubectl -n <connector-namespace> port-forward deployment/clicklink-connector-executor 9999:9999
clicklink clctl instances list --endpoint http://127.0.0.1:9999

clicklink clctl instances list imprime en formato JSON todos los servicios que conoce el executor. clicklink clctl instances get --name <name> --cluster <eks-cluster-name> imprime uno solo, junto con el almacenamiento con el que se creó. El executor deduce el estado a partir del recurso ClickHouseCluster del servicio (réplicas de servidor listas frente a las esperadas) y lo actualiza cada sync_interval (30 segundos de forma predeterminada):

• provisioning: aún no hay ninguna réplica de servidor lista, o el ClickHouseCluster todavía no existe
• running: todas las réplicas de servidor esperadas están listas
• degraded: algunas réplicas de servidor están listas, pero no todas
• terminating: el executor está desinstalando el servicio
• terminated: el espacio de nombres del servicio ya no existe
• stale: el servicio se eliminó del registro del executor sin una operación de borrado; --wait y teardown lo tratan como terminated

Un servicio terminado sigue apareciendo en la lista, con su almacenamiento, hasta que teardown elimina sus recursos en la nube.

El executor registra todos los comandos que le envía ClickHouse Cloud. clicklink clctl commands list los imprime, filtrados con --status (pending, running, completed, failed), --action (por ejemplo, create_instance) o --cluster. clicklink clctl commands get <id> imprime un comando concreto con su etapa y su resultado. El campo result de un comando fallido contiene el error: por qué una creación no convergió, o qué actualización de la plataforma está a la espera de tu aprobación.

​

Ciclo de vida del servicio

Una vez que existe un servicio, ClickHouse Cloud lo opera a través del executor. Los comandos que envía son:

• Escalado. ClickHouse Cloud establece un número fijo de réplicas, limitado por un ajuste de ClickHouse Cloud (20 en la configuración predeterminada). No hay autoescalado.
• Detener e iniciar. Al detenerlo, los servidores se escalan a cero y se mantiene Keeper; al iniciarlo, se restauran los recuentos de réplicas. Los datos permanecen en tus buckets durante todo el proceso.
• Reinicio. Del servicio completo, de su Keeper o de un solo pod de Kubernetes.
• Copias de seguridad. ClickHouse Cloud las activa; se almacenan en tu bucket de copias de seguridad y, al eliminarlas, se borran de allí.
• Actualizaciones de versión y cambios de configuración. ClickHouse Cloud vuelve a generar la definición del servicio con la nueva versión o el nuevo ajuste. Llega como un comando create_instance, por lo que commands list --action create_instance también muestra las actualizaciones. El executor la aplica y espera a que las réplicas vuelvan a estar listas.
• Eliminación. Descrita en eliminar un servicio.

Las actualizaciones de versión y los cambios de configuración no requieren la aprobación del cliente. ClickHouse Cloud los aplica a un servicio administrado igual que aplica un escalado o un reinicio: reenvía la definición y el executor hace converger el cluster hacia ella.

Las creaciones, los escalados y los inicios se completan de forma asíncrona. El executor informa de que el comando está en ejecución en cuanto aplica la definición y envía un informe de progreso cada 2 minutos. Informa del resultado final una vez que las réplicas del servidor están listas. Si no lo están en un plazo de 2 horas, informa de que el comando ha fallado; si se levantan más tarde, devuelve el servicio al estado running.

Los subcomandos instances scale, instances patch e instances delete envían comandos directamente a la API local del executor, sin pasar por ClickHouse Cloud. Ejecútalos solo cuando tu account team te lo pida; la CLI reference describe cada uno.

​

Sesiones de soporte para un servicio administrado

El executor integra el scraper en cada servicio que crea. No aprovisiona el solucionador de problemas, por lo que una sesión de soporte no podrá ejecutar diagnósticos en un servicio administrado hasta que lo hagas. Aprovisiónalo una vez por cada servicio, con el espacio de nombres del servicio ns-<name>, igual que para una instance que hayas registrado tú mismo:

Kubernetes

printf '%s\n' "$CH_DEFAULT_PASSWORD" | clicklink clctl troubleshoot access provision --target helm \
  --target-namespace "${CONNECTOR_NAMESPACE}" \
  --instance <name> --instance-namespace ns-<name> \
  --server <kubernetes-api-server-url> --ch-admin-password-stdin \
  --apply-ch-grants --ch-pod <clickhouse-pod-or-label-selector> --ch-pod-namespace ns-<name>

$CH_DEFAULT_PASSWORD es la contraseña del usuario default que imprimió prepare. El comando se autentica con ella para aplicar los grants de SQL y no la solicita de forma interactiva. Luego añade el par Secret y ServiceAccount a troubleshooter.accessBundles y ejecuta helm upgrade, como se muestra en añadir instances de ClickHouse.

VM de Linux

printf '%s\n' "$CH_DEFAULT_PASSWORD" | sudo clicklink clctl troubleshoot access provision --provider local \
  --instance <name> --instance-namespace ns-<name> \
  --server <kubernetes-api-server-url> --ch-admin-password-stdin

$CH_DEFAULT_PASSWORD es la contraseña del usuario default que imprimió prepare.

Otorga los permisos al ClickHouse user mediante SQL, como se indica arriba. Un usuario añadido con --ch-user-via cr no perduraría: ClickHouse Cloud es el propietario de la definición del servicio y la vuelve a aplicar. Cuando se elimina el servicio, el executor elimina el paquete del solucionador de problemas en una VM. En Kubernetes, el Secret del paquete y el ServiceAccount permanecen hasta que los elimines, como se indica en desinstalación.

​

Eliminar un servicio

No existe un comando de eliminación para clientes a través del endpoint del conector: solicita a tu account team que elimine el servicio. ClickHouse Cloud lo termina y el executor elimina el workload y su espacio de nombres (terminating y, después, terminated). No se toca nada en AWS: los buckets, sus datos y el IAM role permanecen hasta que los elimines.

Una vez que el servicio informa terminated, desmonta lo que creó prepare. Ejecuta teardown donde ejecutaste prepare, con las mismas AWS credentials. En Kubernetes, eso significa la misma workstation, la misma copia de configuración y el mismo directorio de salida, además de un reenvío de puertos abierto hacia el executor:

Kubernetes

kubectl -n "${CONNECTOR_NAMESPACE}" port-forward deployment/clicklink-connector-executor 9999:9999 &
clicklink clctl executor teardown --instance <name> --config clicklink-config.yaml --output-dir ./clicklink-access

VM Linux

sudo clicklink clctl executor teardown --instance <name>

El comando lee el registro que el executor tiene del servicio: dónde residen sus datos y qué role tenía. Elimina el IAM role que creó prepare y hace que el executor olvide el servicio, con lo que libera el nombre. En una VM también elimina los objetos RBAC del servicio a todo el cluster, el paquete de acceso local y la entrada del registry.

De forma predeterminada conserva los datos y las copias de seguridad del servicio. Reetiqueta el bucket conservado de clicklink:deployed-name a clicklink:retained-from=<name>, de modo que un servicio recreado con el mismo nombre nunca lo herede, y el resumen indica dónde están los datos. Para eliminarlos, añade --delete-data --delete-backups --yes al mismo comando.

--delete-data y --delete-backups vacían y eliminan los buckets que indican; después no hay recuperación posible. Confirma los nombres de los buckets en el paso de registro antes de añadir --yes.

Sin --yes, la ejecución se detiene tras el paso de registro e indica los nombres de los buckets que vaciaría. --dry-run lo lee todo y no escribe nada. Un role que aportaste con --role-arn, o un bucket que prepare no creó, se informa como conservado y nunca se toca. La ejecución se rechaza mientras el espacio de nombres del servicio siga alojando un cluster de ClickHouse. Lee todo antes de eliminar nada, por lo que una ejecución rechazada no cambia nada.

​

Cuando el conector está desconectado

Los servicios en ejecución no dependen del executor. El ClickHouse operator de tu cluster los mantiene en funcionamiento, y un conector desconectado no interrumpe nada que ya esté atendiendo queries.

Mientras no haya ningún executor conectado, ClickHouse Cloud no puede asignarle trabajo nuevo. Una creación, eliminación o sincronización de plataforma que ya se haya aceptado se conserva y se reintenta. Una creación se reintenta durante 30 minutos desde su último informe de progreso; una eliminación, durante 2 horas; y una sincronización de plataforma, hasta 10 intentos. Superado ese margen, el endpoint de tu conector marca el comando como fallido. Cualquier otro comando del ciclo de vida (scale, stop, start, restart, copia de seguridad, eliminación de copia de seguridad) se rechaza en lugar de ponerse en cola. Una creación o eliminación que envíes mientras no haya ningún executor conectado se rechaza del mismo modo; solo se reintentan los comandos ya aceptados.

Un comando que el executor ya haya aceptado se ejecuta hasta completarse; un resultado que no pudo comunicar se envía en su siguiente conexión.

instances create necesita que el endpoint de tu conector sea accesible desde el host donde se ejecuta. --wait, instances list, instances get y commands list necesitan la API local del executor, por lo que el executor debe estar en ejecución. El token de una aprobación de plataforma caduca según su propio reloj, independientemente de la conectividad; consulta la ventana de aprobación.