> ## 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.

# Маршрутизация с учетом реплик

> Направляйте связанные запросы на одну и ту же реплику ClickHouse Cloud для временных таблиц, сеансов и повторного использования кэша

export const PrivatePreviewBadge = () => {
  return <div className="privatePreviewBadge">
            <div className="privatePreviewIcon">
            <svg width="16" height="16" viewBox="0 0 16 16" fill="none" xmlns="http://www.w3.org/2000/svg">
                <path d="M5.33301 6.66667V4.66667V4.66667C5.33301 3.194 6.52701 2 7.99967 2V2C9.47234 2 10.6663 3.194 10.6663 4.66667V4.66667V6.66667" stroke="currentColor" strokeLinecap="round" strokeLinejoin="round" />
                <path d="M8.00033 9.33337V11.3334" stroke="currentColor" strokeLinecap="round" strokeLinejoin="round" />
                <path fillRule="evenodd" clipRule="evenodd" d="M11.333 14H4.66634C3.92967 14 3.33301 13.4033 3.33301 12.6666V7.99996C3.33301 7.26329 3.92967 6.66663 4.66634 6.66663H11.333C12.0697 6.66663 12.6663 7.26329 12.6663 7.99996V12.6666C12.6663 13.4033 12.0697 14 11.333 14Z" stroke="currentColor" strokeLinecap="round" strokeLinejoin="round" />
            </svg>
        </div>
            {'Закрытая предварительная версия в ClickHouse Cloud'}
        </div>;
};

<PrivatePreviewBadge />

Маршрутизация с учетом реплик (также известная как липкие сеансы, липкая маршрутизация или привязка сеанса) направляет связанные запросы в одну и ту же реплику ClickHouse. Используйте ее, если нужно, чтобы [временные таблицы](/ru/sql-reference/statements/create/table#temporary-tables) или [именованное состояние сеанса](/ru/interfaces/http#using-clickhouse-sessions-in-the-http-protocol) оставались доступными между запросами, либо если вы хотите, чтобы связанные запросы повторно использовали локальные кэши одной и той же реплики.

Это механизм best effort, и он не гарантирует изоляции. Масштабирование, обновления и перезапуски могут изменить, на какую реплику попадет данный `session_id`.

<Warning>
  **Требуется HTTP-интерфейс**

  Маршрутизация с учетом реплик применяется на уровне прокси поверх [HTTP/HTTPS-интерфейса](/ru/interfaces/http) с использованием параметра запроса `session_id` (см. ниже). Она **недоступна через собственный протокол** (порт native-протокола, например драйвер [clickhouse-go](/ru/integrations/go) в стандартном режиме native). Клиенты, использующие собственный протокол, должны переключиться на HTTP и передавать `session_id` в каждом запросе. Для clickhouse-go (v2) установите `Protocol: clickhouse.HTTP` и передавайте `session_id` как [настройку](/ru/integrations/language-clients/go/database-sql-api#sessions). Драйвер отправляет его как параметр запроса URL, который хеширует прокси.
</Warning>

<div id="prerequisites">
  ## Предварительные требования
</div>

* Вашему сервису требуется **2 или более реплики**. В сервисе с одной репликой привязывать попросту не к чему.
* Сервис должен быть **запущен**. Вывод неактивного сервиса из спящего режима может изменить, какой реплике соответствует `session_id`.
* По умолчанию доступно на уровне **Enterprise** после выхода возможности в GA.
* Поддерживается в стандартных сервисах ClickHouse Cloud. [BYOC](/ru/cloud/reference/byoc/overview) пока не поддерживается.

<div id="configuring-replica-aware-routing">
  ## Настройка маршрутизации с учетом реплик
</div>

Откройте [тикет в службу поддержки](https://clickhouse.com/support/program) и попросите включить HTTP-маршрутизацию запросов к репликам с закреплением сеанса. Укажите ID вашего сервиса и причину, по которой она вам нужна (временные таблицы, состояние сеанса или повторное использование кэша). После включения начните передавать `?session_id=` в HTTPS-запросах. Перезапуск не требуется.

<div id="http-based-routing">
  ## Маршрутизация на основе HTTP (`session_id`)
</div>

Чтобы закрепить рабочую нагрузку за репликой, задайте параметр запроса `session_id` в [интерфейсе HTTPS](/ru/interfaces/http). Прокси использует согласованное хеширование по этому значению для выбора реплики, поэтому все запросы с одинаковым `session_id` направляются на один и тот же сервер, пока не изменится топология кластера.

Используйте существующее имя хоста сервиса. Никаких специальных sticky-хостов или изменений DNS не требуется.

```bash theme={null}
echo 'SELECT hostName()' | curl \
  -H 'X-ClickHouse-User: default' \
  -H 'X-ClickHouse-Key: <password>' \
  'https://<host>:8443/?session_id=my-workload-1' -d @-
```

Каждый запрос с `session_id=my-workload-1` попадает на одну и ту же реплику. Другое значение `session_id` хэшируется независимо и может попасть на ту же или на другую реплику. Соответствие остаётся постоянным, но выбрать, *на какую именно* реплику попадёт конкретное значение, нельзя.

`session_id` — это любая строка на ваш выбор (имя приложения, идентификатор пользователя или метка рабочей нагрузки). Запросы без `session_id` сохраняют обычную балансировку нагрузки.

Подойдёт любой HTTP-клиент, который умеет добавлять параметр запроса, включая `curl`, [clickhouse-connect](/ru/integrations/python), JDBC/ODBC и другие. Для `clickhouse-go` (v2) используйте режим HTTP, как указано выше.

<div id="check-which-replica">
  ### Проверьте, на какую реплику вы попали
</div>

Снова выполните приведённый выше пример `SELECT hostName()` с тем же `session_id`. Вы должны получить то же имя хоста. Другой `session_id` может направить вас на другую реплику.

<div id="subdomain-based-routing-deprecated">
  ## Маршрутизация на основе поддоменов (устарело)
</div>

<Danger>
  **Устарело**

  Описанный ниже механизм на основе поддоменов **устарел** и больше не включается для новых сервисов. Он не масштабируется (для каждой sticky-конечной точки требуется собственный TLS-сертификат). Вместо него используйте [HTTP-метод `session_id`](#http-based-routing). Если вы уже используете sticky-поддомены, обратитесь в [поддержку](https://clickhouse.com/support/program), чтобы включить маршрутизацию `session_id`. Это обратно несовместимое изменение, и потребуется миграция.
</Danger>

Ранее включение маршрутизации с учётом реплик позволяло использовать подстановочный поддомен для имени хоста сервиса. Для сервиса с именем хоста `abcxyz123.us-west-2.aws.clickhouse.cloud` любое имя хоста, соответствующее шаблону `*.sticky.abcxyz123.us-west-2.aws.clickhouse.cloud` (например, `aaa.sticky.abcxyz123.us-west-2.aws.clickhouse.cloud`), Envoy по хешу направлял на одну и ту же реплику. Исходное имя хоста по-прежнему использовало балансировку нагрузки `LEAST_CONNECTION` — алгоритм маршрутизации по умолчанию.

<div id="limitations-of-replica-aware-routing">
  ## Ограничения маршрутизации с учетом реплик
</div>

<div id="replica-aware-routing-does-not-guarantee-isolation">
  ### Привязка может нарушиться при изменениях сервиса
</div>

Любые изменения в работе сервиса меняют кольцо хеширования маршрутизации. К ним относятся перезапуски серверных подов (обновление версии, сбой, вертикальное масштабирование), а также масштабирование наружу или внутрь. В результате запросы с одинаковым `session_id` могут попасть на другой серверный под. Если вы используете временные таблицы или настройки на уровне сеанса, будьте готовы создать их заново после переназначения.

<div id="not-workload-isolation">
  ### Маршрутизация с учетом реплик не является изоляцией рабочих нагрузок
</div>

Липкая маршрутизация определяет только то, *какая* реплика обрабатывает запрос. Эта реплика по-прежнему может обслуживать и другой трафик. Для выделенных вычислительных ресурсов используйте [compute-compute separation](/ru/cloud/reference/warehouses).

<div id="replica-aware-routing-does-not-work-out-of-the-box-with-private-link">
  ### Private Link и устаревший метод с поддоменом
</div>

Маршрутизация HTTP по `session_id` работает с [частным сетевым подключением](/ru/cloud/security/connectivity/private-networking) на стандартном хосте вашего сервиса. Дополнительные записи DNS не требуются.

Устаревший метод с поддоменом так не работает: нужно добавить DNS для шаблона хоста `*.sticky.*`, а неправильная настройка может привести к неравномерному распределению нагрузки между репликами.

<div id="replica-aware-routing-requires-http">
  ### Для маршрутизации с учетом реплик требуется HTTP-протокол
</div>

Липкая маршрутизация использует параметр запроса `session_id`, который существует только в HTTP/HTTPS-интерфейсе. Собственный бинарный протокол не передает такой параметр, по которому прокси мог бы вычислить хеш, поэтому маршрутизация с учетом реплик недоступна через собственный протокол. На сегодняшний день, чтобы использовать эту возможность, клиентам собственного протокола необходимо перенести соответствующую рабочую нагрузку на HTTP-интерфейс.

<div id="troubleshooting">
  ## Устранение неполадок
</div>

**Запросы по-прежнему попадают на разные реплики при одном и том же `session_id`**

* Убедитесь, что `session_id` — это query parameter в URL (`?session_id=...`), а не HTTP-заголовок.
* После включения немного подождите. Изменения могут вступить в силу меньше чем за минуту.
* Проверьте, не масштабировался и не перезапускался ли сервис недавно; после изменений топологии перепривязка ожидаема. Используйте `SELECT hostName()`, чтобы определить новую привязку.