Конфигурации балансировки
Модуль обработки трафика
Сценарии обработки трафика

Сценарии обработки трафика

Сценарии обработки трафика (сценарии) — внутренний инструмент системы 5А, который позволяет настроить обработку сетевого трафика произвольным образом с помощью инструкций, написанных на скриптовом языке Lua. Поддерживаются как простые сценарии, выполняющие модификацию заголовков и перенаправление трафика, так и более сложные конструкции, включающие в себя вывод HTML-форм и работу с базами данных и API.

Созданные сценарии хранятся в системе 5А и могут использоваться повторно в разных конфигурациях балансировки внутри кластера балансировки.

Управление сценариями

Общее управление сценариями выполняется в разделе Кластеры балансировки → <Название выбранного кластера> → Сценарии.

Общий вид раздела "Сценарии обработки трафика"

Общий вид раздела "Сценарии обработки трафика"

В таблице представлена информация о добавленных в систему 5А сценариях:

  • Название — название сценария, которое используется в системе 5А.
  • Описание — краткое описание назначения и особенностей сценария.

Пользователю системы 5А доступны следующие действия со сценариями:

  • Добавить сценарий — добавление нового сценария в набор сценариев системы 5А.
  • Удалить сценарий — удаление выбранного сценария из набора сценариев системы 5А.

Справочник функций для сценариев

В сценариях балансировки доступен набор готовых высокоуровневых функций, которые управляют направлением запроса на бэкенд и его параметрами. Эти функции вызываются в коде сценария как обычные Lua-функции.

Доступный набор функций зависит от уровня, на котором работает балансировщик:

УровеньОписаниеДоступные функции
HTTP (L7)Балансировка на уровне прикладного протокола HTTP/HTTPSforward, forward_host, set_reencrypt, set_req_header, set_host, set_ssl_name
Stream (L4)Балансировка на транспортном уровне TCP/TLS-passthroughforward, forward_host, set_ssl_name

Все функции вызываются как имя_функции(...).

Функции уровня HTTP (L7)

forward(name) — отправить запрос в группу бэкендов

Направляет HTTP-запрос в одну из предварительно настроенных групп серверов. Группа выбирается по имени, указанному в интерфейсе.

Аргументы:

  • name (строка, обязательный) — имя группы серверов.

Поведение:

  • Запрос направляется на пул серверов из указанной группы с применением всех настроек балансировки, health-проверок и т.д.
  • Если группа с указанным именем не найдена, сценарий завершается с ошибкой forward: unknown group '...'.

Примеры:

-- Направить запрос в группу "backend-api"
forward("backend-api")
 
-- Простой роутинг по пути
if ngx.var.uri:find("^/admin") then
    forward("admin-pool")
else
    forward("web-pool")
end

forward_host(addr, auto_host) — отправить запрос на конкретный адрес

Направляет запрос на указанный адрес напрямую, минуя группы серверов. Полезно для динамической маршрутизации или проксирования на внешние сервисы.

Аргументы:

  • addr (строка, обязательный) — адрес назначения. Может включать схему (http://, https://). Форматы: host, host:port, IP, IP:port, [IPv6]:port.
  • auto_host (булев, необязательный, по умолчанию true) — автоматически подставлять заголовок Host и SNI из адреса.

Поведение:

  • Если в адресе указана схема (https://...), она применяется к соединению с бэкендом (включая переключение на TLS).
  • При auto_host = true и адресе, содержащем доменное имя (не IP), функция автоматически выставляет заголовок Host и SNI равными этому домену.
  • Если адрес — IP-адрес (IPv4, IPv6 или [IPv6]:port), Host и SNI автоматически не изменяются.
  • Если auto_host = false, заголовок Host и SNI остаются без изменений (их можно выставить вручную через set_host и set_ssl_name).

Примеры:

-- Домен: Host и SNI подставятся автоматически
forward_host("https://api.example.com")
 
-- Явный порт
forward_host("https://api.example.com:8443")
 
-- IP: Host/SNI не трогаются
forward_host("http://10.0.0.5:8080")
 
-- Отправить на IP, но Host выставить вручную
forward_host("https://10.0.0.5", false)
set_host("api.example.com")

set_reencrypt(on) — включить/выключить шифрование до бэкенда

Управляет тем, шифруется ли соединение между балансировщиком и бэкендом (re-encrypt). Включает или отключает TLS для исходящего соединения.

Аргументы:

  • on (булев, обязательный) — true включить TLS до бэкенда, false выключить.

Примеры:

-- Шифровать соединение до бэкенда
set_reencrypt(true)
 
-- Обращаться к бэкенду по нешифрованному каналу
set_reencrypt(false)

set_req_header(name, value) — установить заголовок запроса к бэкенду

Устанавливает HTTP-заголовок, который будет отправлен бэкенду. Эта функция является предпочтительным способом установки заголовков, так как гарантирует, что заголовок не будет перебит другими настройками.

Аргументы:

  • name (строка, обязательный) — имя заголовка (например, "X-Request-Id").
  • value (строка, обязательный) — значение заголовка.

Примеры:

set_req_header("X-Env", "prod")
set_req_header("X-Request-Id", ngx.var.request_id)

set_host(host) — выставить заголовок Host

Удобное сокращение для set_req_header("Host", host). Устанавливает заголовок Host, с которым запрос уйдёт на бэкенд.

Аргументы:

  • host (строка, обязательный) — значение заголовка Host.

Пример:

set_host("internal-api.local")

set_ssl_name(name) — выставить SNI для TLS-соединения с бэкендом

Задаёт имя сервера (SNI), которое будет использовано при TLS-рукопожатии с бэкендом, а также для проверки сертификата.

Аргументы:

  • name (строка, обязательный) — доменное имя для SNI.

Пример:

forward_host("https://10.0.0.5", false)
set_ssl_name("api.example.com")
ℹ️

Для корректной работы set_ssl_name в конфигурации балансировки должна быть включена опция Pass through SNI.

Функции уровня Stream (L4)

На уровне L4 работа ведётся с TCP/TLS-соединениями, поэтому HTTP-заголовки и схемы недоступны. Доступен урезанный набор функций.

forward(name) — отправить соединение в группу

Аналог HTTP-версии: направляет TCP-соединение в группу бэкендов по имени. При неизвестном имени — ошибка forward: unknown group '...'.

Аргументы:

  • name (строка, обязательный) — имя группы.

Пример:

forward("db-cluster")

forward_host(addr, auto_sni) — отправить соединение на конкретный адрес

Направляет TCP-соединение на указанный адрес.

Аргументы:

  • addr (строка, обязательный) — адрес назначения (host, host:port, IP:port, [IPv6]:port). Схемы (tcp://, https:// и т.п.) игнорируются.
  • auto_sni (булев, необязательный, по умолчанию true) — автоматически выставлять SNI из адреса.

Поведение:

  • При auto_sni = true и адресе, содержащем доменное имя, SNI автоматически выставляется в это имя (без порта).
  • Если адрес — IP-адрес, SNI не трогается.

Примеры:

-- Домен: SNI выставится как secure.example.com
forward_host("secure.example.com:443")
 
-- IP: SNI не трогается
forward_host("10.0.0.7:5432")

set_ssl_name(name) — выставить SNI

Явно задаёт SNI для исходящего TLS-соединения.

Аргументы:

  • name (строка, обязательный) — доменное имя для SNI.

Пример:

set_ssl_name("secure.example.com")
Удаление политикиДобавление сценария