O roteamento com reconhecimento de réplicas (também conhecido como sessões persistentes, roteamento sticky ou afinidade de sessão) direciona requisições relacionadas para a mesma réplica do ClickHouse. Use-o quando precisar que tabelas temporárias ou estado de sessão nomeado permaneçam acessíveis entre consultas, quando quiser que consultas relacionadas reutilizem os caches locais da mesma réplica ou quando precisar de consistência de leitura após gravação entre uma gravação e as leituras subsequentes.
É uma abordagem de melhor esforço e não garante isolamento. O proxy mapeia cada valor de roteamento para uma réplica. O mapeamento permanece estável enquanto o número de réplicas não mudar; o escalonamento do serviço pode mapear o valor para outra réplica.
O roteamento com reconhecimento de réplicas está disponível em ambas as interfaces:
- Por HTTP/HTTPS, usando o cabeçalho
X-ClickHouse-Replica-Tag.
- Pelo protocolo nativo, usando um override de TLS Server Name Indication (SNI).
Ambos são habilitados separadamente e usam o mesmo hash consistente por trás do proxy.
Pré-requisitos
- Seu serviço precisa de 2 ou mais réplicas. Em um serviço com apenas uma réplica, não há nada ao que se vincular.
- Um serviço do tier Enterprise.
- Compatível com os serviços padrão do ClickHouse Cloud e com o BYOC
Configurando o roteamento com reconhecimento de réplicas
Clientes Enterprise habilitam o roteamento com reconhecimento de réplicas na página de configurações do service no ClickHouse Cloud console. Abra seu service, vá em Settings e ative o toggle da interface desejada:
- Um toggle habilita o roteamento baseado em HTTP pelo cabeçalho
X-ClickHouse-Replica-Tag.
- Um toggle separado habilita o roteamento pelo protocolo nativo via override de SNI.
Habilite um deles ou ambos. Não é necessário reiniciar, e o efeito pode levar menos de um minuto para ser aplicado.
Os toggles estão sendo disponibilizados gradualmente nos planos do tier Enterprise. Se ainda não estiverem disponíveis no seu service, abra um ticket de suporte com o ID do seu service para que o recurso seja ativado antes.
Roteamento baseado em HTTP
Para direcionar uma carga de trabalho a uma réplica específica, envie o cabeçalho X-ClickHouse-Replica-Tag na interface HTTPS. O proxy usa hash consistente do valor do cabeçalho; assim, as requisições que compartilham esse valor são direcionadas à mesma réplica enquanto o número de réplicas permanecer inalterado. Um valor diferente recebe um hash independente e pode ser direcionado à mesma réplica ou a outra, mas você não escolhe a qual réplica um valor é mapeado.
Use o hostname do service existente. Não são necessários hostnames sticky especiais nem alterações de DNS. O valor do cabeçalho pode ser qualquer string à sua escolha, como o nome de uma aplicação, o ID de um usuário ou o label da carga de trabalho. Requisições sem o cabeçalho continuam usando o load balancing normal.
Defina o cabeçalho X-ClickHouse-Replica-Tag em cada requisição:
Para clickhouse-go (v2), defina Protocol: clickhouse.HTTP e passe o cabeçalho usando a opção de conexão HttpHeaders.
X-ClickHouse-Replica-Tag fornece afinidade com a réplica sem criar uma sessão HTTP do ClickHouse. Solicitações simultâneas podem reutilizar a mesma tag sem encontrar SESSION_IS_LOCKED.
Roteamento via protocolo nativo
Pelo protocolo nativo, passe o valor de roteamento como nome de servidor TLS no formato <routing-value>.sticky.<host>. Conecte-se normalmente ao hostname habitual do seu service. O ClickHouse Client recebe o valor de roteamento por meio de --tls-sni-override:
--host é o hostname normal do seu service, --secure ativa o TLS e --tls-sni-override carrega o valor de roteamento. O TLS é obrigatório. Não é necessário nenhum certificado adicional nem entrada de DNS.
consistência de leitura após gravação
Em um service com múltiplas réplicas, uma escrita feita em uma réplica pode não ficar visível nas demais até que a replicação se atualize. Envie sua escrita com um valor de roteamento e reutilize esse mesmo valor nas leituras seguintes. O proxy direciona ambas para a mesma réplica, de modo que você lê sua própria escrita mesmo enquanto as outras réplicas ainda estão defasadas. Esse padrão funciona para workloads que escrevem e logo em seguida releem os mesmos dados, como aplicações interativas ou jobs de ETL que validam inserts antes de prosseguir.
Também ajuda após uma alteração de schema que ainda não foi replicada, já que reutilizar o valor de roteamento mantém os inserts em uma réplica que já possui o novo schema.
Via HTTP, reutilize o valor do cabeçalho:
No protocolo nativo, reutilize o override de SNI:
Para garantias mais amplas entre todas as réplicas, você também pode definir select_sequential_consistency como 1 no ClickHouse Cloud.
Verifique qual réplica foi acessada
Execute novamente um dos exemplos SELECT hostName() com o mesmo valor de roteamento. Você deverá obter o mesmo hostname enquanto o número de réplicas permanecer inalterado. Um valor de roteamento diferente pode ser mapeado para outra réplica.
Limitações do roteamento com reconhecimento de réplicas
A afinidade muda quando a contagem de réplicas muda
O aumento ou a redução de escala altera o hash ring de roteamento. Requisições que compartilham o mesmo valor de roteamento podem, então, ser encaminhadas para uma réplica diferente. Se você depende de tabelas temporárias ou de configurações da sessão, esteja preparado para recriá-las após um remapeamento. SELECT hostName() sempre informa em qual réplica você está.
O roteamento com reconhecimento de réplicas não é isolamento de workload
O roteamento sticky controla apenas qual réplica atende a uma solicitação. Essa réplica ainda pode atender outro tráfego. Para processamento dedicado, use compute-compute separation.
Rede privada
Tanto o roteamento baseado em HTTP quanto o do protocolo nativo funcionam com rede privada no hostname padrão do seu serviço. Nenhuma entrada DNS adicional é necessária.
O roteamento por protocolo nativo exige TLS
O roteamento por protocolo nativo exige TLS, portanto passe --secure. Uma conexão nativa sem criptografia mantém o load balancing normal.
Solução de problemas
As consultas continuam sendo direcionadas a réplicas diferentes com o mesmo valor de roteamento
- Confirme que o toggle da interface que você está usando está habilitado na página de configurações do serviço. Os métodos HTTP e protocolo nativo são habilitados separadamente.
- Por HTTP, confirme que cada solicitação inclui o cabeçalho
X-ClickHouse-Replica-Tag e que cada solicitação usa exatamente o mesmo valor.
- Pelo protocolo nativo, confirme que
--secure está definido e que --tls-sni-override tem a forma <routing-value>.sticky.<host>.
- Aguarde um pouco após a ativação. Pode levar menos de um minuto para surtir efeito.
- Verifique se o número de réplicas mudou recentemente; é esperado que haja remapeamento após o escalonamento. Use
SELECT hostName() para descobrir o novo mapeamento.
Erros de certificado pelo protocolo nativo
- Confirme que
--host é o hostname normal do seu serviço e que o valor de roteamento é passado por --tls-sni-override, e não por --host.
