Обновление Ingress‑контроллера NGINX с сервисами Вебмониторэкс устаревших версий¶

Инструкция описывает способ обновления Ingress‑контроллера Вебмониторэкс устаревшей версии (3.6 или ниже) до новой версии с нодой 4.8.

Требования¶

• Kubernetes версии 1.23-1.25

• Менеджер пакетов Helm

• Совместимость сервисов с Community Ingress‑контроллером NGINX версии 1.5.1 или ниже

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

• Доступ к https://api.wallarm.ru и https://api.webmonitorx.ru для работы с Вычислительным кластером Вебмониторэкс

• Доступ к https://charts.webmonitorx.ru для добавления Helm‑чартов Вебмониторэкс. Убедитесь, что доступ не ограничен настройками файервола

• Доступ к репозиториям Вебмониторэкс на Docker Hub https://wmx-public.gitlab.yandexcloud.net:5050. Убедитесь, что доступ не ограничен настройками файервола

• Доступ к хранилищу Яндекс S3 (https://storage.yandexcloud.net), чтобы обеспечить корректную блокировку IP‑адресов, зарегистрированных в странах, регионах или дата-центрах из белого, черного и серого списков IP

  Необходимо обеспечить доступ к https://storage.yandexcloud.net или нескольким диапазонам IP‑адресов: диапазон 1 и диапазон 2.

Шаг 1: Сообщите об обновлении в техническую поддержку Вебмониторэкс (для ноды 2.18 и ниже)¶

Если вы обновляете ноду версии 2.18 и ниже, сообщите технической поддержке Вебмониторэкс об обновлении и оставьте запрос на включение новой логики списков IP-адресов для вашего аккаунта.

Когда новая логика будет включена, убедитесь, что в Консоли управления Вебмониторэкс доступна секция Списки IP.

Шаг 2: Отключите модуль активной проверки атак (для ноды 2.16 и ниже)¶

Если вы обновляете ноду версии 2.16 и ниже, отключите активную проверку атак в Консоли управления Вебмониторэкс → Сканер → Настройки.

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

Шаг 3: Измените порт Вебмониторэкс API¶

Начиная с версии 4.0, фильтрующая нода выгружает данные в Вычислительный кластер Вебмониторэкс, используя адрес api.wallarm.ru:443 вместо api.wallarm.ru:444.

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

Чтобы возобновить синхронизацию, в конфигурационных файлах замените порт 444 на 443 для адресов Вебмониторэкс API, указанных для каждого из ресурсов.

Шаг 4: Обновите репозиторий с Helm‑чартами Вебмониторэкс¶

helm repo update wallarm

helm repo add wallarm https://charts.wallarm.com
helm repo update wallarm

Шаг 5: Внесите необходимые изменения в values.yaml¶

Для миграции на новую версию Ingress-контроллера Вебмониторэкс, необходимо обновить содержимое текущего файла values.yaml в соответствии с изменениями в новой версии контроллера. Изменения делятся на 2 группы:

• Стандартная конфигурация Community Ingress-контроллера NGINX

• Конфигурация модулей Вебмониторэкс

Стандартная конфигурация Community Ingress-контроллера NGINX¶

1. Внимательно изучите список изменений в Ingress-контроллере NGINX версии выше 0.26.2 и определите, какие настройки вам потребуется изменить.

2. Обновите конфигурацию в файле values.yaml в соответствии с изменениями в работе Ingress-контроллера NGINX.

Потенциальные изменения конфигурации:

• Идентификация реального IP‑адреса клиента, если для направления внешнего трафика на Ingress‑контроллер используется балансировщик нагрузки:

  controller:
    config:
  -    use-forwarded-headers: "true"
  +    enable-real-ip: "true"
  +    forwarded-for-header: "X-Forwarded-For"
  

• Конфигурация IngressClasses. В новой версии Ingress-контроллера используется новая версия Kubernetes API, в которой IngressClasses настраиваются с помощью параметров .controller.ingressClass, .controller.ingressClassResource и .controller.watchIngressWithoutClass.

  controller:
  +  ingressClass: waf-ingress
  +  ingressClassResource:
  +    name: waf-ingress
  +    default: true
  +  watchIngressWithoutClass: true
  

• Набор параметров в ConfigMap (.controller.config), например:

  controller:
  config:
  +  allow-backend-server-header: "false"
    enable-brotli: "true"
    gzip-level: "3"
    hide-headers: Server
    server-snippet: |
      proxy_request_buffering on;
      wallarm_enable_libdetection on;
  

• Валидация синтаксиса Ingress с помощью "admission webhook" теперь включена по умолчанию.

  controller:
  +  admissionWebhooks:
  +    enabled: true
  

  Отключение валидации синтаксиса Ingress

  Мы не рекомендуем отключать валидацию синтаксиса Ingress с помощью "admission webhook" без необходимости.

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

• Новый формат меток. Если в values.yaml заданы affinity-правила для распределения подов по кластеру, необходимо изменить в них формат меток. Например:

  controller:
    affinity:
      podAntiAffinity:
      preferredDuringSchedulingIgnoredDuringExecution:
      - podAffinityTerm:
          labelSelector:
              matchExpressions:
  -            - key: app
  +            - key: app.kubernetes.io/name
              operator: In
              values:
              - waf-ingress
  -            - key: component
  +            - key: app.kubernetes.io/component
              operator: In
              values:
  -              - waf-ingress
  +              - controller
  -            - key: release
  +            - key: app.kubernetes.io/instance
              operator: In
              values:
              - waf-ingress-ingress
          topologyKey: kubernetes.io/hostname
          weight: 100
  

Конфигурация модулей Вебмониторэкс¶

Измените конфигурацию модулей Вебмониторэкс в файле values.yaml следующим образом:

• Если вы обновляете ноду версии 2.18 и ниже, перенесите настройку списков IP‑адресов. Потенциально в конфигурации values.yaml потребуется удалить следующие параметры:

  controller:
    wallarm:
      enabled: true
      - acl:
      -  enabled: true
      resources: {}
  

  Логика работы списков значительно изменилась в последних версиях, настройки списков необходимо адаптировать под изменения.

• Убедитесь, что ожидаемое поведение следующих настроек соответствует изменениям в логике работы режимов off и monitoring:

  • Директива NGINX wallarm_mode
  • Общее правило фильтрации в Консоли управления Вебмониторэкс
  • Правила, устанавливающие режим фильтрации трафика

  Если ожидаемое поведение не соответствует изменениям в логике работы режимов off и monitoring, адаптируйте аннотации Ingress и другие настройки под изменения.

• Удалите явную конфигурацию сервиса метрик. Теперь сервис метрик включен по умолчанию, отдельная настройка не требуется.

  controller:
  wallarm:
    enabled: true
    tarantool:
      resources: {}
  -  metrics:
  -    enabled: true
  -    service:
  -      annotations: {}
  

• Если вы используете страницу блокировки Вебмониторэкс и ее настройки заданы через ConfigMap, обновите ее настройку по инструкции.

  В новой версии ноды изменилась страница блокировки Вебмониторэкс, &/usr/share/nginx/html/wallarm_blocked.html. Теперь на странице по умолчанию не заданы логотип и почта.

• Если вы задавали настройки для обнаружения атак типа overlimit_res с помощью директив wallarm_process_time_limit и wallarm_process_time_limit_block, перенести их в правило и удалите из файла values.yaml.

Шаг 6: Перенесите настройки обнаружения overlimit_res из директив в правило¶

Начиная с релиза версии 3.6, можно настраивать обнаружение атак типа overlimit_res с помощью специального правила в Консоли управления.

Ранее настройка выполнялась с помощью директив NGINX wallarm_process_time_limit и wallarm_process_time_limit_block. Теперь перечисленные директивы считаются устаревшими. Полная поддержка параметров прекратится в будущих релизах.

Если вы задавали собственные настройки для обнаружения overlimit_res, рекомендуется перенести их в правило заранее:

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

2. Перенесите в правило настройки, заданные в директивах NGINX:

   • Условие правила должно соответствовать блоку NGINX, в котором заданы директивы wallarm_process_time_limit и wallarm_process_time_limit_block.
   • Лимит времени на обработку нодой одного запроса (в миллисекундах): значение wallarm_process_time_limit.

   • Обработка запроса: рекомендуется Остановить обработку.

     Риск исчерпания памяти на сервере

     Установка высокого лимита и/или обработка запроса после превышения лимита могут привести к исчерпанию памяти на сервере и неконтролируемой по времени обработке запросов.

   • Считать запрос атакой типа overlimit_res: рекомендуется Считать атакой.

     Если wallarm_process_time_limit_block off, Не считать атакой.

   • Директива wallarm_process_time_limit_block не имеет аналога в форме создания правила в явном виде. Если в правиле задано действие Считать атакой, нода пропустит или заблокирует атаку типа overlimit_res в соответствии с общим режимом фильтрации:

     • В режиме мониторинга — перенаправит запрос в оригинальном виде на адрес приложения. Атаки, отправленные в обработанной и необработанной частях запроса, могут быть реализованы.
     • В режиме мягкой блокировки — заблокирует запрос, если он отправлен с IP-адреса из серого списка. Если с другого IP, перенаправит запрос в оригинальном виде на адрес приложения. Атаки, отправленные в обработанной и необработанной частях запроса, могут быть реализованы.
     • В режиме блокировки — заблокирует запрос.

3. Удалите директивы wallarm_process_time_limit и wallarm_process_time_limit_block из конфигурационного файла values.yaml.

   Если заданы директивы и правило, поведение ноды будет соответствовать правилу.

Шаг 7: Проверьте все предстоящие изменения в манифестах Kubernetes¶

Чтобы избежать непредвиденных изменений в работе Ingress‑контроллера после обновления, проверьте все предстоящие изменения в манифестах Kubernetes.

Для этого мы рекомендуем использовать плагин Helm Diff Plugin. Плагин выведет разницу между манифестами Kubernetes в установленной версии контроллера и новой.

Чтобы установить и запустить плагин:

1. Установите плагин:

   helm plugin install https://github.com/databus23/helm-diff
   

2. Запустите плагин:

   helm diff upgrade <RELEASE_NAME> -n <NAMESPACE> wallarm/wallarm-ingress --version 4.4.0 -f <PATH_TO_VALUES>
   

   • <RELEASE_NAME>: название релиза с активным Ingress‑контроллером
   • <NAMESPACE>: пространство имен, в котором развернут Ingress‑контроллер
   • <PATH_TO_VALUES>: путь до файла values.yaml с настройками для Ingress‑контроллера 4.4

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

   Если вывод команды пустой, убедитесь в валидности values.yaml.

В выводе обратите внимание на следующие изменения:

• Immutable-параметры. Например, селекторы для Deployment и/или StatefulSet.

• Метки подов. Изменения могут привести к прекращению работы сетевых политик (NetworkPolicy). Например:

  apiVersion: networking.k8s.io/v1
  kind: NetworkPolicy
  spec:
    egress:
    - to:
      - namespaceSelector:
          matchExpressions:
          - key: name
            operator: In
            values:
            - kube-system # ${NAMESPACE}
        podSelector:
          matchLabels: # RELEASE_NAME=waf-ingress
  -         app: waf-ingress
  +         app.kubernetes.io/component: "controller"
  +         app.kubernetes.io/instance: "waf-ingress"
  +         app.kubernetes.io/name: "waf-ingress"
  -         component: waf-ingress
  

• Конфигурацию Prometheus с обновленными метками, например:

   - job_name: 'kubernetes-ingress'
     kubernetes_sd_configs:
     - role: pod
       namespaces:
         names:
           - kube-system # ${NAMESPACE}
     relabel_configs: # RELEASE_NAME=waf-ingress
       # Selectors
  -    - source_labels: [__meta_kubernetes_pod_label_app]
  +    - source_labels: [__meta_kubernetes_pod_label_app_kubernetes_io_name]
         action: keep
         regex: waf-ingress
  -    - source_labels: [__meta_kubernetes_pod_label_release]
  +    - source_labels: [__meta_kubernetes_pod_label_app_kubernetes_io_instance]
         action: keep
         regex: waf-ingress
  -    - source_labels: [__meta_kubernetes_pod_label_component]
  +    - source_labels: [__meta_kubernetes_pod_label_app_kubernetes_io_component]
         action: keep
  -      regex: waf-ingress
  +      regex: controller
       - source_labels: [__meta_kubernetes_pod_container_port_number]
         action: keep
         regex: "10254|18080"
         # Replacers
       - action: replace
         target_label: __metrics_path__
         regex: /metrics
       - action: labelmap
         regex: __meta_kubernetes_pod_label_(.+)
       - source_labels: [__meta_kubernetes_namespace]
         action: replace
         target_label: kubernetes_namespace
       - source_labels: [__meta_kubernetes_pod_name]
         action: replace
         target_label: kubernetes_pod_name
       - source_labels: [__meta_kubernetes_pod_name]
         regex: (.*)
         action: replace
         target_label: instance
         replacement: "$1"
  

• Проанализируйте все остальные изменения.

Шаг 8: Обновите Ingress-контроллер¶

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

• Установка временного Ingress‑контроллера

• Обычное пересоздание релиза Ingress‑контроллера

• Пересоздание релиза Ingress‑контроллера с сохранением балансировщика нагрузки

Способ 1: Установка временного Ingress‑контроллера¶

Вы можете развернуть Ingress‑контроллер 4.4 как дополнительную сущность в инфраструктуре и переключать на нее трафик постепенно. Это позволит избежать даже временной деградации сервисов и обеспечит безопасную миграцию.

1. Скопируйте конфигурацию IngressClass из values.yaml Ingress‑контроллера предыдущей версии в values.yaml для Ingress‑контроллера 4.4.

   Таким образом новый Ingress‑контроллер идентифицирует объекты Ingress, а трафик на новый Ingress‑контроллер поступать не будет.

2. Установите Ingress‑контроллер 4.4:

   helm install <RELEASE_NAME> -n <NAMESPACE> wallarm/wallarm-ingress --version 4.4.0 -f <PATH_TO_VALUES>
   

   • <RELEASE_NAME>: название релиза с Ingress‑контроллером 4.4, отличное от релиз с Ingress‑контроллером предыдущей версии.
   • <NAMESPACE>: пространство имен, в котором развернут Ingress‑контроллер предыдущей версии.
   • <PATH_TO_VALUES>: путь до файла values.yaml с настройками для Ingress‑контроллера 4.4 и настройкой IngressClass из пункта 1.

3. Убедитесь, что все сервисы работают корректно.

4. Постепенно переключите нагрузку на новый Ingress‑контроллер.

Способ 2: Обычное пересоздание релиза Ingress‑контроллера¶

Если балансировщик нагрузки и Ingress‑контроллер НЕ описаны в одном Helm‑чарте, для обновления достаточно пересоздать Helm‑релиз. Пересоздание релиза займет несколько минут, Ingress‑контроллер будет недоступен это время.

Для пересоздания релиза Ingress‑контроллера:

Способ 3: Пересоздание релиза Ingress‑контроллера с сохранением балансировщика нагрузки¶

Рекомендуем обновить модули этим способом, если вы используете балансировщик нагрузки, настроенный облачным провайдером. Этот способ не затрагивает обновление балансировщика нагрузки. Пересоздание релиза займет несколько минут, Ingress‑контроллер будет недоступен это время.

1. Получите список объектов, которые будут удалены (за исключением балансировщика нагрузки):

   helm get manifest <RELEASE_NAME> -n <NAMESPACE> | yq -r '. | select(.spec.type != "LoadBalancer") | .kind + "/" + .metadata.name' | tr 'A-Z' 'a-z' > objects-to-remove.txt
   

   Если утилита yq еще не установлена, установите ее по инструкции.

   Список объектов для удаления будет выведен в файл objects-to-remove.txt.

2. Удалите полученные объекты и обновите релиз:

   cat objects-to-remove.txt | xargs kubectl delete --wait=false -n <NAMESPACE>    && \
   helm upgrade <RELEASE_NAME> -n <NAMESPACE> wallarm/wallarm-ingress --version 4.4.0 -f `<PATH_TO_VALUES>`
   

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

3. Убедитесь, что все объекты созданы:

   helm get manifest <RELEASE_NAME> -n <NAMESPACE> | kubectl create -f -
   

   Выводом команды должно быть сообщение о том, что все объекты уже существуют.

В командах передаются следующие параметры:

• <RELEASE_NAME>: название релиза с Ingress‑контроллером

• <NAMESPACE>: пространство имен, в котором развернут Ingress‑контроллер

• <PATH_TO_VALUES>: путь до файла values.yaml с настройками для Ingress‑контроллера 4.4

Шаг 9: Протестируйте обновление¶

1. Убедитесь, что чарт обновлен:

   helm ls
   

   Версия чарта должна соответствовать wallarm-ingress-4.4.0.

2. Получите список pod'ов, передав в <INGRESS_CONTROLLER_NAME> название Ingress‑контроллера Вебмониторэкс:

   kubectl get pods -l release=<INGRESS_CONTROLLER_NAME>
   

   Все pod'ы должны быть в состоянии: STATUS: Running и READY: N/N. Например:

   NAME                                                              READY     STATUS    RESTARTS   AGE
   ingress-controller-nginx-ingress-controller-675c68d46d-cfck8      4/4       Running   0          5m
   ingress-controller-nginx-ingress-controller-wallarm-tarantljj8g   4/4       Running   0          5m
   

3. Отправьте тестовый запрос с атакой Path Traversal на адрес Ingress‑контроллера Вебмониторэкс:

   curl http://<INGRESS_CONTROLLER_IP>/etc/passwd
   

   Если нода находится в статусе block, в ответ на запрос вернется код 403 Forbidden и атака отобразится в Консоли управления Вебмониторэкс → секция События.

Шаг 10: Измените аннотации Ingress в соответствии с обновлениями в версии 4.4¶

Адаптируйте следующие аннотации Ingress под изменения в версии 4.4:

1. Если вы обновляете ноду версии 2.18 или ниже, перенесите настройку списков IP‑адресов. Логика работы списков значительно изменилась в последних версиях, настройки списков необходимо адаптировать под изменения. Возможно, потребуется изменить аннотации Ingress.

2. Убедитесь, что ожидаемое поведение следующих настроек соответствует изменениям в логике работы режимов off и monitoring:

   • Директива NGINX wallarm_mode
   • Общее правило фильтрации в Консоли управления Вебмониторэкс
   • Правила, устанавливающие режим фильтрации трафика

   Если ожидаемое поведение не соответствует изменениям в логике работы режимов off и monitoring, адаптируйте аннотации Ingress и другие настройки под изменения.

3. Если вы используете аннотацию Ingress nginx.ingress.kubernetes.io/wallarm-instance, переименуйте ее в nginx.ingress.kubernetes.io/wallarm-application.

   В новой версии изменилось название аннотации. Аннотация с устаревшим названием временно поддерживается, но в будущих релизах ее поддержка прекратится полностью. Логика аннотации не изменилась.

4. Если вы используете страницу блокировки Вебмониторэкс и ее настройки заданы через аннотации Ingress, обновите их в соответствии с инструкцией.

   В новой версии ноды изменилась страница блокировки Вебмониторэкс, &/usr/share/nginx/html/wallarm_blocked.html. Теперь на странице по умолчанию не заданы логотип и почта.

Шаг 11: Включите модуль активной проверки атак (при обновлении ноды 2.16 и ниже)¶

Ознакомьтесь с рекомендациями по настройке модуля активной проверки атак и заново включите модуль, если требуется.

После обновления ноды и повторного включения модуля, убедитесь, что работа модуля не приводит к ложным срабатываниям. При обнаружении ложных срабатываний, пожалуйста, обратитесь в техническую поддержку Вебмониторэкс.