Пaраметр upstream#

Параметр upstream доступен для использования в сервисе через объявление одним из следующих параметров (или и их взаимосвязи):

Обязательные параметры:

use_main_upstream_groups

В значении параметра определяется, использовать ли upstream_groups основного прокси (т.е. сервиса типа service_main_proxy).
```
use_main_upstream_groups: true
```
Параметр use_main_upstream_groups НЕ МОЖЕТ быть объявлен в сервисе типа service_main_proxy.

Тип параметра:
- true;
- false.
upstream_groups

Параметр описывает группы upstream'ов, на которые проксируются сообщения. Параметр рекомендован к применению в случае, если проксирование осуществляется с использованием сервиса типа service_main_proxy, или при условии использования сервиса отличного от типа service_cache или service_main_proxy и значения false параметра use_main_upstream_groups.
```
use_main_upstream_groups: false
```
Пример использования upstream_groups:
```
service_main_proxy:
  - id: 1
    ...
    upstream_groups:
      - id: extgw_v1
        !include: upstream-v1.yml
        ...
    ...
```
Пример использования upstream_groups (один из сервисов типа http_proxy использует отличную от сервиса main_proxy группу upstream'ов):
```
service_main_proxy:
  - id: 1
    ...
    upstream_groups:
      - id: <value>
        !include: upstream-v1.yml
        ...
    ...
service_http_proxy:
  - id: hp_1
    ...
    use_main_upstream_groups: false
    upstream_group_id: <value_name_group>
    upstream_groups:
      - id: <value_name_group>
        servers:
          - server: <value_ip_address>
  - id: 2
    ...
    upstream_group_id: <value>
    use_main_upstream_groups: true
```
Тип параметра: последовательность параметров и их значения.

Обязательные параметры:
- id
  
  В значении параметра указывается идентификатор upstream группы. Идентификатор может быть строкой, числом, или их комбинацией. В качестве разделителя слов необходимо использовать знак нижнее подчеркивание " _ ".
  
  Значение параметра id должно быть уникальным.
  
  Тип параметра: текстовое значение.
```
- id: 1_one
- id: two_2
```
- servers
  
  В значении параметра указывается список нод для upstream'а.
  
  Если в секции servers присутствует только один upstream, то параметры max_fails, fail_timeout и slow_start игнорируются и сервер никогда не считается недоступным.
  
  Тип параметра: последовательность параметров и их значения.
  
  Опциональные параметры:
  - service_id
    
    В значении параметра указывается идентификатор сервиса.
    
    Обязательно в случае:
    - server is None.
    Тип параметра: текстовое значение.
    servers: - service_id: <id_one> ... - service_id: <id_two> ...
    По умолчанию: не имеет значения по умолчанию.
  - (2.1) service_type
    
    В значении параметра указывается тип сервиса.
    
    Обязательно в случае:
    - service_id is not None.
    Тип параметра: текстовое значение.
    - service_main_proxy;
    - service_http_proxy;
    - service_http_kafka_proxy;
    - service_http_mq_proxy;
    - service_gost_proxy.
    По умолчанию: не имеет значения по умолчанию.
  - server
    
    В значении параметра указывается имя сервера или ip-адрес с портом. Порт по умолчанию - 80.
    
    ОБЯЗАТЕЛЬНО в случае:
    - service_id is None.
    Тип параметра: строковое значение.
    servers: - server: 10.x.x.x:80 ... - server: localhost ...
    По умолчанию: не имеет значения по умолчанию.
  - weight
    
    В значении параметра указывается "веса" сервера.
    
    Тип параметра: целочисленное значение.
    
    По умолчанию:
    weight: 1
  - max_conns
    
    В значении параметра определяется максимальное количество одновременных подключений к upstream.
    
    Тип параметра: целочисленное значение.
    
    0 - ограничений нет.
    
    По умолчанию:
    max_conns: 0
  - max_fails
    
    Число неудачных попыток работы с сервером, которые должны произойти в течение времени, заданного параметром fail_timeout, чтобы сервер считался недоступным на период времени, также заданный параметром fail_timeout. Нулевое значение отключает учет попыток. Что считается неудачной попыткой, определяется, например, директивой next_upstream.
    
    Тип параметра: целочисленное значение.
    
    По умолчанию:
    max_fails: 1
  - fail_timeout
    
    Задает:
    1. время, в течение которого должно произойти заданное число неудачных попыток работы с сервером для того, чтобы сервер считался недоступным; По умолчанию - 10s.
    2. и время, в течение которого сервер будет считаться недоступным. По умолчанию - 10s.
    Тип параметра: текстовое значение с суффиксом:
    - ms - миллисекунда;
    - s - секунда;
    - m - минута;
    - h - час;
    - d - день;
    - w - неделя;
    - M - месяц (30 дней);
    - y - год (365 дней).
    По умолчанию:
    fail_timeout: 10s
  - backup
    
    В значении параметра указывается имя сервера, который будет использоваться в качестве резервной копии. Если все базовые серверы станут недоступны, запросы будут перенаправлены сюда.
    upstream_groups: - id: back_1 servers: - server: 127.0.0.1:10016 weight: 5 max_fails: 1 fail_timeout: 10s max_conns: 5 slow_start: 15s - server: 127.0.0.1:10015 max_fails: 1 fail_timeout: 10s - server: 127.0.0.1:10017 backup: true
    В этом примере 127.0.0.1:10016 имеет вес 5, а два других сервера имеют вес по умолчанию - 1. Сервер 127.0.0.1:10017, помечен как backup и не принимает запросы. Это продолжится до тех пор, пока двое других серверов живы. При такой конфигурации весов 5 из 6ти запросов будут направлены в 127.0.0.1:10016, а 1 в 127.0.0.1:10015.
    
    Тип параметра:
    - true;
    - false.
    По умолчанию: не имеет значения по умолчанию.
  - slow_start
    
    В значении параметра устанавливается время, в течение которого сервер восстанавливает свой "вес" с нуля до номинального значения, бывшем до этого в неработоспособном состоянии. Применимо, если указано более одного peer'а.
    
    Тип параметра: текстовое значение с суффиксом:
    - s - секунда;
    - m - минута;
    - h - час;
    - d - день;
    - w - неделя;
    - M - месяц (30 дней);
    - y - год (365 дней).
    По умолчанию: не имеет значения по умолчанию.
  - hash
    
    В значении параметра определяется хеш, который будет связан с узлом при выборе липкой балансировки.
    
    Используется в случае:
    - …/…/load_balancing/type == 'sticky';
    - enable_dp_hash is None.
    Тип параметра: текстовое значение.
    
    По умолчанию: Не имеет значения по умолчанию.
  - (2.1) enable_dp_hash
    
    В значении параметра определяется, необходимо ли генерировать хеш из "ip: port" по внутреннему алгоритму DP.
    
    Используется в случае:
    - …/…/load_balancing/type == 'sticky';
    - hash is None.
    Тип параметра: текстовое значение.
    
    По умолчанию:
    - true;
    - false. Опциональные параметры:
- ssl
  
  В значении параметра определяется тип соединения с проксируемым сервером - http или https.
  
  В текущей версии маппится "как есть" на опцию https://nginx.org/ru/docs/http/ngx_http_proxy_module.html#proxy_pass.
  
  Без дальнейших настроек SSL/TLS соединения в сервисе, позволит установить небезопасное соединение по протоколу HTTPS (без верификации валидности сертификатов сервера (иными словами, upstream), то есть без прикладывания каких-либо сертификатов в данной части профиля.
  
  По умолчанию тип соединения:
```
http  
```
  Тип параметра:
  - true;
  - false.
  По умолчанию:
```
ssl: false
```
- rewrite_uri
  
  Последовательность rewrite_uri позволяет произвести замену URL-адреса, который идет на backend.
  
  В rewrite_uri переопределяется URI запроса целиком (с учетом аргументов). Например:
```
rewrite_uri:
  - from: ^\/agreement\/v1\/agreement(\?.*|)$
    to: /api/v1/agreement$1
```
  Тип параметра:
```
rewrite_uri:
  - from: ^(/payments/v4/banking/
products/p2bpayments)
(/mobile-pay/)(.*)$
    to: $1/mobile-not-pay/$3
  - from: ^(/person-credit/v5/ib/banking/
products/loans/lending-capacity)
(/consumer-loan/)(.*)$
    to: $1/consumer-not-loan/$3
```
  По умолчанию: не имеет значения по умолчанию.
  
  Обязательные параметры:
  - from
    
    Значением параметра необходимо указать регулярное выражение, соответствующее URI.
    
    Тип параметра: строковое значение.
    from: ^(/payments/v4/banking/products/p2bpayments)(/mobile-pay/)(.*)$
  - to
    
    Значением параметра необходимо указать строку для замены URI, которая соответствует регулярному выражению в параметре from. Допустимо использовать подстановки (например, $1, $2 и т.д.) в соответствии с имеющимся регулярным выражением.
    
    Тип параметра: строковое значение.
    to: $1/mobile-not-pay/$3
- bind_context
  
  В значении параметра указывается шаблон условия связывания контекста. Т.е. параметр обязателен к использованию при условии, что балансировка включена на уровне service_main_proxy.
  
  ОБЯЗАТЕЛЬНО в случае:
  - use_upstream_groups: true;
  - bind_condition is None.
```
service_main_proxy:
  - id: 1
    use_upstream_groups: true
```
  Тип параметра: строковое значение.
  
  По умолчанию: не имеет значения по умолчанию.
- bind_condition
  
  В значении параметра задается значение переменной, которая будет использоваться в качестве условия связывания с upstream группой.
  
  Если используется данный параметр и существует несколько upstream групп, то одна из них должна быть объявлена по умолчанию.
  
  Используется в случае:
  - bind_context is None;
  - upstream_bind_variable is not None.
  Тип параметра: строковое значение.
  
  По умолчанию: не имеет значения по умолчанию.
- default
  
  В значении параметра указывается, что данная группа upstream'ов используется по умолчанию. Используется вместе с bind_condition.
  
  Значение параметра default должно быть уникальным.
  
  Используется в случае:
  - bind_condition is not None.
  Тип параметра:
  - true;
  - false.
  По умолчанию: не имеет значения по умолчанию.
- health_check
  
  Группа параметров health_check предназначена для проверки работоспособности сервиса.
  
  Группа, включающая в себя параметры, описанные в разделе "Параметр health_check (util_health_check)".
  
  Тип параметра: группа параметров и их значения.
  
  По умолчанию: не имеет значения по умолчанию.
- load_balancing
  
  Тип параметра: группа параметров и их значения.
```
load_balancing:
  type: sticky
  always_use_sticky: true
  httponly: "off"
  secure: "off"
  name: SWJSESSIONID
  monitor_cookie: UFS-SESSION
  domain: .online.mycompany.ru
  path: /
#  expires: 3h
```
  По умолчанию: не имеет значения по умолчанию.
  
  Опциональные параметры:
  - type
    
    В значении параметра указывается тип балансировки.
    
    Тип параметра:
    - hash - метод балансировки, при котором соответствие клиента серверу определяется при помощи хэшированного значения "ключа";
    - ip_hash (пример);
    - sticky - привязывает запрос (на определенное время или нет) к конкретному upstream'у;
    - persistence - выполняет ту же роль, что и sticky, но, persistence потенциально знает еще о сессии, поэтому его можно ограничить не только по времени, но и по времени жизни сессии;
    - least_conn - Метод балансировки нагрузки, при котором запрос передается серверу с наименьшим числом активных соединений, с учетом весов серверов. Если подходит сразу несколько серверов, они выбираются циклически (в режиме round-robin) с учетом их весов.
    По умолчанию: Round Robin.
  - hash_consistent
    
    В значении параметра указывается механизм хеширования методом ketama.
    
    Используется в случае:
    - type: hash.
    Тип параметра:
    - "on";
    - "off". По умолчанию: не имеет значения по умолчанию.
  - hash_key
    
    В значении параметра указывается отображение клиент-сервер основано на значении хэшированного ключа.
    
    Используется в случае:
    - type: hash.
    Тип параметра: строковое значение.
    
    По умолчанию: не имеет значения по умолчанию.
  - name
    
    В значении параметра указывается имя файла cookie, используемого для отслеживания, сохраняющихся upstream srv.
    
    Используется в случае:
    - type: sticky;
    - type: persistence.
    Тип параметра: строковое значение.
    
    По умолчанию:
    name: <route>
  - domain
    
    В значении параметра указывается имя домена, в котором будет сохранен файл cookie.
    
    Используется в случае:
    - type: sticky.
    Тип параметра: строковое значение.
    
    По умолчанию: по умолчанию обрабатывается браузером.
  - path
    
    В значении параметра указывается путь, по которому будет сохранен файл cookie.
    
    Используется в случае:
    - type: sticky.
    Тип параметра: строковое значение.
    
    По умолчанию: по умолчанию обрабатывается браузером.
  - expires
    
    В значении параметра указывается срок действия файла cookie.
    
    Используется в случае:
    - type: sticky.
    Тип параметра: текстовое значение с суффиксом:
    - ms - миллисекунда;
    - s - секунда;
    - m - минута;
    - h - час;
    - d - день;
    - w - неделя;
    - M - месяц (30 дней);
    - y - год (365 дней).
    По умолчанию: Сookie действует на протяжении сессии.
  - hash
    
    В значении параметра указывается механизм хеширования для кодирования upstream'а.
    
    Используется в случае:
    - type: sticky;
    - hmac is None.
    Тип параметра:
    - "md5";
    - "sha1";
    - "index".
    По умолчанию:
    hash: "md5"
  - hmac
    
    В значении параметра указывается механизм хеширования для кодирования upstream'а, который похож на механизм hash, но используется дополнительный параметр hmac_key для обеспечения хеширования.
    
    Используется в случае:
    - type: sticky;
    - hash is None.
    Тип параметра:
    - "md5;
    - "sha1".
    По умолчанию: не имеет значения по умолчанию.
  - hmac_key
    
    Ключ, используемый при хешировании механизмом hmac.
    
    Используется в случае:
    - type: sticky;
    - hmac is not None.
    Тип параметра: строковое значение.
    
    По умолчанию: не имеет значения по умолчанию.
  - no_fallback
    
    Вкл./Откл. поведения nginx'а, возвращающего 502 (Bad Gateway or Proxy Error), если запрос приходит с файлом cookie, а соответствующий backend недоступен.
    
    Используется в случае:
    - type: sticky.
    Тип параметра:
    - "on";
    - "off".
    По умолчанию: не имеет значения по умолчанию.
  - secure
    
    В значении параметра указывается вкл./откл. механизма безопасной передачи файлов cookie - только через https.
    
    Используется в случае:
    - type: sticky.
    Тип параметра:
    - "on";
    - "off".
    По умолчанию:
    secure: "off"
  - httponly
    
    В значении параметра определяется, необходимо ли использовать файлы cookie, которые не могут быть пропущены через js.
    
    Используется в случае:
    - type: sticky.
    Тип параметра:
    - "on";
    - "off".
    По умолчанию:
    httponly: "off"
  - persistence_type
    
    В значении параметра указывается тип персистентной балансировки.
    
    Используется в случае:
    - type: persistence.
    Тип параметра:
    - "insert_cookie" - состояние, при котором балансировщик добавляет сеансовый cookie в сеанс клиентов. С каждым запросом, который делает клиент, он отправляет этот файл cookie, который декодирует подсистема балансировки, чтобы определить, на какой сервер отправить клиента;
    - "session_based" - балансировщик находится перед группой серверов и реализует логику, которая связывает пользовательский сеанс с конкретным сервером так долго, как это необходимо.
    По умолчанию: не имеет значения по умолчанию.
  - monitor_cookie
    
    В значении параметра указывается cookie, устанавливаемая upstream'ом в ответе в заголовке Set-Cookie. Если cookie пришли, выставляется имя сессии.
    
    Используется в случае:
    - type: persistence;
    - type: sticky.
    Тип параметра: строковое значение.
    
    По умолчанию: не имеет значения по умолчанию.
  - always_use_sticky
    
    Если в upstream'e только один peer, а параметр always_use_sticky не указан, то cookie создаваться не будут.
    
    Используется в случае:
    - type: sticky.
    Тип параметра:
    - true;
    - false.
    По умолчанию: не имеет значения по умолчанию.
  - timeout
    
    В значении параметра указывается время истечения срока действия cookie.
    
    Используется в случае:
    - type: persistence.
    Тип параметра: целочисленное значение.
    
    По умолчанию: не имеет значения по умолчанию.
  - reset_uri
    
    При обращении к данному uri в случае наличия в запросе cookie, заданной для соответствующего маршрута как сессионная, в параметре name данная cookie будет удалена из запроса уходящего на upstream и соответственно peer будет перевыбран.
    reset_uri: /cookie_reset_go
    Используется в случае:
    - type: sticky;
    - reset_uri_pattern is None.
    Тип параметра: текстовое значение.
    
    По умолчанию: не имеет значения по умолчанию.
  - reset_uri_pattern
    
    Используется в случае:
    - type: sticky;
    - reset_uri_ is None.
    Тип параметра: текстовое значение.
    
    По умолчанию: не имеет значения по умолчанию.
  - reset_cookie
    
    Если установлен данный параметр, то сессионная cookie будет сброшена, если в запросе отсутствует cookie указанная в monitor_cookie.
    
    Используется в случае:
    - type: sticky.
    Тип параметра:
    - true;
    - false.
    По умолчанию:
    reset_cookie: false
  - max_age
    
    В значении параметра устанавливается количество секунд до истечения срока действия файла cookie. Нулевое или отрицательное число немедленно сбросит файл cookie.
    
    Используется в случае:
    - type: sticky.
    Тип параметра: целочисленное значение.
    
    По умолчанию: не имеет значения по умолчанию.
- zone
  
  Зона разделяемой памяти, в которой хранятся конфигурация группы и ее рабочее состояние, разделяемые между рабочими процессами. По умолчанию все группы апстримов используют одну общую дефолтную зону с размером 1m.
  
  Тип параметра: группа параметров и их значения.
  
  По умолчанию: не имеет значения по умолчанию.
  
  Опциональные параметры:
  - name
    
    В значении параметра указывается имя upstream_zone
    
    Тип параметра: строковое значение.
    
    По умолчанию:
    default_zone
  - size
    
    В значении параметра указывается размер upstream_zone
    
    Тип параметра: текстовое значение с суффиксом:
    - k / K - килобайты;
    - m / M - мегабайты.
    По умолчанию:
    zone: 1m
    Данного размера хватает на 512 серверов с включенным healthcheck & sticky session.
- keepalive_conn_count
  
  Устанавливает максимальное число неактивных постоянных соединений с серверами группы, которые будут сохраняться в кэше каждого рабочего процесса.
  
  Тип параметра: целочисленное значение.
  
  По умолчанию: не имеет значения по умолчанию.
- keepalive
  
  Устанавливает максимальное число неактивных постоянных соединений с серверами группы, которые будут сохраняться в кэше каждого рабочего процесса. При превышении этого числа наиболее давно не используемые соединения закрываются.
  
  Тип параметра: целочисленное значение.
  
  По умолчанию: не имеет значения по умолчанию.
- (2.3) keepalive_requests
  
  Задает максимальное число запросов, которые можно сделать по одному постоянному соединению. После того как сделано максимальное число запросов, соединение закрывается.
  
  Тип параметра: целочисленное значение.
  
  По умолчанию: 100.
- (2.3) keepalive_timeout
  
  Задает таймаут, в течение которого неактивное постоянное соединение с сервером группы не будет закрыто.
  
  Тип параметра: текстовое значение с суффиксом:
  - s - миллисекунда;
  - s - секунда;
  - m - минута;
  - h - час;
  - d - день;
  - w - неделя;
  - M - месяц (30 дней);
  - y - год (365 дней).
  По умолчанию: 60s.

Опциональные параметры:

upstream_group_id

В значении параметра указывается идентификатор upstream группы.
```
use_main_upstream_groups: true
upstream_group_id: extgw_v1
```
Параметр upstream_group_id не может быть объявлен в сервисах типа service_main_proxy и service_cache.

Тип параметра: текстовое значение.

По умолчанию: не имеет значения по умолчанию.
upstream_bind_variable

В значении параметра определяется переменная, которая используется для связывания upstream группы с bind_condition.
```
upstream_bind_variable: $http_host
upstream_groups:
  - id: extgw_v1
    ssl: true
    bind_condition: ^test-0004$
    servers:
      !include: server_group1.yml
  - id: extgw_v2
    ssl: true
    bind_condition: ^test-0004.example.ru$
    default: true
    servers:
      !include: server_group2.yml
```
Тип параметра: строковое значение.

По умолчанию: не имеет значения по умолчанию.

Пример использования параметра upstream:

version: 2.0.3
profile: <profile_name>
system:
  wrk_count: 4
  conn_count: 2048
  optional:
    wrk_user: sowactl
    underscores_in_headers: true
    log_level: debug
service:
  service_main_proxy:
    - id: 1
      listen:
        - port: 8091
          ...
      hostname:
        - localhost
      url: /
      ...
      upstream_groups:
        - id: extgw_v1
          ssl: true
          health_check:
            ...
          load_balancing:
            ...
          servers:
            ...
      ...
  service_http_proxy:
    - id: payments_1
      ...
      url: ^\/payments\/v4\/banking\/products\/p2bpayments\/mobile-main\/main$
      ...
      use_main_upstream_groups: true
      upstream_group_id: extgw_v1
      ...
    - id: hp_1
      ...
      use_main_upstream_groups: false
      upstream_group_id: <value_name_group>
      upstream_groups:
        - id: <value_name_group>
          servers:
            - server: <value_ip_address>