Настройка Ingress‑контроллера Вебмониторэкс¶

Ingress‑контроллер Вебмониторэкс настраивается на трех уровнях:

Кроме настроек Вебмониторэкс доступны все настройки F5 NGINX Ingress Controller: параметры Helm‑чарта, ключи ConfigMap и аннотации.

Применение настроек¶

Параметры Helm‑чарта и глобальные настройки задаются в values.yaml и применяются командой:

helm upgrade <RELEASE_NAME> oci://registry.webmonitorx.ru/public/charts/wmx-ingress \
  --version <CHART_VERSION> \
  -n <KUBERNETES_NAMESPACE> \
  -f values.yaml

Аннотации задаются в манифесте Ingress или командой:

kubectl -n <INGRESS_NAMESPACE> annotate --overwrite ingress <INGRESS_NAME> <ANNOTATION>=<VALUE>

Изменения аннотаций и глобальных настроек применяются без перезапуска pod'ов: Ingress‑контроллер перегенерирует конфигурацию NGINX и перезагружает ее.

Параметры Helm‑чарта¶

Параметры Вебмониторэкс находятся в разделе controller.wmx файла values.yaml.

Подключение к Вычислительному кластеру¶

При controller.wmx.enable: true необходимо задать controller.wmx.token или controller.wmx.existingSecret.name, иначе установка завершится ошибкой.

Постаналитика¶

Образ и ресурсы сервисов ноды¶

| controller.wmx.resources | requests: {cpu: 10m, memory: 64Mi} | Ресурсы по умолчанию для каждого контейнера ноды. Запросы (requests) нужны в том числе для HorizontalPodAutoscaler: без них у всех контейнеров pod'а HPA не может вычислить загрузку по ресурсам. |

Для каждого сервиса ноды можно задать свои ресурсы (resources, вместо controller.wmx.resources) и, при необходимости, отдельный образ (image.repository, image.tag):

Пример:

controller:
  wmx:
    postanalytics:
      arena: "1"
      tarantool:
        resources:
          requests:
            cpu: 500m
            memory: 1500Mi
          limits:
            memory: 1500Mi

Память контейнера tarantool должна превышать значение arena с запасом не менее 20 %.

Если resources для tarantool не заданы, Helm‑чарт запрашивает arena + 128 МиБ памяти (для arena: "0.2" — 332 МиБ), чтобы планировщик не размещал pod на узле без этой памяти.

Метрики¶

Подробнее — в статье Мониторинг Ingress‑контроллера.

Защита от ботов¶

Секреты защиты от ботов общие для всех pod'ов Ingress‑контроллера: проверку, которую браузер прошел на одном pod'е, проверяет другой. Если чарт отрисовывается без доступа к кластеру (например, helm template в GitOps), он не может сохранить созданные секреты и завершается с ошибкой — задайте в этом случае собственный Secret в existingSecret. hmac и token-key — строки из латинских букв, цифр и символов ., _, -. После изменения Secret перезапустите pod'ы Ingress‑контроллера (kubectl rollout restart): секреты копируются в pod при запуске.

Аннотации защиты от ботов появились в этом Ingress‑контроллере, вариантов nginx.ingress.kubernetes.io/wallarm-antibot-* у них нет.

Проверка аннотаций¶

Глобальные настройки (ConfigMap)¶

Глобальные настройки задаются в разделе controller.config.entries файла values.yaml:

controller:
  config:
    entries:
      wallarm-process-timeout: "2000"
      wallarm-mode: monitoring

Параметры enable-wallarm, wallarm-upstream-service, wallarm-metrics-port и wallarm-fallback Helm‑чарт задает автоматически на основе раздела controller.wmx.

Модуль Вебмониторэкс¶

Некорректное значение игнорируется: используется значение по умолчанию, а в событиях ConfigMap появляется предупреждение (kubectl -n <KUBERNETES_NAMESPACE> describe configmap).

Настройки по умолчанию для всех Ingress¶

Каждую аннотацию Ingress можно задать глобально ключом wallarm-<название>, например wallarm-mode, wallarm-application, wallarm-parse-response. Аннотация Ingress имеет приоритет над глобальным значением.

controller:
  config:
    entries:
      wallarm-mode: monitoring
      wallarm-application: "1"

Аннотации Ingress¶

Проверка аннотаций при применении¶

Значения аннотаций prowaf.wmx.pro/ проверяются при создании и изменении Ingress (ValidatingAdmissionPolicy, Kubernetes 1.30 и выше). Ingress с некорректным значением не будет применен, а действующая конфигурация продолжит работать:

$ kubectl annotate ingress my-app prowaf.wmx.pro/mode=blocking
The ingresses "my-app" is invalid: : ValidatingAdmissionPolicy 'wmx-ingress-wmx-annotations'
with binding 'wmx-ingress-wmx-annotations' denied request: mode must be one of: off, monitoring, safe_blocking, block

Если проверка при применении отключена или не поддерживается кластером, Ingress‑контроллер проверяет аннотации сам: Ingress с некорректным значением будет отклонен, а его маршруты будут удалены из конфигурации NGINX до исправления ошибки. Причина отклонения указана в событиях Ingress (kubectl describe ingress <INGRESS_NAME>). Поэтому рекомендуем не отключать проверку при применении.

Сниппеты¶

По умолчанию сниппеты в аннотациях отключены. Глобальные директивы задавайте через http-snippets, server-snippets, location-snippets в controller.config.entries.

Если нужны сниппеты на уровне Ingress, включите controller.enableSnippets: true и используйте nginx.org/server-snippets / nginx.org/location-snippets. Эта настройка дает пользователям с правом изменения Ingress возможность менять конфигурацию NGINX.

Примеры¶

Страница блокировки и код ответа¶

Аннотация prowaf.wmx.pro/block-page задает страницу и код ответа для запросов, заблокированных по следующим причинам:

• в запросе обнаружена атака, и нода работает в режиме блокировки;
• запрос с признаками атаки отправлен с IP‑адреса из серого списка, и нода работает в режиме мягкой блокировки;
• запрос отправлен с IP‑адреса из черного списка.

Формат: одно или несколько определений через ;, каждое — <страница> [response_code=<код>] [type=<типы>], где:

• <страница> — одно из следующего:
  • URI (/blocked.html): запрос перенаправляется на этот URI внутри NGINX, ответ формирует location, который обслуживает этот URI (см. ниже);
  • именованный location (@name), его задают так же;
  • файл из каталога /usr/share/nginx/html/ (&/usr/share/nginx/html/page.html): его содержимое возвращается как страница блокировки, в тексте можно использовать переменные NGINX.
• response_code — код ответа от 100 до 599, не больше одного раза;
• type — для каких блокировок использовать страницу: attack (атака), acl_ip (IP‑адрес в черном списке), acl_source (страна, регион или дата‑центр в черном списке), acl_session (сессия в черном списке). Не больше одного раза, без повторов.

Чтобы использовать свою страницу, смонтируйте ее в под контроллера, например из ConfigMap:

controller:
  volumes:
    - name: block-pages
      configMap:
        name: block-pages
  volumeMounts:
    - name: block-pages
      mountPath: /usr/share/nginx/html/custom

и укажите ее в аннотации: prowaf.wmx.pro/block-page="&/usr/share/nginx/html/custom/blocked.html response_code=403".

Если файла нет или значение не принимает NGINX, Ingress‑контроллер исключает этот Ingress из конфигурации (событие AddedOrUpdatedWithError), остальные Ingress продолжают обновляться.

Вернуть стандартную страницу блокировки Вебмониторэкс с кодом 445 для всех блокировок:

kubectl annotate ingress <INGRESS_NAME> \
  prowaf.wmx.pro/block-page="&/usr/share/nginx/html/wallarm_blocked.html response_code=445 type=attack,acl_ip,acl_source"

Страница блокировки из location¶

Если страница задана URI или именованным location, location для нее задается сниппетом сервера: ключом server-snippets в controller.config.entries (для всех Ingress) или аннотацией nginx.org/server-snippets (нужно controller.enableSnippets: true). Например, перенаправить клиента на страницу другого сайта:

kubectl annotate ingress <INGRESS_NAME> \
  nginx.org/server-snippets='location = /blocked { return 302 https://example.com/blocked.html; }' \
  prowaf.wmx.pro/block-page="/blocked type=acl_source"

Если location страницы блокировки передает запрос дальше (proxy_pass, grpc_pass и аналоги), пометьте его директивой internal:

location = /blocked {
    internal;
    proxy_pass http://block-page.example.local/blocked.html;
}

Без internal нода не передает заблокированный запрос дальше: клиент получает код 403 (или код из response_code), а в журнале NGINX появляется ошибка block page "..." is served by location "...", which passes the request on but is not internal. Так же нода отвечает, если для URI страницы нет своего location и его обслуживает путь Ingress, то есть приложение: раньше (до 5.0.29-1) заблокированный запрос в этом случае уходил в приложение. Страницы, которые NGINX отдает сам (return, файл), работают и без internal.

Устаревшая аннотация prowaf.wmx.pro/acl-block-page задает страницу только для блокировок по черному списку: одна страница без type, параметры можно разделять пробелом или запятой.

Подробнее о странице блокировки — в статье Настройка страницы и кода блокировки.

Отключение парсеров¶

kubectl annotate ingress <INGRESS_NAME> prowaf.wmx.pro/parser-disable="base64,jwt"

Несколько Ingress для одного хоста¶

Ingress‑контроллер не принимает второй Ingress с именем хоста, которое уже используется другим Ingress того же класса. Чтобы разделить пути одного хоста между несколькими Ingress (например, с разными приложениями или режимами фильтрации), используйте объединяемые Ingress:

• master — задает хост, TLS и общие настройки; не содержит путей;
• minion — задают пути и собственные аннотации. Аннотации Вебмониторэкс master‑Ingress наследуются minion‑Ingress, если не переопределены.

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: shop-master
  annotations:
    nginx.org/mergeable-ingress-type: master
    prowaf.wmx.pro/mode: block
spec:
  ingressClassName: nginx
  tls:
    - hosts: [shop.example.com]
      secretName: shop-tls
  rules:
    - host: shop.example.com
---
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: shop-api
  annotations:
    nginx.org/mergeable-ingress-type: minion
    prowaf.wmx.pro/application: "21"
spec:
  ingressClassName: nginx
  rules:
    - host: shop.example.com
      http:
        paths:
          - path: /api
            pathType: Prefix
            backend:
              service: {name: shop-api, port: {number: 80}}
---
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: shop-web
  annotations:
    nginx.org/mergeable-ingress-type: minion
    prowaf.wmx.pro/application: "22"
    prowaf.wmx.pro/mode: monitoring
spec:
  ingressClassName: nginx
  rules:
    - host: shop.example.com
      http:
        paths:
          - path: /
            pathType: Prefix
            backend:
              service: {name: shop-web, port: {number: 80}}

В этом примере /api защищается в режиме block (унаследован от master) с приложением 21, а остальные пути — в режиме monitoring с приложением 22.

Библиотека libdetection¶

Библиотека libdetection дополнительно проверяет атаки SQL‑инъекций и снижает количество ложных срабатываний. По умолчанию она выключена. Чтобы включить ее для всех Ingress:

controller:
  config:
    entries:
      http-snippets: |
        wallarm_enable_libdetection on;

Включение защиты от ботов¶

Защита от ботов (Smart Bot Protection) проверяет, что запросы отправляет браузер, а не бот. Включите ее для Ingress:

kubectl annotate ingress <INGRESS_NAME> \
  prowaf.wmx.pro/antibot-mode=block \
  prowaf.wmx.pro/antibot-location-type=landing

Для всех Ingress режим и тип проверки задаются ключами wallarm-antibot-mode и wallarm-antibot-location-type в controller.config.entries.

В каждом сервере (хосте), где защита включена хотя бы для одного пути, Ingress‑контроллер добавляет location /v1/antibot — API проверки браузера. Не используйте этот путь в приложениях: Ingress с ним будет исключен из конфигурации.

API проверки один на хост, поэтому на одном хосте защиту от ботов можно включить для путей только одного приложения (prowaf.wmx.pro/application). API использует приложение первого пути с включенной защитой; если на хосте защита включена для путей разных приложений, Ingress‑контроллер добавляет в события Ingress предупреждение, а проверка браузера в путях остальных приложений не проходит.

Настройки в Консоли управления. Режим и тип проверки можно задать и в Консоли управления, в правилах защиты от ботов для приложения и пути. Такие правила действуют только там, где защита включена аннотацией prowaf.wmx.pro/antibot-mode или ключом wallarm-antibot-mode: без нее защита для пути выключена, и правила Консоли не применяются. Режим из Консоли может только ослабить режим аннотации: при аннотации block правило Консоли может установить monitoring или off, а при аннотации monitoring правило block не блокирует запросы. Тип проверки из Консоли заменяет тип из аннотации. Чтобы управлять защитой из Консоли, задайте аннотацию prowaf.wmx.pro/antibot-mode: block, а тип проверки и режим для отдельных путей — в Консоли.

Мультиарендная нода¶

Если в аккаунте включена мультиарендность, укажите для Ingress идентификатор тенанта и приложения тенанта:

kubectl annotate ingress <INGRESS_NAME> \
  prowaf.wmx.pro/partner-client-uuid=<TENANT_UUID> \
  prowaf.wmx.pro/application=<APPLICATION_ID>

• Установка Ingress‑контроллера Вебмониторэкс
• Повышение стабильности работы
• Миграция с предыдущей версии Ingress‑контроллера