Шаг 3. Настройка ADC: объекты конфигурации

Продолжаем обучение настройке ADC. Из прошлой статьи вы уже узнали, что такое плагины. Плагины подключаются к объектам конфигурации. О них пойдёт речь в этом тексте.

Введение: какие вообще настройки нужны ADC для работы

ADC стоит между клиентами и вашим бэкендом. Он принимает, обрабатывает и передаёт запросы и ответы, а также может писать логи и отправлять копии запросов во внешнюю систему.

Чтобы выполнять эти действия, ADC нужно знать:

TLS-сертификаты и ключи — если клиенты подключаются по HTTPS;
параметры трафика, который нужно принять и обработать;
правила обработки трафика — например, проверить клиента или IP-адрес, применить ограничения, изменить HTTP-запрос или ответ;
описание gRPC-сервиса в формате .proto — если ADC должен преобразовывать HTTP-запросы в gRPC-вызовы;
учётные данные клиентов — если в ходе обработки запроса нужно отличить одного клиента от другого;
секреты — если API-ключи, пароли или токены нельзя хранить открытым текстом;
адреса бэкенд-нод, куда нужно передать трафик, а также настройки балансировки и health checks.

Как вы вносите настройки

Вы создаёте объекты конфигурации. Один объект — это совокупность нескольких настроек.

Пример объекта — потоковый маршрут. Он описывает обработку TCP/UDP трафика. В нём вы указываете сразу несколько вещей:

параметры TCP/UDP-трафика, который нужно принимать и передавать на бэкенд;
плагины, с помощью которых нужно обрабатывать этот трафик;
адреса бэкенда и правила балансировки между серверами.

Виды объектов конфигурации

Все объекты конфигурации можно условно разделить на два типа:

Основные — объекты, в которых вы задаёте конфигурацию ADC: параметры принимаемого трафика, плагины для него, клиенты API и так далее.
Вспомогательные — объекты, в которые вы выносите повторяющиеся настройки или общие параметры, чтобы затем переиспользовать их в основных объектах.

Объясним разницу между ними на примере: на сайте авиакомпании вы сохранили данные пассажира: свои ФИО и паспорт. Теперь при покупке билетов можно нажимать Выбрать пассажира → [Ваше имя], и сайт автоматически подставит ваши данные. Не придётся каждый раз вводить ФИО и паспорт заново. В этом примере данные пассажира — вспомогательный объект, а билеты — основные объекты.

Основные объекты конфигурации

Внутри каждого из основных объектов вы указываете набор настроек или данных.

Объект конфигурации	Что вы указываете в нём
SSL-сертификаты	TLS-сертификат, закрытый ключ и SNI
Глобальное правило	Плагины, которые нужно применять ко всем HTTP/HTTPS-запросам
Маршрут	Параметры конкретного типа HTTP-запросов, плагины для обработки этих запросов и ответов на них, адреса бэкенда и правила балансировки
Потоковый маршрут	Параметры TCP/UDP-трафика, плагины для обработки этого трафика, адреса бэкенда и правила балансировки
Потребитель	Учётные данные конкретного клиента и плагины для обработки запросов от этого клиента
Секрет	Адрес внешнего хранилища секретов и параметры доступа к нему
Proto	Описание вашего gRPC-сервиса, его методов и структуры сообщений

Объект конфигурации

Что вы указываете в нём

SSL-сертификаты

TLS-сертификат, закрытый ключ и SNI

Глобальное правило

Плагины, которые нужно применять ко всем HTTP/HTTPS-запросам

Маршрут

Параметры конкретного типа HTTP-запросов, плагины для обработки этих запросов и ответов на них, адреса бэкенда и правила балансировки

Потоковый маршрут

Параметры TCP/UDP-трафика, плагины для обработки этого трафика, адреса бэкенда и правила балансировки

Потребитель

Учётные данные конкретного клиента и плагины для обработки запросов от этого клиента

Секрет

Адрес внешнего хранилища секретов и параметры доступа к нему

Proto

Описание вашего gRPC-сервиса, его методов и структуры сообщений

Объектов можно создавать сколько угодно. Например, вы точно создадите много маршрутов — по одному на каждый тип запроса, для которого нужны уникальные правила обработки.

Пример из жизни: как настраиваются объекты

Представьте, что нужно настроить такую последовательность:

Установить соединение по HTTPS.
Идентифицировать конкретного клиента по его API-токену.
Проверить, не превысил ли этот клиент установленный для него лимит запросов:
- если превысил — отдать ошибку 429;
- если не превысил — обработать запрос.
Присвоить запросу уникальный идентификатор, чтобы его можно было отслеживать в логах.
Передать запрос на бэкенд с адресом 10.0.1.11:8080.
Принять ответ от бэкенда и добавить в него CORS-заголовки.
Передать получившийся ответ клиенту.

Для этого вы создаёте следующие объекты:

Объект Какие настройки в нём указываются

Объект	Какие настройки в нём указываются
SSL-сертификат	`Тип`: `Серверный` — тип сертификата, в данном случае серверный; `Статус`: `Включён` — режим работы: применять сертификат (`Включён`) или нет (`Отключён`); `TLS-протоколы`: `TLSv1.2`, `TLSv1.3`; `SNI`: `example.com` — домен, к которому будут обращаться клиенты; `Сертификат (PEM)` и `Приватный ключ (PEM)` — содержимое TLS-сертификата и ключа
Маршрут	`URI`: `/orders/*`, `HTTP-методы`: `POST` / `GET`, `Хост`: `example.com` — параметры запросов, которые должен обрабатывать маршрут; Плагин `key-auth` — проверить API-ключ, найти соответствующего ему потребителя и применить настроенные для него правила; Плагин `request-id` — присвоить запросу уникальный идентификатор для отслеживания; `Upstream` → адрес `10.0.1.11:8080` — куда отправлять запрос после обработки; Плагин `cors` — добавить CORS-заголовки в ответ
Потребитель	`Имя пользователя` — уникальный идентификатор клиента; Плагин `key-auth` — в рамках этого плагина вы указываете API-ключ данного клиента; Плагин `limit-req` или `limit-count` — настройки лимита запросов, которые будут применены к трафику от данного клиента

SSL-сертификат

Тип: Серверный — тип сертификата, в данном случае серверный;

Статус: Включён — режим работы: применять сертификат (Включён) или нет (Отключён);

TLS-протоколы: TLSv1.2, TLSv1.3;

SNI: example.com — домен, к которому будут обращаться клиенты;

Сертификат (PEM) и Приватный ключ (PEM) — содержимое TLS-сертификата и ключа

Маршрут

URI: /orders/*, HTTP-методы: POST / GET, Хост: example.com — параметры запросов, которые должен обрабатывать маршрут;

Плагин key-auth — проверить API-ключ, найти соответствующего ему потребителя и применить настроенные для него правила;

Плагин request-id — присвоить запросу уникальный идентификатор для отслеживания;

Upstream → адрес 10.0.1.11:8080 — куда отправлять запрос после обработки;

Плагин cors — добавить CORS-заголовки в ответ

Потребитель

Имя пользователя — уникальный идентификатор клиента;

Плагин key-auth — в рамках этого плагина вы указываете API-ключ данного клиента;

Плагин limit-req или limit-count — настройки лимита запросов, которые будут применены к трафику от данного клиента

Вспомогательные объекты конфигурации

Напоминаем: во вспомогательные объекты вы выносите повторяющиеся настройки или общие параметры, чтобы затем использовать их из других объектов.

Вспомогательный объект	Что вы указываете в нём	Из каких объектов его можно использовать и как
Upstream	Адреса бэкенд-нод / настройки service discovery, параметры подключения, балансировка, проверки здоровья	Маршрут, потоковый маршрут, сервис — в их настройках укажите ID нужного upstream
Конфигурация плагинов	Набор настроенных плагинов	Маршрут, потоковый маршрут — в их настройках укажите ID нужной конфигурации плагинов
Сервис	Набор настроенных плагинов, адреса бэкенд-нод / настройки service discovery, параметры подключения, балансировка, проверки здоровья	Маршрут, потоковый ма3ршрут — в их настройках укажите ID нужного сервиса
Группа потребителей	Набор настроенных плагинов	Потребитель — в его настройках укажите ID нужной группы потребителей
Метаданные плагина	Общие параметры для всех экземпляров конкретного плагина	Любые объекты конфигурации — метаданные плагинов применяются автоматически при подключении к объекту нужного плагина. Исключение: если внутри объекта прописать для плагина параметры, конфликтующие с параметрами из метаданных плагина, то все конфликты разрешатся в пользу параметров из объекта.

Вспомогательный объект

Что вы указываете в нём

Из каких объектов его можно использовать и как

Upstream

Адреса бэкенд-нод / настройки service discovery, параметры подключения, балансировка, проверки здоровья

Маршрут, потоковый маршрут, сервис — в их настройках укажите ID нужного upstream

Конфигурация плагинов

Набор настроенных плагинов

Маршрут, потоковый маршрут — в их настройках укажите ID нужной конфигурации плагинов

Сервис

Набор настроенных плагинов, адреса бэкенд-нод / настройки service discovery, параметры подключения, балансировка, проверки здоровья

Маршрут, потоковый ма3ршрут — в их настройках укажите ID нужного сервиса

Группа потребителей

Набор настроенных плагинов

Потребитель — в его настройках укажите ID нужной группы потребителей

Метаданные плагина

Общие параметры для всех экземпляров конкретного плагина

Любые объекты конфигурации — метаданные плагинов применяются автоматически при подключении к объекту нужного плагина.

Исключение: если внутри объекта прописать для плагина параметры, конфликтующие с параметрами из метаданных плагина, то все конфликты разрешатся в пользу параметров из объекта.

Пример: когда нужны вспомогательные объекты

Представьте, что вам нужно поставить на несколько эндпоинтов разные лимиты запросов. При этом трафик к каждому эндпоинту идёт на один и тот же бэкенд. Настройка выглядит так:

Маршрут Параметры запроса Лимит запросов Бэкенд

Маршрут	Параметры запроса	Лимит запросов	Бэкенд
Маршрут 1	`POST /orders`	100 запросов в минуту	`10.0.1.11:8080`, `10.0.1.12:8080`, round robin
Маршрут 2	`GET /orders/{id}`	300 запросов в минуту	`10.0.1.11:8080`, `10.0.1.12:8080`, round robin
Маршрут 3	`PUT /orders/{id}`	50 запросов в минуту	`10.0.1.11:8080`, `10.0.1.12:8080`, round robin
Маршрут 4	`DELETE /orders/{id}`	20 запросов в минуту	`10.0.1.11:8080`, `10.0.1.12:8080`, round robin

Маршрут 1

POST /orders

100 запросов в минуту

10.0.1.11:8080, 10.0.1.12:8080, round robin

Маршрут 2

GET /orders/{id}

300 запросов в минуту

10.0.1.11:8080, 10.0.1.12:8080, round robin

Маршрут 3

PUT /orders/{id}

50 запросов в минуту

10.0.1.11:8080, 10.0.1.12:8080, round robin

Маршрут 4

DELETE /orders/{id}

20 запросов в минуту

10.0.1.11:8080, 10.0.1.12:8080, round robin

Заметьте: пришлось четыре раза копировать одни и те же настройки бэкенда из маршрута в маршрут. А если IP поменяется, придётся редактировать все маршруты один за другим.

Упростит процесс вспомогательный объект upstream. Вы создаёте upstream с настройками 10.0.1.11:8080, 10.0.1.12:8080, round robin. Этот объект получает свой ID — например, 1. Затем вы просто ссылаетесь на него из каждого маршрута:

Маршрут Параметры запроса Лимит запросов Бэкенд

Маршрут	Параметры запроса	Лимит запросов	Бэкенд
Маршрут 1	`POST /orders`	100 запросов в минуту	Upstream-1
Маршрут 2	`GET /orders/{id}`	300 запросов в минуту	Upstream-1
Маршрут 3	`PUT /orders/{id}`	50 запросов в минуту	Upstream-1
Маршрут 4	`DELETE /orders/{id}`	20 запросов в минуту	Upstream-1

Маршрут 1

POST /orders

100 запросов в минуту

Upstream-1

Маршрут 2

GET /orders/{id}

300 запросов в минуту

Upstream-1

Маршрут 3

PUT /orders/{id}

50 запросов в минуту

Upstream-1

Маршрут 4

DELETE /orders/{id}

20 запросов в минуту

Upstream-1

Работать стало удобнее.

Подробно о каждом объекте конфигурации

Сначала даём краткую схему, затем подробный текстовый обзор всех объектов: и основных, и вспомогательных.

Маршрут
  = условия совпадения HTTP-запроса
  + WebSocket
  + плагины² ³
  + бэкенд¹ ²
  + таймауты

¹ альтернатива: ID upstream;
² альтернатива/дополнение: ID сервиса;
³ альтернатива/дополнение: ID конфигурации плагинов.


Потоковый маршрут
  = условия совпадения TCP/UDP-трафика
  + плагины² ³
  + бэкенд¹ ²
  + протокол

¹ альтернатива: ID upstream;
² альтернатива/дополнение: ID сервиса;
³ альтернатива/дополнение: ID конфигурации плагинов.


Сервис
  = плагины
  + бэкенд¹
  + настройки сервиса (WebSocket, скрипт, хосты)

¹ альтернатива: ID upstream.


Upstream
  = адреса нод или настройки service discovery
  + параметры подключения (схема, Pass Host, повторные попытки, таймауты, keepalive)
  + правила балансировки
  + health checks


Потребитель
  = имя пользователя
  + плагины¹

¹ альтернатива/дополнение: ID группы потребителей.


Группа потребителей
  = плагины


SSL-сертификат
  = TLS-сертификат и приватный ключ
  + тип: серверный или клиентский
  + SNI¹
  + версии TLS

¹ только для серверного сертификата.


Секрет
  = менеджер секретов
  + конфигурация менеджера (URI, префикс, токен, namespace)


Глобальное правило
  = плагины


Метаданные плагина
  = плагин¹ + конфигурация (JSON)

¹ только для плагинов, поддерживающих метаданные.


Конфигурация плагинов
  = плагины


Proto-файл
  = содержимое .proto

Маршруты

Если ADC получит HTTP-запрос, который не подходит ни под один маршрут, он вернёт клиенту ошибку 404.

Суть: маршрут диктует, что делать с конкретным типом HTTP-запросов:

как обработать запрос;
на какой бэкенд передать запрос после обработки;
как обработать ответ перед передачей клиенту.

Тип объекта: основной.

Какие блоки настроек содержит:

Основная информация — название, описание и метки маршрута, а также его приоритет и статус. Приоритет нужен, если для одного URI настроено несколько маршрутов: ADC выберет тот, чей приоритет выше.
Правила маршрутизации — параметры, с которыми должен совпасть HTTP-запрос, чтобы ADC применил настройки этого маршрута: HTTP-методы, URI, хосты, IP-адреса и другие условия. Здесь же можно включить поддержку WebSocket.
Таймауты — сколько ADC будет ждать соединения с бэкендом, отправки ему запроса и ответа от него.
Upstream — адреса бэкенд-нод / настройки service discovery, параметры подключения, балансировки и health checks.
Плагины — плагины, которыми ADC обработает запрос до передачи его на бэкенд и ответ до передачи клиенту.

Некоторые настройки можно не указывать напрямую, а вынести во вспомогательный объект (сервис, upstream или конфигурацию плагинов) и просто сослаться на этот объект через его ID.

Пример: настроим маршрут для запросов на создание заказов. ADC примет POST-запросы к api.example.com/api/v1/orders, распределит их на доступные ноды по round robin, вернёт клиенту ответ бэкенда и отправит логи на сервер https://logs.example.com/adc.

Основная информация: имя — create-orders; статус — Включён.
Правила маршрутизации: HTTP-метод — POST; URI — /api/v1/orders; хост — api.example.com.
Таймауты: подключение — 1 секунда; отправка запроса — 5 секунд; ожидание ответа — 10 секунд.
Upstream: ноды — 10.0.1.11:8080 и 10.0.1.12:8080.
Конфигурация соединения: схема — HTTP; алгоритм балансировки — Round Robin; Pass Host — pass, то есть ADC передаёт бэкенду исходный заголовок Host.
Проверки здоровья: включены активные проверки, ADC проверяет доступность нод.
Плагины: http-logger — ADC отправляет на указанный сервер сведения о запросе и ответе; в этом примере указываем https://logs.example.com/adc.

Потоковые маршруты

Суть: потоковый маршрут диктует, что делать с конкретным типом TCP/UDP-трафика:

какие входящие TCP-соединения или UDP-сессии принять;
на какой бэкенд передать трафик;
какие плагины применить при обработке TCP-соединения или UDP-сессии.

Тип объекта: основной.

Какие блоки настроек содержит:

Основная информация — описание и метки потокового маршрута.
Сервер — адрес и порт ADC, на которых нужно принять трафик, а также удалённый адрес клиента и SNI, если их нужно учитывать.
Upstream — адреса бэкенд-нод / настройки service discovery, параметры подключения, балансировки и health checks.
Плагины — плагины, которые нужно применить к трафику.
Протокол — имя протокола, ID родительского протокола, его конфигурация и настройки логгера в JSON. Этот блок нужен, если для трафика используется специальный поддерживаемый протокол.

Пример: настроим потоковый маршрут для внутреннего TCP-сервиса.

Основная информация: описание — Доступ к TCP-сервису для внутренних систем.
Сервер: адрес — 0.0.0.0; порт — 9100; удалённый адрес — 10.0.0.0/8.
Upstream: ноды — 10.0.2.11:9000 и 10.0.2.12:9000.
Конфигурация соединения: схема — TCP; алгоритм балансировки — Round Robin; подключение — 1 секунда; отправка данных — 5 секунд; ожидание данных — 10 секунд.
Проверки здоровья: включены активные проверки нод.
Плагины: prometheus — собирает метрики TCP-трафика.

В результате ADC примет TCP-соединение на порту 9100, только если клиент подключается из внутренней сети, выберет доступную бэкенд-ноду и передаст ей поток данных. Метрики соединений и переданного трафика будут доступны для сбора в Prometheus.

Сервисы

Суть: сервис хранит общие настройки для одного API, которые можно переиспользовать в нескольких маршрутах:

как обрабатывать запросы к этому API;
на какой бэкенд их направлять;
какие общие параметры соединения с бэкендом использовать.

Тип объекта: вспомогательный.

Из каких объектов на него можно ссылаться: маршрут, потоковый маршрут.

Какие блоки настроек содержит:

Основная информация — название, описание и метки сервиса.
Настройки сервиса — поддержка WebSocket, пользовательский скрипт и список хостов.
Upstream — адреса бэкенд-нод / настройки service discovery, параметры подключения, балансировки и health checks.
Плагины — плагины, которые ADC будет применять к запросам, связанным с этим сервисом.

Пример: у API каталога есть два маршрута: один возвращает список товаров, другой — карточку товара. Для обоих нужны одинаковые настройки CORS, идентификатор запроса и один бэкенд. Вынесем их в сервис.

Основная информация: имя — catalog-api; описание — Общие настройки API каталога.
Настройки сервиса: WebSocket — выключен; хост — api.example.com.
Upstream: ID существующего upstream — catalog-backend.
Плагины: cors — разрешает запросы с https://app.example.com; request-id — добавляет каждому запросу уникальный идентификатор.

В результате оба маршрута будут использовать одни и те же настройки. Если потребуется изменить бэкенд или CORS, достаточно изменить сервис один раз.

Upstreams

Суть: upstream описывает группу бэкенд-нод и правила работы с ней:

на какие ноды можно направлять запросы;
как выбирать ноду;
как подключаться к нодам и проверять их доступность.

Тип объекта: вспомогательный.

Из каких объектов на него можно ссылаться: маршрут, потоковый маршрут, сервис.

Какие блоки настроек содержит:

Основная информация — название, описание и метки upstream.
Источник upstream — адреса бэкенд-нод / настройки service discovery.
Конфигурация соединения — схема подключения, алгоритм балансировки, настройка Pass Host, повторные попытки, таймауты и keepalive-соединения.
Проверки здоровья — параметры health checks, по которым ADC определяет, доступна ли нода.

Пример: настроим upstream для API заказов.

Основная информация: имя — orders-backend; описание — Ноды API заказов.
Источник upstream: ноды — 10.0.1.11:8080 и 10.0.1.12:8080.
Конфигурация соединения: схема — HTTP; алгоритм балансировки — Round Robin; Pass Host — pass; подключение — 1 секунда; отправка запроса — 5 секунд; ожидание ответа — 10 секунд.
Проверки здоровья: включены активные проверки доступности нод.

В результате ADC будет распределять запросы между доступными нодами API заказов по round robin.

Потребители

Сам по себе объект потребитель не распознаёт клиента. Для этого на маршруте или сервисе должен быть включён плагин аутентификации, например key-auth, jwt-auth или basic-auth.

Суть: потребитель представляет конкретного клиента API — например, партнёра, приложение или внутренний сервис. В нём можно хранить учётные данные клиента и отдельные правила обработки его запросов.

Тип объекта: основной.

Какие блоки настроек содержит:

Основная информация — уникальное имя пользователя, описание и метки.
Плагины — плагины, которые ADC применит к трафику этого клиента. Учётные данные клиента также указываются внутри плагинов.

Настройки плагина у потребителя имеют наивысший приоритет среди локальных настроек. Они перекрывают настройки того же плагина в группе потребителей, маршруте, конфигурации плагинов и сервисе.

Из настроек потребителя можно сослаться на ID группы потребителей.

Пример: партнёр Acme обращается к API заказов по API-ключу. Создадим для него отдельного потребителя.

Основная информация: имя пользователя — acme; описание — Партнёр Acme.
Плагины: key-auth — API-ключ партнёра; limit-count — не более 1 000 запросов в минуту.

Если на маршруте API заказов включён key-auth, ADC распознает Acme по ключу и применит к его запросам отдельный лимит.

Группы потребителей

Суть: группа потребителей позволяет задать общие правила для нескольких клиентов API и не копировать их в каждого потребителя.

Тип объекта: вспомогательный.

Из каких объектов на него можно ссылаться: потребитель.

Какие блоки настроек содержит:

Основная информация — ID группы, описание и метки.
Плагины — плагины, которые ADC применит к трафику всех потребителей, которые входят в группу.

Если один и тот же плагин настроен и в группе, и у конкретного потребителя, ADC использует настройки потребителя.

Пример: все стандартные партнёры должны работать с одинаковым лимитом запросов. Вы создаёте группу потребителей:

Основная информация: ID — partners-standard; описание — Стандартные условия для партнёров.
Плагины: limit-count — не более 1 000 запросов в минуту.

Теперь достаточно указать partners-standard в настройках каждого нового партнёра. Общий лимит будет применяться автоматически.

SSL-сертификаты

Суть: SSL-сертификат хранит TLS-сертификат и закрытый ключ. Серверный сертификат ADC показывает клиенту при HTTPS-подключении, а клиентский использует для подключения к бэкенду по mTLS.

Тип объекта: основной.

Какие блоки настроек содержит:

Основная информация — описание, метки, тип сертификата, статус и разрешённые версии TLS.
SNI — один домен или список доменов, для которых нужно использовать сертификат.
Сертификат и приватный ключ — TLS-сертификат и соответствующий ему закрытый ключ в формате PEM.

Для входящих HTTPS-соединений используется тип сертификата Серверный. Тип Клиентский нужен, когда ADC должен предъявить сертификат бэкенду при mTLS-соединении.

Пример: настроим сертификат для публичного API.

Основная информация: тип — Серверный; статус — Включён; TLS-протоколы — TLSv1.2 и TLSv1.3.
SNI: api.example.com.
Сертификат и приватный ключ: сертификат и закрытый ключ для api.example.com в формате PEM.

В результате клиент, который подключится к https://api.example.com, получит нужный сертификат и сможет установить защищённое соединение.

Секреты

Суть: секрет настраивает подключение ADC к внешнему хранилищу секретов. После этого вместо API-ключей, паролей, сертификатов и других чувствительных значений в поддерживаемых настройках можно указывать ссылки на значения из этого хранилища.

Тип объекта: основной.

Какие блоки настроек содержит:

Основная информация — ID секрета и выбранный менеджер секретов.
Конфигурация менеджера — адрес менеджера, префикс, токен доступа и namespace.

Пример: настроим подключение к HashiCorp Vault, в котором хранятся ключи партнёров.

Основная информация: ID — vault-prod; менеджер — HashiCorp Vault.
Конфигурация менеджера: URI — https://vault.example.com:8200; префикс — kv/adc; токен доступа и namespace — значения для доступа ADC к Vault.

После этого в настройках плагина или потребителя можно указать ссылку на значение из Vault, например $secret://vault/vault-prod/…, вместо самого ключа.

Глобальные правила

Суть: глобальное правило задаёт плагины, которые должны работать для всего HTTP-трафика: например, общее логирование, аудит или ограничение запросов.

Тип объекта: основной.

Какие блоки настроек содержит:

Основная информация — ID глобального правила.
Плагины — плагины, которые ADC применит ко всем HTTP-запросам (даже к тем, что не подходят ни под один маршрут).

Пример: настроим общее логирование всех запросов к API.

Основная информация: ID — global-access-logs.
Плагины: http-logger — отправляет сведения о каждом запросе и ответе на https://logs.example.com/adc; request-id — добавляет запросу уникальный идентификатор.

В результате ADC будет логировать весь HTTP-трафик, даже если в конкретном маршруте логирование не настроено.

Метаданные плагина

Суть: метаданные плагина позволяют централизованно настроить параметр, который должен быть одинаковым у всех экземпляров конкретного плагина.

Не все плагины поддерживают метаданные плагинов.

Тип объекта: вспомогательный.

Какие блоки настроек содержит:

Имя плагина — плагин, для которого задаются общие метаданные.
Конфигурация (JSON) — параметры метаданных этого плагина.

Пример: вы хотите, чтобы у всех логов, собираемых через http-logger, был одинаковый набор полей. Вы задаёте метаданные плагина:

Имя плагина: http-logger.
Конфигурация (JSON): формат лога содержит хост, IP клиента и ID маршрута.

После этого подключаете http-logger к нужным маршрутам, и все экземпляры этого плагины будут отправлять логи в одном формате.

Если в конкретном экземпляре плагина вы настроите конфигурацию, которая конфликтует с созданными метаданными, то для всех конфликтующих настроек будут использованные локальные значения (то есть не значения из метаданных).

Конфигурации плагинов

Суть: конфигурация плагинов — это готовый набор настроенных плагинов, который можно переиспользовать в нескольких маршрутах и потоковых маршрутах.

Тип объекта: вспомогательный.

Из каких объектов на него можно ссылаться: маршрут, потоковый маршрут.

Какие блоки настроек содержит:

Основная информация — ID, название, описание и метки конфигурации.
Плагины — набор плагинов и их настройки.

Пример:

Несколько публичных API должны поддерживать CORS и добавлять идентификатор запроса.

Основная информация: ID — public-api-common; имя — Публичные API.
Плагины: cors — разрешает запросы с https://app.example.com; request-id — добавляет уникальный идентификатор запроса.

Теперь в каждом нужном маршруте достаточно указать ID public-api-common — плагин применится с указанными настройками.

Proto-файлы

Proto-файл нужен не для обычной маршрутизации. Он используется, когда ADC должен преобразовать HTTP-запрос в вызов gRPC-метода или сделать обратное преобразование ответа.

Суть: proto-файл описывает gRPC-сервис, его методы и структуру сообщений. По этому описанию ADC понимает, как преобразовать HTTP-запрос в gRPC-вызов.

Тип объекта: основной.

Какие блоки настроек содержит:

Содержимое (.proto) — текст proto-файла с описанием сервиса, методов и сообщений.

Пример: бэкенд заказов работает по gRPC, но клиентам нужен обычный HTTP API.

Содержимое (.proto): описание сервиса Orders, метода CreateOrder и сообщений запроса и ответа.
Маршрут: использует плагин grpc-transcode, в котором указаны этот proto-файл, сервис и метод.
Upstream: подключается к бэкенду по схеме gRPC.

В результате клиент отправляет POST /api/v1/orders с JSON, а ADC преобразует запрос в вызов gRPC-метода CreateOrder.

Приоритеты объектов конфигурации, разрешение конфликтов

Когда для трафика создано несколько конфликтующих настроек, ADC будет действовать так:

Ситуация	Какой объект/настройка будет использована
Один HTTP-запрос подходит под несколько маршрутов с одинаковым URI	Маршрут с более высоким приоритетом.
Upstream указан и в маршруте, и в сервисе	Upstream из маршрута.
Один и тот же плагин настроен в сервисе, конфигурации плагинов, маршруте, группе потребителей и потребителе	ADC проверит ваши объекты конфигурации в таком порядке: потребитель → группа потребителей → маршрут → конфигурация плагинов → сервис. Будут применены настройки плагина из первого объекта, где этот плагин встретился.
Один и тот же плагин настроен в глобальном правиле и в другом объекте	Обе конфигурации плагина в таком порядке: сначала из глобального правила, затем из другого объекта. Для отдельных плагинов возможны исключения.
Один и тот же параметр задан и в метаданных плагина, и в настройках этого плагина в объекте конфигурации	Значение параметра из объекта конфигурации.

Ситуация

Какой объект/настройка будет использована

Один HTTP-запрос подходит под несколько маршрутов с одинаковым URI

Маршрут с более высоким приоритетом.

Upstream указан и в маршруте, и в сервисе

Upstream из маршрута.

Один и тот же плагин настроен в сервисе, конфигурации плагинов, маршруте, группе потребителей и потребителе

ADC проверит ваши объекты конфигурации в таком порядке: потребитель → группа потребителей → маршрут → конфигурация плагинов → сервис. Будут применены настройки плагина из первого объекта, где этот плагин встретился.

Один и тот же плагин настроен в глобальном правиле и в другом объекте

Обе конфигурации плагина в таком порядке: сначала из глобального правила, затем из другого объекта. Для отдельных плагинов возможны исключения.

Один и тот же параметр задан и в метаданных плагина, и в настройках этого плагина в объекте конфигурации

Значение параметра из объекта конфигурации.

Обучение закончено. Что дальше?

Поздравляем с окончанием обучения! Теперь вы знаете, как работает ADC и как его настраивать. Самое время применить полученные знания.

Если захотите освежить память по обучению, откройте Схемы-шпаргалки по обучению — там кратко собрали основную информацию в виде схем и таблиц, которыми удобно пользоваться.