Руководство по установке#

Системные требования#

Инструмент установки#

Установка дистрибутива производится с использованием одного из вариантов:

• Ручная установка с использованием инструмента установки Platform V Monitor (OPM), расположенного в дистрибутиве по пути package/bh/installer/deploy-pvm.zip (инструкция по его использованию находится внутри архива)

• Автоматизированная установка (опционально) компонентом Deploy tools в составе Platform V DevOps Tools (DOT) версии не ниже release/D-01.039.049-886

Среда контейнеризации#

Для установки компонентов сервиса в рекомендуемой конфигурации требуется наличие двух (в раздельных георезервированных ЦОД) собственных namespace в среде контейнеризации Kubernetes или OpenShift (опционально) с одинаковыми квотами и следующими пререквизитами:

1. Подключен Platform V Synapse Service Mesh (SSM) (Istio)

2. Заполнен файл multiClusters.json в common репозитории с указанием обоих кластеров, для каждого из которых обязательно заданы (названия одинаковы для всех поддерживаемых сред контейнеризации):

   1. openshiftCluster - адрес для API запросов к кластеру

   2. openshiftProjectName - название namespace

   3. openshiftSATokenCred - имя credential с типом Secret Text, в котором сохранен токен Service Account для данного namespace с ролью edit

   4. openshiftAppsDomain - домен для Ingress (в формате apps...xxxx.ru)

   5. alrt.k8s.clusters.current - название текущего кластера для идентификации внутри Alert Manager

3. Создан секрет с типом «Image Pull Secret», содержащий логин и пароль для загрузки образов из registry

Образы контейнеров#

Для работы Platform V Monitor Alert Manager (ALRT) требуется наличие в registry следующих образов контейнеров:

1. Образы контейнеров сервисов компонента. Должны быть собраны из дистрибутива с использованием одного из базовых образов с OpenJDK 1.8:

   • На базе ALT Linux: alt-sp8/openjdk-1.8.0:v0.4.10

   • На базе Red Hat Enterprise Linux: redhat-openjdk-18/openjdk18-openshift:1.8-30 (опционально)

2. Образы для использования на ingress/egress

   1. Образ Nginx. Инструкция по сборке расположена в дистрибутиве по пути package/bh/installer/images/nginx

   2. Образ Envoy, предоставляемый Platform V Synapse Service Mesh (SSM)

   3. Образ sidecar OTT, предоставляемый Platform V One-Time-Token (OTT)

3. Образ FluentBit для отправки логов, предоставляемый компонентом Журналирование (LOGA) в составе Platform V Monitor (OPM)

Platform V Pangolin SE (PSQ)#

Для работы компонентов сервиса требуется внешняя база данных Platform V Pangolin SE (PSQ) со следующими пререквизитами:

1. Версия 4.4.0+ (ядро 11.12+) в конфигурации cluster-patroni-etcd-pgbouncer

2. Минимальные требования к аппаратным ресурсам (CPU/MEM/HDD) - 4/16/200 на каждую из реплик

3. Наличие в одной базе данных раздельных схем (названия схем могут быть настроены в файле conf/custom_property.conf.yml в репозитории настроек компонента), настроенных согласно рекомендациям Platform V Pangolin SE:

   1. almgr_alerting

   2. almgr_worker

   3. almgr_registrar

   4. almgr_notification

4. Наличие двух пользователей:

   1. С ролью as_admin для использования в процессе установки для применения миграций

   2. C ограниченной ролью as_TUZ для использования в процессе работы с БД из приложения

5. На pgbouncer настроено подключение клиентов с использованием TLS в режиме verify-ca или verify-full

Apache Kafka#

Для работы компонентов сервиса требуется георезервированный кластер Apache Kafka (выделенный на слой core Platform V Monitor) со следующими пререквизитами:

1. Минимальные требования к аппаратным ресурсам (CPU/MEM/HDD):

   • 4/8/200 на каждую из 3 реплик (+ 3 zookeeper) в тестовых средах

   • 8/16/400 на каждую из 6 реплик (+ 5 zookeeper, георезервированная схема) в промышленных средах

2. Подключение с использованием TLS и авторизацией (ACL) по сертификатам

3. Наличие сертификата, который будет использоваться для создания topic

   1. Наличие следующих credentials (имена могут быть изменены в environment.json в common репозитории в блоке credentials) с типом Secret File, содержащих файлы в формате pem

      1. gateway_client_cer - клиентский сертификат с цепочкой

      2. gateway_client_key - клиентский приватный ключ в незашифрованном виде

      3. gateway_client_keystore - цепочка доверенных сертификатов (при наличии в файле нескольких цепочек будет применена только первая)

   2. На кластере Kafka должны быть созданы следующие ACL

      Resource type	Resource name	Principal	Host	Operation	Permission type
      TOPIC	*	DN сертификата	*	CREATE	ALLOW
      TOPIC	*	DN сертификата	*	ALTER	ALLOW
      TOPIC	*	DN сертификата	*	DESCRIBE	ALLOW
      TOPIC	*	DN сертификата	*	DESCRIBE_CONFIGS	ALLOW
      CLUSTER	kafka-cluster	DN сертификата	*	ALTER	ALLOW

      В некоторых случаях отсутствует возможность получения прав на CLUSTER (последняя строка выше). В таком случае необходимо отключить создание ACL при создании topic (см. ниже в «Конфигурация conf/inventory/inventory») и ручное назначение прав для клиентского сертификата, который будет использоваться приложением:

      Resource type	Resource name	Principal	Host	Operation	Permission type
      GROUP	*	DN сертификата	*	READ	ALLOW
      TOPIC	almgr.*	DN сертификата	*	READ	ALLOW
      TOPIC	almgr.*	DN сертификата	*	DESCRIBE	ALLOW
      TOPIC	almgr.*	DN сертификата	*	WRITE	ALLOW

4. Настроено расширение для инструмента развертывания для автоматического создания topic:

   1. Создать git-репозиторий в системе контроля версий

   2. Архив с исходный кодом расширения и инструкцией по настройке извлечь из дистрибутива по пути package/bh/installer/alert-manager-pipeline.zip

   3. Загрузить расширение и настроить инструмент развертывания в соответствии с инструкцией из файла README.MD в корне распакованного архива

5. Необходимо настроить параметры replica.fetch.max.bytes и message.max.bytes на стороне брокеров в значение, большее или равное значению в параметре almgr.kafka.topic.all.max-message-bytes

TLS Сертификаты#

Для работы компонентов сервиса требуется наличие по следующим путям (могут быть настроены при необходимости) в common репозитории следующих сертификатов:

1. ansible/files/ssl/ca.pem - цепочка корневых сертификатов доверенного центра в формате .pem;

2. ansible/files/ssl/keystore.jks - набор ключей и сертификатов Alert Manager;

   1. Клиентские ключ и сертификат, подписанный доверенным центром;

   2. Серверные ключ и сертификат, подписанный доверенным центром;

3. ansible/files/ott/ott_service_truststore.p12 - набор доверенных сертификатов OTT;

4. ansible/files/ott/almgr.p12 - клиентские ключ и сертификат OTT для соответствующего module.id.

Интеграции с сервисами Platform V Monitor и внешними системами#

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

2. Наличие доменной ТУЗ (Технической Учетной Записи) с доступом в каталог пользователей LDAP (Active Directory)

3. Наличие ТУЗ на почтовом сервере с возможностью отправки электронной почты

Установка#

Конфигурация параметров среды#

Конфигурация subsystems.json#

"ALMGR": {
  "fpi_name": "almgr",
  "fpType": "bts",
  "groupId": "xxx_PROD.CI90000314_alrt",
  "artifactId": "ALRT",
  "versionFilter": "D-*"
}

Конфигурация secret.yml и _passwords.conf#

В дистрибутиве по пути conf/config/secrets лежат шаблоны для файлов secret.yml и _passwords.conf с комментариями

Конфигурация параметров компонента#

• При использовании инструмента ручной установки Platform V Monitor (OPM) необходимо шаблоны файлов конфигурации из дистрибутива по пути package/conf поместить в директорию инструмента по пути ansible/config/alrt/VERSION/fp_repo/R1/conf/

• При использовании Platform V DevOps Tools (DOT) необходимо запустить шаг установки MIGRATION_FP_CONF, который автоматически смигрирует конфигурационные файлы в репозиторий настроек компонента

Конфигурация conf/custom_property.conf.yml#

В опции almgr.pipe.jdbc.url необходимо указать JDBC url, который будет использоваться для подключения к БД для выполнения миграций

Конфигурация conf/inventory/inventory#

1. В секции [kafka:vars] необходимо заполнить следующие переменные

   1. listener_port - порт для подключения с TLS к брокерам Kafka

   2. mtls_dn - DN клиентского сертификата Alert Manager, для которого будут созданы ACL. Или acl_mode=false для отключения автоматического создания ACL

2. В секции [kafka] необходимо перечислить список хостов брокеров

Основные настройки в конфигурационных файлах компонента#

Во всех файлах настройки с именами almgr.ose.* применимы для всех поддерживаемых сред контейнеризации.

almgr.all.conf#

Значение по умолчанию для настройки almgr.all.spec.template.spec.securityContext.runAsUser установлено для работы в среде контейнеризации Kubernetes. При исполнении в OpenShift необходимо изменить значение параметра на пустое.

almgr.certs.all.conf#

almgr.logger.all.conf#

almgr.certs.all.conf#

almgr-notification.conf#

almgr.istio.all.conf#

При использовании георезервированной схемы должен быть указан shared Route в параметре almgr.ose.istio.ingress.geo.route.spec.host, а на балансировщике для него настроен health-check по пути https://ROUTE-FQDN/healthz

Настройки по умолчанию в файле almgr.istio.all.conf установлены для работы в среде контейнеризации Kubernetes. При исполнении в OpenShift необходимо изменить значения следующих параметров:

almgr.ose.istio.common.dns-resolver = dns-default.openshift-dns.svc.cluster.local
almgr.ose.istio.common.ott.envoy-filter.transport-api-version =
almgr.ose.istio.egress.deployment.spec.template.spec.containers.istio-proxy.env.jwt-policy = first-party-jwt

Установка сервиса#

После выполнения всех пререквизитов и настройки конфигурационных файлов можно запускать установку сервиса в ручном режиме или автоматизированном (опционально) с использованием Platform V DevOps Tools (DOT).

Ручная установка#

Для ручной установки необходимо:

1. Запустить вручную точку расширения для создания topic Kafka в соответствии с ее инструкцией

2. Настроить инструмент установки Platform V Monitor в соответствии с его инструкцией, а затем выполнить в консоли следующие команды:

   cd ansible; 
   ./deploy-<id_дистрибутива>.sh
   

Установка с использованием DevOps Tools#

Для автоматизированной установки с использованием Platform V DevOps Tools необходимо запустить установку со следующими шагами (шаги с названиями OPENSHIFT_* применимы для всех поддерживаемых сред контейнеризации):

• DB_UPDATE

• ALMGR_KAFKA

• OPENSHIFT_INGRESS_EGRESS_DEPLOY

• OPENSHIFT_DEPLOY

Подключение UI в Indicator#

Все последующие действия выполняются через пользовательский интерфейс Platform V Monitor Indicator (INDA) под пользователем, имеющим доступ к настройкам Indicator. После выполнения данных действий в боковом меню появятся пункты для Alert Manager и Notification Manager

Активация плагинов#

1. В меню Configuration -> Plugins находим плагины «Alert Manager» и «Notification Manager»

2. Заходим в каждый из них и включаем их кнопкой «Enable»

Создание Datasources#

1. В меню Configuration -> Data Sources создаем два подключения «Datasource Proxy ALMGR» и «Datasource Proxy Notification ALMGR» через кнопку «Add data source»

2. Заполняем поля следующим образом:

   1. В «URL» указываем адрес в зависимости от настраиваемого источника: http://SHARED_ROUTE_FQDN/alerting/api/v1/ для «ALMGR» и http://SHARED_ROUTE_FQDN/notification/api/v1/ для «Notification ALMGR»

      В качестве SHARED_ROUTE_FQDN указывается адрес георезервированного Route (alrt-route-ingress-geo) в namespace Alert Manager в среде контейнеризации. При типовой конфигурации имеет вид almgr-env.env-apps.ocp-geo.domain.xxxx.ru (например, almgr-stable.dev-apps.ocp-geo.sssss.xxxx.ru). В качестве протокола указывается http, т.к. это необходимо для маршрутизации запросов через Egress в namespace Indicator

   2. «Forward OAuth Identity» - включено

   3. На тестовых средах может потребоваться включение «Skip TLS Verify»

3. После нажатия «Save&Test» проверка подключения к источнику должна пройти успешно

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

Обновление#

Обновление 4.0.0 -> 4.1.0#

1. Из-за изменений в инструментах установки в файл conf/inventory/inventory необходимо добавить следующий блок:

[local]
localhost ansible_connection=local

[hosts:children]
local

2. Необходимо выпустить API ключ для Abyss (см. «Интеграции с сервисами Platform V Monitor и внешними системами») и внести его в файл _passwords.conf

3. После обновления конфигурационных файлов

   1. Настроить discovery адрес Istio и имя секрета с учетными данными для получения образов

   2. Настроить хост для отправки трассировки в формате Zipkin

   3. При необходимости выполнить настройки в файлах almgr.all.conf и almgr.istio.all.conf

   4. Изменить значение параметра с именем текущего кластера на новое значение по умолчанию

      almgr.geo.clusters.current = ${alrt.k8s.clusters.current}
      

4. Текущая версия осуществляет миграцию пользователей в модуле notification на новый формат. Перед запуском процесса установки рекомендуется сделать резервную копию со схемы модуля в базе данных

5. Текущая версия из-за обновления механизмов георезервирования не поддерживает rolling upgrade. Необходимо остановить реплики всех сервисов в обоих кластерах

6. Запустить установку сервиса со всеми шагами

Обновление 4.1.0 -> 4.2.0#

1. Обновить значение almgr.kafka.topic.all.max-message-bytes

2. Выполнить пункт 5 из раздела Apache Kafka

Удаление#

Для полного удаления сервиса или одного из его георезервированных плеч необходимо удалить из соответствующих namespace в среде контейнерации все манифесты с меткой SUBSYSTEM в значении, равном ключу в файле subsystems.json.

Для удаления всех связанных данных необходимо:

• При использовании выделенных базы данных и Apache Kafka удалить связанные с ними виртуальные машины

• При использовании коммунальных ресурсов:

  1. В базе данных удалить настроенные в пререквизитах схемы и пользователей

  2. На стороне Apache Kafka удалить все topic, имена которых начинаются с almgr.*, а также ACL, созданные в пререквизитах

Проверка работоспособности#

Для проверки работоспособности необходимо убедиться в том, что процесс установки завершился успешно и все реплики сервиса полностью запущены. После чего необходимо зайти в интерфейс Indicator и перейти сначала на вкладку Alert Manager, затем на Notification Manager. В обоих случаях страница должна успешно открыться без каких-либо ошибок.

Для проверки работоспособности механизмов безопасности необходимо:

1. Попробовать обратиться напрямую к API компонента без использования OAuth 2.0 через браузер по адресу http://ROUTE_FQDN/alerting/api/v1/environment. В ответ должен быть получен json с кодом (status) 401 и текстом ошибки (message) «Full authentication is required to access this resource»

2. На любой из страниц пользовательского интерфейса (например, «Правила отклонений») проверить, что в поле «Проект» отображаются только те проекты, которые действительно доступны пользователю, под которым аутентифицированы

3. Выполнить любое действие, приводящее к изменению настроек (например, создать правило отклонений), и проверить наличие в Platform V Audit SE соответствующего события и соответствие значений полей в нем заданным при выполнении действия

4. Для проверки взаимодействия с внешними системами с использованием TLS необходимо проверить логи контейнера istio-proxy в pod alrt-egress-.... Все обращения должны идти на порты с включенным TLS (например, outbound|443||service.external.host). Если запрос идет на хост almgr-egress-tls-sni-proxy.local, то необходимо проверить аналогичным образом логи контейнера sni-proxy (например, service.external.host  (10.53.95.182:443))

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

Откат#

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

В случае возникновения конфликтов с манифестами среды контейнеризации требуется осуществить очистку namespace и повторно запустить установку предыдущей версии дистрибутива.

Часто встречающиеся проблемы и пути их устранения#

1. Не во всех случаях в инструменте установки присутствует глобальная переменная global.multiClusters.currentCluster, что приводит к невозможности развертывания. В такой ситуации возможна ее временная замена на namespace в параметре almgr.geo.clusters.current с внесением соответствующих изменений в параметре almgr.geo.clusters.list.

Чек-лист валидации установки#

Для полноценной установки Alert Manager все этапы работы инструмента установки должны завершиться успешно.