Le routage tenant compte des répliques (également appelé sessions sticky, routage sticky ou affinité de session) achemine les requêtes liées vers la même réplique ClickHouse. Utilisez-le lorsque des tables temporaires ou un état de session nommé doivent rester accessibles d’une requête à l’autre, lorsque vous souhaitez que des requêtes liées réutilisent les caches locaux d’une même réplique, ou lorsque vous avez besoin d’une cohérence lecture après écriture entre une écriture et les lectures qui suivent.
Il est fourni au mieux et ne garantit pas l’isolation. Le proxy associe chaque valeur de routage à une réplique. Cette association reste stable tant que le nombre de répliques ne change pas ; la mise à l’échelle du service peut toutefois associer cette valeur à une autre réplique.
Le routage tenant compte des répliques est disponible via les deux interfaces :
- Via HTTP/HTTPS, à l’aide de l’en-tête
X-ClickHouse-Replica-Tag.
- Via le protocole natif, à l’aide d’un override de l’extension TLS Server Name Indication (SNI).
Les deux s’activent séparément et reposent sur le même hachage cohérent derrière le proxy.
Prérequis
- Votre service doit disposer d’au moins 2 répliques. Sur un service à réplique unique, il n’y a rien à épingler.
- Un service de tier Enterprise.
- Pris en charge sur les services ClickHouse Cloud standard et BYOC
Configurer le routage tenant compte des répliques
Les clients Enterprise activent le routage tenant compte des répliques depuis la page des paramètres du service dans la ClickHouse Cloud console. Ouvrez votre service, rendez-vous dans Settings, puis activez le toggle correspondant à l’interface souhaitée :
- Un toggle active le routage HTTP basé sur l’en-tête
X-ClickHouse-Replica-Tag.
- Un second toggle active le routage en protocole natif via l’override SNI.
Activez l’un, l’autre, ou les deux. Aucun redémarrage n’est nécessaire et la prise d’effet peut prendre moins d’une minute.
Ces toggles sont progressivement déployés sur les plans de l’Enterprise tier. S’ils ne sont pas encore disponibles sur votre service, ouvrez un ticket auprès du support en indiquant votre service ID afin que la feature soit activée plus tôt.
Routage HTTP
Pour associer une charge de travail à une réplique, envoyez un en-tête X-ClickHouse-Replica-Tag via l’interface HTTPS. Le proxy applique un hachage cohérent à la valeur de l’en-tête : les requêtes partageant cette valeur sont donc dirigées vers la même réplique tant que le nombre de répliques reste inchangé. Une valeur différente est hachée indépendamment et peut être associée à la même réplique ou à une autre, mais vous ne choisissez pas à quelle réplique une valeur est associée.
Utilisez le nom d’hôte existant de votre service. Aucun nom d’hôte sticky spécifique ni aucune modification DNS ne sont nécessaires. La valeur de l’en-tête peut être n’importe quelle chaîne de votre choix, par exemple un nom d’application, un ID utilisateur ou un label de charge de travail. Les requêtes sans cet en-tête conservent l’équilibrage de charge habituel.
Définissez l’en-tête X-ClickHouse-Replica-Tag pour chaque requête :
Pour clickhouse-go (v2), définissez Protocol: clickhouse.HTTP et transmettez l’en-tête à l’aide de l’option de connexion HttpHeaders.
X-ClickHouse-Replica-Tag assure une affinité avec une réplique sans créer de session HTTP ClickHouse. Les requêtes concurrentes peuvent réutiliser le même tag sans rencontrer l’erreur SESSION_IS_LOCKED.
Routage via le protocole natif
Avec le protocole natif, transmettez la valeur de routage sous la forme d’un nom de serveur TLS du type <routing-value>.sticky.<host>. Connectez-vous au nom d’hôte habituel de votre service, comme d’ordinaire. ClickHouse Client récupère la valeur de routage via --tls-sni-override :
--host correspond au nom d’hôte habituel de votre service, --secure active TLS et --tls-sni-override transporte la valeur de routage. TLS est obligatoire. Aucun certificat ni entry DNS supplémentaire n’est nécessaire.
Cohérence lecture après écriture
Sur un service comptant plusieurs répliques, une écriture effectuée sur une réplique peut ne pas être visible sur les autres tant que la réplication n’a pas rattrapé son retard. Envoyez votre écriture avec une valeur de routage, puis réutilisez cette même valeur lors des lectures qui suivent. Le proxy dirige les deux vers la même réplique : vous lisez ainsi votre propre écriture, même si les autres répliques accusent encore du retard. Ce modèle convient aux workloads qui écrivent puis relisent immédiatement les mêmes données, comme les applications interactives ou les jobs ETL qui valident les insertions avant de poursuivre.
Il est également utile après une modification de schéma qui n’a pas encore été répliquée, car la réutilisation de la valeur de routage maintient les insertions sur une réplique disposant déjà du nouveau schéma.
En HTTP, réutilisez la valeur de l’en-tête :
Avec le protocole natif, réutilisez l’override SNI :
Pour des garanties plus étendues sur l’ensemble des répliques, vous pouvez également définir select_sequential_consistency sur 1 dans ClickHouse Cloud.
Vérifier quelle réplique est utilisée
Exécutez à nouveau l’un des exemples SELECT hostName() avec la même valeur de routage. Vous devriez obtenir le même nom d’hôte tant que le nombre de répliques reste inchangé. Une valeur de routage différente peut être associée à une autre réplique.
Limites du routage tenant compte des réplicas
La persistance change lorsque le nombre de répliques change
La mise à l’échelle horizontale, à la hausse comme à la baisse, modifie l’anneau de hachage du routage. Des requêtes partageant la même valeur de routage peuvent alors être dirigées vers une autre réplique. Si vous vous appuyez sur des tables temporaires ou des paramètres au niveau de la session, soyez prêt à les recréer après une réaffectation. SELECT hostName() vous indique toujours sur quelle réplique vous vous trouvez.
Le routage tenant compte des réplicas n’est pas une isolation des charges de travail
Le routage sticky contrôle uniquement quelle réplique traite une requête. Cette réplique peut tout de même servir d’autres requêtes. Pour un compute dédié, utilisez la séparation compute-compute.
Mise en réseau privée
Le routage HTTP comme le routage par protocole natif fonctionnent avec la mise en réseau privée sur le nom d’hôte habituel de votre service. Aucune entrée DNS supplémentaire n’est requise.
Le routage en protocole natif nécessite TLS
Le routage en protocole natif nécessite TLS : utilisez donc l’option --secure. Une connexion native non chiffrée conserve l’équilibrage de charge ordinaire.
Résolution des problèmes
Les requêtes sont toujours dirigées vers différentes répliques avec la même valeur de routage
- Vérifiez que le toggle correspondant à l’interface que vous utilisez est activé sur la page des paramètres du service. Les méthodes HTTP et native s’activent séparément.
- En HTTP, vérifiez que chaque requête inclut l’en-tête
X-ClickHouse-Replica-Tag, et que chaque requête utilise exactement la même valeur.
- Avec le protocole natif, vérifiez que
--secure est défini et que --tls-sni-override a la forme <routing-value>.sticky.<host>.
- Attendez un instant après l’activation. La modification peut prendre moins d’une minute avant de prendre effet.
- Vérifiez si le nombre de répliques a récemment changé ; un remappage est attendu après une mise à l’échelle. Utilisez
SELECT hostName() pour déterminer la nouvelle association.
Erreurs de certificat avec le protocole natif
- Vérifiez que
--host correspond bien au nom d’hôte habituel de votre service, et que la valeur de routage est transmise via --tls-sni-override plutôt que via --host.
