El enrutamiento con reconocimiento de réplicas (también conocido como sesiones persistentes, enrutamiento con afinidad o afinidad de sesión) dirige las solicitudes relacionadas a la misma réplica de ClickHouse. Úselo cuando necesite que las tablas temporales o el estado de sesión con nombre sigan estando disponibles entre consultas, cuando quiera que las consultas relacionadas reutilicen las cachés locales de la misma réplica o cuando necesite consistencia de lectura después de la escritura entre una escritura y las lecturas posteriores.
Funciona según el mejor esfuerzo y no garantiza el aislamiento. El proxy asigna cada routing value a una réplica. La asignación se mantiene estable mientras no cambie el número de réplicas; al escalar el servicio, el valor puede asignarse a una réplica diferente.
El enrutamiento con reconocimiento de réplicas está disponible en ambas interfaces:
- A través de HTTP/HTTPS, mediante el encabezado
X-ClickHouse-Replica-Tag.
- A través del protocolo nativo, mediante una sobrescritura de TLS Server Name Indication (SNI).
Ambas se habilitan por separado y utilizan el mismo hash consistente detrás del proxy.
Prerrequisitos
- Tu servicio necesita 2 o más réplicas. En un servicio con una sola réplica, no hay ninguna a la que anclarlo.
- Un servicio de nivel Enterprise.
- Compatible con los servicios estándar de ClickHouse Cloud y BYOC
Configurar el enrutamiento con reconocimiento de réplicas
Los clientes Enterprise habilitan el enrutamiento con reconocimiento de réplicas desde la página de configuración del servicio en la ClickHouse Cloud console. Abra su servicio, vaya a Settings y active el toggle de la interfaz que desee:
- Un toggle habilita el enrutamiento basado en HTTP mediante el encabezado
X-ClickHouse-Replica-Tag.
- Otro toggle independiente habilita el enrutamiento por protocolo nativo mediante la sobrescritura de SNI.
Puede habilitar uno de los dos o ambos. No es necesario reiniciar y puede surtir efecto en menos de un minuto.
Los toggles se están desplegando progresivamente en los planes del tier Enterprise. Si aún no están disponibles en su servicio, abra un ticket de soporte indicando el ID de su servicio para que se active la feature antes.
Enrutamiento basado en HTTP
Para asignar una carga de trabajo a una réplica concreta, envíe un encabezado X-ClickHouse-Replica-Tag a través de la interfaz HTTPS. El proxy aplica hash consistente al valor del encabezado, por lo que las solicitudes que lo comparten se dirigen a la misma réplica mientras el número de réplicas no cambie. Un valor distinto se procesa como hash de forma independiente y puede asignarse a la misma réplica o a otra, pero no puede elegir a qué réplica se asigna un valor.
Use el nombre del host de su servicio existente. No se requieren nombres del host sticky especiales ni cambios en DNS. El valor del encabezado puede ser cualquier cadena que elija, como un nombre de aplicación, un ID de usuario o una etiqueta de carga de trabajo. Las solicitudes sin el encabezado mantienen el balanceo de carga normal.
Establezca el encabezado X-ClickHouse-Replica-Tag en cada solicitud:
Para clickhouse-go (v2), configure Protocol: clickhouse.HTTP y pase el encabezado mediante la opción de conexión HttpHeaders.
X-ClickHouse-Replica-Tag proporciona afinidad con una réplica sin crear una sesión HTTP de ClickHouse. Las solicitudes concurrentes pueden reutilizar la misma etiqueta sin encontrarse con SESSION_IS_LOCKED.
Routing mediante protocolo nativo
A través del protocolo nativo, pase el routing value como nombre de servidor TLS con el formato <routing-value>.sticky.<host>. Conéctese al nombre del host habitual de su service como de costumbre. ClickHouse Client toma el routing value a través de --tls-sni-override:
--host es el nombre del host habitual de su service, --secure activa TLS y --tls-sni-override transporta el routing value. TLS es obligatorio. No se necesita ningún certificate adicional ni entry de DNS.
Consistencia de lectura después de la escritura
En un service con múltiples réplicas, una escritura realizada en una réplica puede no ser visible en las demás hasta que la replicación se ponga al día. Envíe la escritura con un routing value y reutilice ese mismo valor en las lecturas posteriores. El proxy dirige ambas operaciones a la misma réplica, de modo que lee su propia escritura incluso mientras las demás réplicas siguen rezagadas. Este patrón funciona para workloads que escriben y leen de inmediato los mismos datos, como aplicaciones interactivas o jobs de ETL que validan los inserts antes de continuar.
También resulta útil tras un cambio de schema que aún no se ha replicado, ya que reutilizar el routing value mantiene los inserts en una réplica que ya cuenta con el nuevo schema.
Por HTTP, reutilice el valor del encabezado:
A través del protocolo nativo, reutilice la sobrescritura de SNI:
Para obtener garantías más amplias en todas las réplicas, también puede definir select_sequential_consistency con el valor 1 en ClickHouse Cloud.
Compruebe qué réplica se ha utilizado
Ejecute de nuevo uno de los ejemplos SELECT hostName() con el mismo routing value. Debería obtener el mismo nombre del host mientras el número de réplicas no cambie. Un routing value diferente puede asignarse a otra réplica.
Limitaciones del enrutamiento con reconocimiento de réplicas
La afinidad cambia cuando cambia el número de réplicas
El escalado horizontal, tanto de ampliación como de reducción, cambia el anillo hash de enrutamiento. Las solicitudes que comparten el mismo routing value pueden acabar llegando a una réplica diferente. Si depende de tablas temporales o de configuración a nivel de sesión, prepárese para volver a crearlas tras una reasignación. SELECT hostName() siempre le indica en qué réplica se encuentra.
El enrutamiento con reconocimiento de réplicas no es aislamiento de cargas de trabajo
El enrutamiento con afinidad solo controla qué réplica gestiona una petición. Esa réplica puede seguir atendiendo otro tráfico. Para tener cómputo dedicado, usa compute-compute separation.
Redes privadas
Tanto el enrutamiento basado en HTTP como el del protocolo nativo funcionan con redes privadas en el nombre del host habitual de tu servicio. No se requieren registros DNS adicionales.
El enrutamiento por protocolo nativo requiere TLS
El enrutamiento por protocolo nativo requiere TLS, por lo que debe pasar --secure. Una conexión nativa sin cifrar mantiene el balanceo de carga normal.
Solución de problemas
Las consultas siguen llegando a réplicas distintas con el mismo routing value
- Confirme que el toggle de la interfaz que está utilizando está habilitado en la página de configuración del servicio. Los métodos HTTP y nativo se habilitan por separado.
- A través de HTTP, confirme que cada solicitud incluya el encabezado
X-ClickHouse-Replica-Tag y que todas las solicitudes utilicen exactamente el mismo valor.
- A través del protocolo nativo, confirme que
--secure está configurado y que --tls-sni-override tiene el formato <routing-value>.sticky.<host>.
- Espere unos instantes tras la activación. Los cambios pueden tardar menos de un minuto en aplicarse.
- Compruebe si el número de réplicas ha cambiado recientemente; es normal que se reasignen después del escalado. Use
SELECT hostName() para descubrir la nueva correspondencia.
Errores de certificado a través del protocolo nativo
- Confirme que
--host es el nombre del host habitual de su servicio y que el routing value se pasa mediante --tls-sni-override en lugar de --host.
