> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-vortex-format.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# 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
export const Image = ({img, alt, size = "lg", background}) => {
const normalizedSize = ["sm", "md", "lg"].includes(size) ? size : "lg";
const backgroundColor = background === "white" ? "white" : background === "black" ? "rgb(31 31 28)" : undefined;
return ;
};
export const PrivatePreviewBadge = () => {
return ;
};
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](/es/products/bring-your-own-cloud/connector/onboarding#install-and-enroll) para ver el flujo completo y la [CLI reference](/es/products/bring-your-own-cloud/connector/reference/cli#init) 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.
```bash theme={null}
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.
```bash theme={null}
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 `. El nombre generado se registra en `/_prepare/.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---00-Role`. Los nombres de bucket predeterminados son `-clickhouse-data-` y `-clickhouse-backup-`; `--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-`), 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 `/_prepare/.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 ` 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.
```bash theme={null}
clicklink clctl instances create \
--from-prepare ./clicklink-access/_prepare/.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.
```bash theme={null}
sudo clicklink clctl instances create \
--from-prepare /etc/clicklink/access/executor/_prepare/.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 (state provisioning)` y una sugerencia `watch:`. `` 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`.
```bash theme={null}
clicklink clctl instances get --name --cluster
```
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:
```bash theme={null}
kubectl -n 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 --cluster ` 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](#delete-a-service) 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 ` 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](/es/products/bring-your-own-cloud/connector/platform-updates) 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](#delete-a-service).
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](/es/products/bring-your-own-cloud/connector/reference/cli#instances-scale) 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](/es/products/bring-your-own-cloud/connector/support-sessions) 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-`, igual que para una instance que hayas registrado tú mismo:
```bash theme={null}
printf '%s\n' "$CH_DEFAULT_PASSWORD" | clicklink clctl troubleshoot access provision --target helm \
--target-namespace "${CONNECTOR_NAMESPACE}" \
--instance --instance-namespace ns- \
--server --ch-admin-password-stdin \
--apply-ch-grants --ch-pod --ch-pod-namespace ns-
```
`$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](/es/products/bring-your-own-cloud/connector/configuration#clickhouse-instances).
```bash theme={null}
printf '%s\n' "$CH_DEFAULT_PASSWORD" | sudo clicklink clctl troubleshoot access provision --provider local \
--instance --instance-namespace ns- \
--server --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](/es/products/bring-your-own-cloud/connector/operations#uninstall-kubernetes).
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:
```bash theme={null}
kubectl -n "${CONNECTOR_NAMESPACE}" port-forward deployment/clicklink-connector-executor 9999:9999 &
clicklink clctl executor teardown --instance --config clicklink-config.yaml --output-dir ./clicklink-access
```
```bash theme={null}
sudo clicklink clctl executor teardown --instance
```
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=`, 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](/es/products/bring-your-own-cloud/connector/platform-updates#the-approval-window).