Установка Ingress-контроллера Вебмониторэкс в Kubernetes¶

Ingress‑контроллер Вебмониторэкс – Ingress‑контроллер NGINX для Kubernetes со встроенной фильтрующей нодой Вебмониторэкс. Он принимает внешний трафик кластера, анализирует каждый запрос, блокирует атаки и передает легитимные запросы вашим сервисам.

С помощью этой инструкции вы развернете Ingress‑контроллер Вебмониторэкс с помощью Helm, включите защиту для своих Ingress и проверите, что атаки обнаруживаются и блокируются.

Как это работает¶

Helm-чарт разворачивает:

Каждый pod контроллера и постаналитики при запуске регистрируется в Консоли управления как нода.

Требования¶

• Kubernetes 1.25 и выше. В Kubernetes ниже 1.30 проверка через ValidatingAdmissionPolicy не устанавливается.

• Узлы с архитектурой x86_64 (amd64).

• Helm 3.8.0 и выше.

• Доступ к аккаунту с ролью Администратор в Консоли управления Вебмониторэкс.

• Доступ из кластера к следующим адресам:

Загрузка чарта и образов не требует авторизации. Образы подписаны с помощью cosign, к ним приложены SBOM.

Ограничения¶

• Работа без постаналитики не поддерживается: она устанавливается вместе с нодой.

• При уменьшении количества pod постаналитики или их перезапуске могут теряться данные об атаках, которые еще не выгружены из памяти Tarantool.

• Фильтрация Вебмониторэкс работает только для ресурсов Ingress. Контроллер обрабатывает VirtualServer и VirtualServerRoute, но трафик этих ресурсов не фильтруется; предупреждение отображается в событиях и статусе ресурса.

• Два обычных Ingress одного класса не могут использовать один хост: второй ресурс отклоняется. Для разделения путей одного хоста используйте объединяемые Ingress с ролями master и minion (nginx.org/mergeable-ingress-type).

• Сниппеты в аннотациях Ingress по умолчанию отключены.

Установка¶

1. Создайте ноду и сохраните ее токен.

2. Установите Ingress‑контроллер Вебмониторэкс.

3. Включите защиту для своих Ingress.

4. Проверьте работу.

В примерах используются:

• <KUBERNETES_NAMESPACE> — пространство имен контроллера;

• <RELEASE_NAME> — имя установки Helm; для приведенных ниже имен ресурсов используйте wmx-ingress;

• <NODE_TOKEN> — токен ноды из Консоли управления;

• <INGRESS_NAMESPACE> и <INGRESS_NAME> — пространство имен и имя защищаемого Ingress;

• <APPLICATION_ID> — положительное целое число, идентификатор приложения для разделения атак и статистики.

Шаг 1: Создание ноды¶

1. Перейдите в Консоль управления Вебмониторэкс → Ноды.

2. Создайте ноду и скопируйте сгенерированный токен.

Токен используется всеми pod'ами Ingress‑контроллера и постаналитики для регистрации в Вычислительном кластере.

Шаг 2: Установка Ingress‑контроллера¶

1. Создайте пространство имен и Secret с токеном ноды:

   kubectl create namespace <KUBERNETES_NAMESPACE>
   kubectl -n <KUBERNETES_NAMESPACE> create secret generic wmx-node-token \
     --from-literal=token=<NODE_TOKEN>
   

   • <KUBERNETES_NAMESPACE> — пространство имен, в котором будет развернут Ingress‑контроллер;
   • <NODE_TOKEN> — токен ноды из шага 1.

   Токен в values.yaml

   Токен можно также указать в параметре controller.wmx.token файла values.yaml — тогда Secret создаст Helm‑чарт. Хранить токен в отдельном Secret безопаснее: он не попадает в файлы с настройками и в историю Helm‑релиза.

2. Создайте файл values.yaml с минимальной конфигурацией:

   controller:
     wmx:
       enable: true
       existingSecret:
         name: wmx-node-token
     service:
       externalTrafficPolicy: Local
   

   Параметр externalTrafficPolicy: Local сохраняет IP‑адреса клиентов: без него в Консоли управления в качестве источника атак может отображаться внутренний адрес кластера. Подробнее — в статье Определение IP‑адреса клиента.

   Все параметры описаны в статье Настройка Ingress‑контроллера Вебмониторэкс.

   Сертификат API, выпущенный собственным удостоверяющим центром

   Для on‑premise установки укажите адрес ее API в controller.wmx.api.host. Если сертификат API выпущен внутренним удостоверяющим центром, передайте ноде его сертификат (PEM) через Secret и параметр controller.wmx.api.caSecret:

   kubectl -n <KUBERNETES_NAMESPACE> create secret generic wmx-api-ca --from-file=ca.crt=<PATH_TO_CA_PEM>
   

   controller:
     wmx:
       api:
         host: <API_HOST>
         caSecret:
           name: wmx-api-ca
   

3. Установите Helm‑чарт:

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

   • <RELEASE_NAME> — название установки (Helm release), например wmx-ingress. От него зависят имена ресурсов: при wmx-ingress — wmx-ingress-controller и wmx-ingress-wmx-postanalytics, при другом названии, например waf, — waf-wmx-ingress-controller и т. д. Примеры в документации приведены для установки wmx-ingress.

4. Убедитесь, что все pod'ы запущены:

   kubectl -n <KUBERNETES_NAMESPACE> get pods
   

   Все pod'ы должны быть в состоянии Running, а все контейнеры — готовы:

   NAME                                             READY   STATUS    RESTARTS   AGE
   wmx-ingress-controller-7449d9456c-mc8f9          10/10   Running   0          2m
   wmx-ingress-wmx-postanalytics-6df954464d-r6g99   15/15   Running   0          2m
   

5. Узнайте название класса Ingress и внешний адрес Ingress‑контроллера:

   kubectl get ingressclass
   kubectl -n <KUBERNETES_NAMESPACE> get service
   

   По умолчанию класс называется nginx. Внешний адрес указан в столбце EXTERNAL-IP сервиса типа LoadBalancer.

Шаг 3: Включение защиты Ingress¶

Ingress‑контроллер обрабатывает ресурсы Ingress своего класса (поле spec.ingressClassName). Анализ трафика включается для каждого Ingress аннотациями с префиксом prowaf.wmx.pro/:

• prowaf.wmx.pro/mode — режим фильтрации: off, monitoring, safe_blocking или block;
• prowaf.wmx.pro/application — идентификатор приложения: положительное число, по которому в Консоли управления разделяются атаки и статистика разных приложений.

Для существующего Ingress:

kubectl -n <INGRESS_NAMESPACE> annotate ingress <INGRESS_NAME> \
  prowaf.wmx.pro/mode=monitoring \
  prowaf.wmx.pro/application=<APPLICATION_ID>

Или в манифесте Ingress:

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: my-app
  annotations:
    prowaf.wmx.pro/mode: monitoring
    prowaf.wmx.pro/application: "12"
spec:
  ingressClassName: nginx
  rules:
    - host: app.example.com
      http:
        paths:
          - path: /
            pathType: Prefix
            backend:
              service:
                name: my-app
                port:
                  number: 80

Без аннотации prowaf.wmx.pro/mode трафик Ingress не анализируется (режим off), если в настройках не задан другой режим по умолчанию.

Шаг 4: Проверка работы¶

1. Отправьте тестовый запрос с атакой Path Traversal на адрес вашего приложения:

   curl "https://app.example.com/?file=../../../../etc/passwd"
   

   В режиме block в ответ вернется код 403 Forbidden. В режиме monitoring запрос будет передан приложению.

2. Перейдите в Консоль управления Вебмониторэкс → События. Через 1–2 минуты атака отобразится в списке с IP‑адресом вашего клиента.

3. Перейдите в раздел Ноды: в нем отображаются зарегистрированные pod'ы Ingress‑контроллера и постаналитики.

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

Обновление настроек¶

Чтобы изменить параметры установленного Ingress‑контроллера, отредактируйте values.yaml и выполните команду ниже.

Вместо <CHART_VERSION> укажите текущую установленную версию Helm‑чарта, чтобы изменить настройки без обновления контроллера до другой версии.

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

Обновление до новой версии¶

Ниже приведены команды обновления до версии Helm-чарта 5.0.32-1.

Версия Ingress‑контроллера совпадает с версией ноды Вебмониторэкс: <версия ноды>-<сборка>, например, 5.0.32-1. Новая сборка при той же версии ноды выпускается для исправлений в самом Ingress‑контроллере.

1. Обновите CRD: helm upgrade не обновляет CRD, которые уже установлены в кластере.

   helm pull oci://registry.webmonitorx.ru/public/charts/wmx-ingress --version 5.0.32-1 --untar
   kubectl apply --server-side --force-conflicts -f wmx-ingress/crds/
   

2. Обновите установку:

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

3. Проверьте работу, как после установки (см. Шаг 4: Проверка работы).

Pod'ы Ingress‑контроллера обновляются поочередно, без прерывания обработки запросов. Pod'ы постаналитики перезапускаются: Tarantool хранит запросы в памяти, поэтому атаки, которые не успели выгрузиться в Вычислительный кластер, при перезапуске теряются. Обновляйтесь в период низкой нагрузки; при controller.wmx.postanalytics.replicaCount больше 1 pod'ы постаналитики тоже обновляются поочередно.

Откат¶

Верните предыдущую версию установки:

helm history <RELEASE_NAME> -n <KUBERNETES_NAMESPACE>
helm rollback <RELEASE_NAME> <REVISION> -n <KUBERNETES_NAMESPACE>

helm rollback не откатывает CRD. Если нужно вернуть и их, примените CRD предыдущей версии чарта так же, как при обновлении (helm pull ... --version <PREVIOUS_VERSION>).

Удаление¶

helm uninstall <RELEASE_NAME> -n <KUBERNETES_NAMESPACE>

Ноды, зарегистрированные pod'ами Ingress‑контроллера и постаналитики, остаются в Консоли управления. Удалите их в разделе Ноды, если они больше не нужны.

Определение IP-адреса клиента¶

Для сохранения адреса при внешнем доступе через Service задайте controller.service.externalTrafficPolicy: Local.

Если балансировщик устанавливает собственное соединение с контроллером, дополнительно настройте доверенные адреса и способ передачи IP.

Пример для X-Forwarded-For:

controller:
  config:
    entries:
      real-ip-header: "X-Forwarded-For"
      set-real-ip-from: "192.0.2.0/24,198.51.100.10"
      real-ip-recursive: "true"

Замените адреса примера адресами своих балансировщиков. Не указывайте 0.0.0.0/0: это позволяет подменить адрес источника через заголовок.

Если балансировщик использует PROXY protocol:

controller:
  config:
    entries:
      proxy-protocol: "true"
      real-ip-header: "proxy_protocol"
      set-real-ip-from: "192.0.2.0/24"

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

Рекомендации для рабочей среды¶

• Разверните минимум два pod контроллера на разных узлах и настройте PodDisruptionBudget.

• Задайте запросы и ограничения ресурсов по результатам измерений на своей нагрузке. При перезагрузке NGINX потребление памяти временно увеличивается.

• Для HPA необходимы metrics-server и запросы ресурсов у всех контейнеров pod.

• Постаналитику рекомендуется развернуть минимум в двух pod на разных узлах. Это не исключает потерю данных из памяти отдельного pod при его остановке.

• Выделите Tarantool память для хранения запросов за 5–15 минут. Память контейнера должна превышать arena не менее чем на 20%. Если ресурсы не заданы явно, чарт запрашивает arena + 128 МиБ.

• Для часто масштабируемых сервисов можно использовать nginx.org/use-cluster-ip: "true", чтобы изменения набора pod не вызывали перезагрузку NGINX. При этом недоступны привязка сессий, балансировка по pod средствами NGINX и повтор запроса на другом pod.

При controller.wmx.fallback: "on" контроллер может обслуживать трафик без анализа, если нода не зарегистрировалась или не загрузила правила. При "off" pod не запустится, пока нода не зарегистрируется и не загрузит правила. Выбирайте режим с учетом требований к доступности приложения и непрерывности защиты.

Мониторинг и диагностика¶

Контроллер предоставляет два набора метрик Prometheus:

Следите за ростом wallarm_requests_lost, wallarm_tnt_errors, wallarm_memfaults, wallarm_proton_errors, wallarm_segfaults и за состоянием wallarm_proton_instances{status="fallback"} / {status="failed"}. Состояние fallback означает работу без анализа запросов.

Для установки с именем wmx-ingress и типом Deployment:

kubectl -n <KUBERNETES_NAMESPACE> get pods -o wide
kubectl -n <KUBERNETES_NAMESPACE> describe pod <POD_NAME>
kubectl -n <INGRESS_NAMESPACE> describe ingress <INGRESS_NAME>
kubectl -n <KUBERNETES_NAMESPACE> logs deploy/wmx-ingress-controller -c addnode
kubectl -n <KUBERNETES_NAMESPACE> logs deploy/wmx-ingress-controller -c syncnode --tail=20
kubectl -n <KUBERNETES_NAMESPACE> logs deploy/wmx-ingress-controller -c wmx-ingress --tail=20
kubectl -n <KUBERNETES_NAMESPACE> logs deploy/wmx-ingress-wmx-postanalytics -c export-attacks --tail=20

При другом имени установки или типе ресурса замените имена в командах фактическими.

Если атаки не появляются, проверьте класс и события Ingress, режим фильтрации, загрузку правил, доступность постаналитики и журнал export-attacks. При ошибке регистрации проверьте токен, доступ к API и доверие сертификату API.

• Настройка Ingress‑контроллера: параметры Helm‑чарта, ConfigMap и аннотации
• Определение IP‑адреса клиента при работе через балансировщик
• Повышение стабильности работы
• Мониторинг и диагностика
• Блокировка запросов по IP‑адресам
• Миграция с предыдущей версии Ingress‑контроллера