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

В руководстве приведены инструкции по установке компонента Kafka Gateway (KFGT) продукта Monosolution Platform V Synapse Enterprise Integration (SEI).

Термины и определения#

Важно!
Программный компонент Kafka Gateway продукта Platform V Synapse Enterprise Integration поставляется в виде собранного Docker-образа, размещаемого в целевом Docker-репозитории, и предназначается для использования в составе прикладных интеграционных решений, разрабатываемых продуктовыми командами.

Для этого команды, реализующие прикладную интеграцию, выпускают дистрибутив, содержащий набор конфигурационных артефактов Kubernetes или Red Hat OpenShift, обеспечивающих развертывание и настройку отдельного экземпляра Kafka Gateway под требования этой интеграции.

Самостоятельно, вне рамок прикладных интеграционных решений, Kafka Gateway не эксплуатируется.

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

Настройки безопасности окружения и перечень платформенных (дополнительных внешних) продуктов, используемых для установки, настройки и контроля в конечной информационной системе (далее — ИС), выбираются клиентом при разработке конечной ИС, исходя из характера обрабатываемой в ней информации и иных требований информационной безопасности (далее — ИБ), предъявляемых к ней.

Системное программное обеспечение#

Ниже представлены категории системного программного обеспечения (далее — ПО), которые обязательны для установки, настройки, контроля и функционирования компонента. В каждой категории перечислены все поддерживаемые продукты сторонних правообладателей. Отдельно обозначены варианты, которые рекомендует АО «СберТех» (маркировка «Рекомендовано» в столбце «Продукт, функциональная совместимость с которым подтверждена»). Клиенту необходимо выбрать один из продуктов в каждой категории, исходя из условий использования конечной ИС.

Платформенные зависимости#

Для настройки, контроля и функционирования компонента реализована интеграция с программными продуктами, правообладателем которых является АО «СберТех»:

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

Аппаратные требования#

В рамках требований указан минимальный размер. Целевой размер определяется по результатам НТ отдельно под каждый интеграционный сценарий. Для установки компонента требуется следующая конфигурация аппаратного обеспечения:

Состав дистрибутива#

Выбор способа установки#

Поддерживается ручная установка или установка с помощью компоненты Service Mesh DevOps Lib (SMDL) продукта Platform V Synapse Service Mesh.

Подготовка окружения#

Для установки Kafka Gateway в составе прикладного дистрибутива должно быть выполнено следующее:

1. Развернут и настроен кластер DropApp 1.2+, Kubernetes 1.17+ или Red Hat OpenShift 4.5.13+ в соответствии с требованиями, предъявляемыми к Платформе.

2. В кластере создан проект (namespace), в котором будет разворачиваться шлюз.

3. В проекте создана учетная запись с правами на загрузку артефактов.

4. Docker-образ шлюза размещен в целевом Docker-репозитории по ссылке, указанной в конфигурационном артефакте Deployment.

5. В проект добавлен Secret для загрузки Docker-образов из целевого Docker-репозитория.

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

7. Брокеры Kafka настроены и готовы к работе, есть доступ к ним со стороны кластера Kubernetes/DropApp или Red Hat OpenShift.

8. Созданы целевые topic(s) сообщений, необходимый доступ к ним предоставлен.

9. В проекте имеются свободные ресурсы по лимитам и Requestам не менее, чем зарезервировано в конфигурационных артефактах.

10. При установке с использованием консоли, на рабочем месте должен быть установлен клиент Kubernetes/DropApp или Red Hat OpenShift.

11. Если планируется использование сервиса OTT для обеспечения целостности данных, сервис OTT должен быть доступен из проекта, в который производится установка.

12. Сетевые соединения с брокерами Kafka должны быть защищены протоколом TLS версии не ниже 1.2, поэтому должны быть выпущены сертификаты для установки TLS подключения.

    При опциональном использовании совместно со Шлюзом Kafka Сайдкара компонента Сервисный прокси (входящего в состав продукта «Platform V Synapse Service Mesh») минимальные ресурсы, необходимые для запуска, следует уточнить в соответствующей документации используемого компонента.

    Перечень программных продуктов, используемых при установке:

Установка#

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

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

В дистрибутиве передаются примеры конфигураций Kubernetes/DropApp/Red Hat OpenShift, на основе которых необходимо описать целевую конфигурацию для промышленных стендов.

Пререквизиты#

1. Базовый образ для сборки docker image загружен в docker registry.

2. Установлен клиент kubectl.

3. Установлен docker.

Публикация базового образа#

1. Загрузить образ из файла командой docker load

2. Поставить тег полученному образу и залить в docker registry (командами docker tag, docker push)

Сборка образа из owned и party частей#

1. Скачать party и owned дистрибутивы.

2. Разархивировать party дистрибутив.

3. Разархивировать owned дистрибутив и разархивировать архив в нем.

4. Скопировать содержимое party дистрибутива в разархивированную owned часть по пути package/bh/BOOT-INF/lib.

5. Перейти в терминале в директорию package/ дистрибутива owned.

6. Скопировать в данную директорию dockerfile из package/conf/k8s/base/asgt_kafka/Dockerfile и отредактировать его, указав путь до базового образа:

cp conf/k8s/base/asgt_kafka/Dockerfile .

7. Выполнить сборку докер образа, предварительно авторизоваться в docker regestry (командой docker login):

docker build .

8. Поставить тег полученному образу и залить в docker registry (командами docker tag, docker push)

Развертывание#

1. Отредактировать deployment dc.yaml по пути package/conf/k8s/base/asgt_kafka, а также заполнить необходимые переменные:

   kfgt.replicas - количество реплик Pod (например 1)
   
   kfgt.ose.deployment.metadata.annotations.sidecar.istio.io.inject - включение/отключение sidecar service mesh (например true/false)
    
   kfgt.ose.deployment.metadata.annotations.sidecar.istio.io.proxyCPU - cpu request для контейнера sidecar service mesh (например 200m)
   kfgt.ose.deployment.metadata.annotations.sidecar.istio.io.proxyCPULimit - cpu limit для контейнера sidecar service mesh (например 200m)
   kfgt.ose.deployment.metadata.annotations.sidecar.istio.io.proxyMemory - memory request для контейнера sidecar service mesh (например 500Mi)
   kfgt.ose.deployment.metadata.annotations.sidecar.istio.io.proxyMemoryLimit - memory limit для контейнера sidecar service mesh (например 500Mi)
   
   kfgt.ose.deployment.spec.template.spec.priorityClassName - Имя priorityClassName при использовании приоритетов развертывания Pod (null, если не используется)
   
   kfgt.ose.deployment.spec.template.spec.containers.kfgt.resources.limits.cpu - cpu limit для контейнера приложения (например 200m)
   kfgt.ose.deployment.spec.template.spec.containers.kfgt.resources.limits.memory - memory limit для контейнера приложения (например 500Mi)
    
   kfgt.ose.deployment.spec.template.spec.containers.kfgt.resources.requests.cpu - cpu request для контейнера приложения (например 200m)
   kfgt.ose.deployment.spec.template.spec.containers.kfgt.resources.requests.memory - memory request для контейнера приложения (например 500Mi)
   
   kfgt.ose.deployment.spec.template.spec.containers.kfgt.readinessProbe.initialDelaySeconds - время инициализации readiness пробы в секундах (например 45)
   kfgt.ose.deployment.spec.template.spec.containers.kfgt.readinessProbe.timeoutSeconds - таймаут в секундах, за который приложение должно ответить по запросу readiness пробы (например 1)
   kfgt.ose.deployment.spec.template.spec.containers.kfgt.readinessProbe.periodSeconds - частота запросов readiness пробы в секундах (например 1)
   kfgt.ose.deployment.spec.template.spec.containers.kfgt.readinessProbe.successThreshold - количество успешных запросов необходимых для успешного прохождения readiness пробы (например 1)
   kfgt.ose.deployment.spec.template.spec.containers.kfgt.readinessProbe.failureThreshold - количество ошибочных запросов необходимых для провального прохождения readiness пробы (например 3)
   
   kfgt.ose.deployment.spec.template.spec.containers.kfgt.livenessProbe.initialDelaySeconds - время инициализации liveness пробы в секундах (например 45)
   kfgt.ose.deployment.spec.template.spec.containers.kfgt.livenessProbe.timeoutSeconds - таймаут в секундах, за который приложение должно ответить по запросу liveness пробы (например 1)
   kfgt.ose.deployment.spec.template.spec.containers.kfgt.livenessProbe.periodSeconds - частота запросов liveness пробы в секундах (например 1)
   kfgt.ose.deployment.spec.template.spec.containers.kfgt.livenessProbe.successThreshold - количество успешных запросов необходимых для успешного прохождения liveness пробы (например 1)
   kfgt.ose.deployment.spec.template.spec.containers.kfgt.livenessProbe.failureThreshold - количество ошибочных запросов необходимых для провального прохождения liveness пробы (например 10)
   
   kfgt.ose.configmap.javaArguments - параметры запуска JVM (например -XX:+UseContainerSupport -XX:MaxRAMPercentage=70)
   
   registry - URL docker registry
   registry_path - путь до образа (например /sbt_dev/ci90000017_synapse_dev)
   
   distrib.release.version - версия дистрибутива (например v1)
   

2. Также в файле dc.yaml в поле image указать тег образа, полученный на шаге 8 этапа сборки.

3. Отредактировать configmap-kafka-adapter.yaml по пути package/conf/k8s/base/configmaps/, а также заполнить необходимые переменные:

   kfgt.bootstrap-servers - указываем список серверов кафки, к которым необходимо подключаться (например host1:9092,host2:9092)
   kfgt.producer.topic - указываем topic(s), в который необходимо записывать сообщения по умолчанию (например producer_topic)
   kfgt.consumer.topic - указываем topic(s), из которого необходимо читать сообщения (например consumer_topic1)
   kfgt.consumer.group-id - group id для consumer group, с которым Kafka Gateway будет читать сообщения из topic(s) (например kfgt)
   

4. Установить конфигурацию, предварительно авторизовавшись в проекте:

   kubectl apply -f conf/k8s/base/configmaps/configmap-kafka-adapter.yaml
   kubectl apply -f conf/k8s/base/asgt_kafka/dc.yaml
   kubectl apply -f conf/k8s/base/asgt_kafka/svc.yaml
   kubectl apply -f conf/k8s/base/empty-service/svc.yaml
   

Установка с помощью SynapseInstaller компонента Service Mesh DevOps Lib (SMDL) Platform V Synapse Service Mesh#

Подготовка конфигурации Helm#

Необходимо настроить файл values.yaml в соответствие с описанием конфигурации Kafka Gateway (Руководство прикладного разработчика).

Описание настроек values.yaml:

nameOverride: <Имя компонента>
fullnameOverride: <Имя компонента, включая версию>

grpcPort: <Номер порта GRPC-сервера>
restPort: <Номер порта REST-сервера>                                  

dc:                                             
  maxUnavailable: <Максимальное количество Pod, которые могут быть недоступны в процессе обновления>                                                                                             
  maxSurge: <Максимальное количество Pod, которое может быть создано сверх желаемого количества Pods (Pods) в процессе развертывания>
  replicaCount: <Количество реплик приложения>
  priorityClassName: <Имя конфигурации приоритета, с которым необходимо развернуть приложение>

  prometheus:
    enabled: <Управление метриками prometheus>
    port: <Номер порта для опроса prometheus>
    path: <Путь, по которому требуется собирать метрики prometheus>

  istio:
    enabled: <Управление sidecar istio>
    proxyCPU: <Request CPU для контейнера sidecar istio>
    proxyCPULimit: <Limit CPU для контейнера sidecar istio>
    proxyMemory: <Request RAM для контейнера sidecar istio>
    proxyMemoryLimit: <Limit RAM для контейнера sidecar istio>

  vault:
    enabled: <Управление sidecar vault>
    role: <Роль для подключения к vault>
    volumePath: <Путь для монтирования сертификатов из Vault>
    volumePathSSL: <Путь для монтирования конфигурации ssl.yml из Vault>
    withSecret: <Список конфираций для монтируемых файлов>

  image:                                                                                                        
    registry: <Адрес docker registry>                                                                              
    repository: <Путь до docker image>                                                   
    tag: <Тег docker image с sha256>                            
    pullPolicy: Always                                                                                      

  resources: <Request и Limits CPU/RAM для основного контейнера>

  failureThreshold: <Количество неуспешных попыток для livenessProbe>

cm:
  client:
    settings:
      default:
        hostname: <Имя сервиса/адрес для вызова сервиса GRPC по умолчанию>
        port: <Номер порта для вызова сервиса GRPC по умолчанию>
  spring:
    kafka:
      ssl:
        enabled: <Управление наличием TLS>
        keyStoreLocation: <Путь до keyStore>
        trustStoreLocation: <Путь до trustStore>
        protocol: <Версия протокола TLS>
      rest:
        mode: <Управление режимом работы GRPC/REST>
        maxConnections: <Максимальное количество подключений для клиента REST>
        defaultURL: <Адрес по умолчанию для клиента REST>
        failedURL: <Адрес, по которому необходимо отправить сообщение с ошибкой, в случае ошибки проверки подписи>
      producer:
        enabled: <Управление режимом записи в topic(s) Kafka>
        bootstrapServers: <Список брокеров Kafka>
        topic: <topic(s) по умолчанию для записи сообщения>
      consumer:
        enabled: <Управление режимом чтения из topic(s) Kafka>
        transactional: <Управление транзакционным режимом>
        batching: <Управление режимом Batch>
        bootstrapServers: <Список брокеров Kafka>
        topics: <Список topic(s) для чтения>
      properties: <Список Kafka настроек для конфигурации producer и consumer>

audit:
  enabled: <включение интеграции с аудитом>                                                                  
  service:
    host: <адрес сервера аудита>
    metamodel-route: <endpoint для регистрации метамодели аудита>
    event-route: <endpoint для фиксации событий аудита>
  metamodel:
    version: <версия метамодели>
    module-id: <идентификатор модуля>                                                           
    retry:
      max-attempts: <кол-во попыток регистрации метамодели>                                                        
      wait-duration: <время в миллисекундах между попытками регистрации метамодели>                               
  event:
    retry:
      max-attempts: <кол-во попыток фиксации событий аудита>                                                          
      wait-duration: <время в миллисекундах между попытками фиксации>                                                 
  buffer:
    size: <размер буфера событий, которые необходимо отправить в аудит>                                               
  listener:
    pool-size: <кол-во слушателей, которые читают буфер и отправляют события в аудит>                                 
    period: <периодичность в миллисекундах, как часто слушатели должны опрашивать буфер>                              

fluentBit:
  name: <Имя контейнера агента журналирования>
  dc:
    image:
      registry: <Адрес docker registry>                                                                              
      repository: <Путь до docker image>                                                   
      tag: <Тег docker image с sha256>                            
      pullPolicy: <Политика загрузки образа>
    resources: <Request и Limits CPU/RAM для контейнера агента журналирования>
  cm:
    brokers: <Список брокеров Kafka>
    topics: <Имя topic(s)>

Развертывание на стенд#

Запустить сборку Jenkins задачи SynapseInstaller по инструкции из документации на компонент SMDL (раздел SynapseInstaller руководства оператора).

Настройка интеграции#

Ниже описана процедура интеграции с рекомендованным АО «СберТех» продуктами. На усмотрение пользователя может быть настроена интеграция с аналогичным по функциональности продуктом от других производителей .

1. Интеграция с Platform V Corax производится путем конфигурирования параметров ${kfgt.bootstrap-servers}, ${kfgt.producer.topic}, ${kfgt.consumer.topic} в 3 шаге процесса развертывания.

2. Интеграция с Platform V Monitor производится через компонент LOGA.

   Для настройки необходимо добавить в конфигурацию deployment описание дополнительного контейнера LOGA и дополнительных volumes:

            - name: loga-agent
              image: <image>
              resources:
                limits:
                  cpu: 100m
                  memory: 100Mi
                requests:
                  cpu: 100m
                  memory: 100Mi
              securityContext:
                runAsNonRoot: true
                readOnlyRootFilesystem: true
              volumeMounts:
                - name: synapselogs
                  mountPath: /opt/synapse/logs
                - name: loga-agent-config
                  readOnly: true
                  mountPath: /fluent-bit/etc/
              imagePullPolicy: Always
            ...
          volumes:
            - name: synapselogs
              emptyDir: {}
            - name: loga-agent-config
              configMap:
                name: loga-agent-config
                defaultMode: 256
                optional: true
   

   А также подготовить ConfigMap с конфигурацией:

            kind: ConfigMap
            apiVersion: v1
            metadata:
              name: loga-agent-config
            data:
              fluent-bit.conf: |
                [SERVICE]
                    Flush        1
                    Daemon       Off
                    Log_Level    Debug
                    Parsers_File /fluent-bit/etc/parsers.conf
            
                [INPUT]
                    Name   tail
                    Path   /opt/synapse/logs/*.log
                    Tag    fluent
                    Parser custom
                    Buffer_Chunk_Size 400k
                    Buffer_Max_Size 6MB
                    Mem_Buf_Limit 6MB
            
                [OUTPUT]
                    Name  kafka
                    Brokers <host>:<port>
                    Timestamp_Key fluent_time
                    Topics <topic name>
              parsers.conf: |
                [PARSER]
                    Name        custom
                    Format      json
   

   Более подробную информацию по конфигурации можно найти в документации на компонент LOGA (раздел подключение и конфигурирование руководства прикладного разработчика).

3. Для интеграции с компонентом MONA продукта Platform V Monitor необходимо в конфигурацию Service добавить следующие аннотации по пути metadata.annotations:

   metadata:
     annotations:
       prometheus.io.path: /actuator/prometheus        # контроллер, с которого собирать метрики
       prometheus.io.port: '8080'                      # порт, на котором доступен web server
       prometheus.io.scrape: 'true'                    # включание сбора метрик с помощью MONA
   

4. Интеграция с Platform V Synapse Service Mesh производится через sidecar SVPX Сервисный прокси в автоматическом режиме после подключения проекта в контрольной панели Synapse Service Mesh, подробности описаны в документации на компонент SVPX (Раздел подключение и конфигурирование руководства прикладного разработчика).

5. Интеграция с Platform V Secret Management производится через sidecar Platform V Secret Management, подробности описаны в Руководстве по безопасноcти, в разделе Как интегрировать Kafka Gateway с SecMan и настроить TLS подключение к брокерам Kafka.

6. Интеграция с Платформенным сервисом аудита (AUDT) продукта «Platform V Audit SE» описана в Руководстве прикладного разработчика, в разделе Настройка регистрации событий аудита.

Обновление#

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

   kubectl get deployment <deployment-name> > depl.yml
   kubectl get service <service-name> > svc.yml
   kubectl get se <serviceentry-name> > se.yml
   kubectl get configmap <configmap-name> > cm.yml
   kubectl get secret <keystore-secret-name> > keystore.yml
   kubectl get secret <secret-name> > secret.yml
   

2. Удалить все ресурсы Kafka Gateway по инструкции из раздела Удаление.

3. Провести установку по инструкции из раздела Установка.

Если требуется обновление без прекращения работы Kafka Gateway, то необходимо проводить канареечное развертывание (canary deployment), исходя из таблицы:

Удаление#

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

kubectl delete deployment <deployment-name>
kubectl delete service <service-name>
kubectl delete se <serviceentry-name>
kubectl get configmap <configmap-name>
kubectl delete secret <keystore-secret-name>
kubectl delete secret <secret-name>

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

С использованием веб-интерфейса

С использованием консоли

Чек-лист проверки работоспособности интеграций#

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

Откат#

1. Удалить все ресурсы Kafka Gateway по инструкции из раздела Удаление.

2. Провести установку бэкапа по инструкции из раздела Установка.

Откат возможен на любую версию, выпущенную не ранее 2.8.

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

Чтение журналов всех контейнеров Pod помогает найти причину и решение большинства проблем при установке.

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

Для проверки валидности установки проверьте наличие всех установленных компонентов, например:

kubectl get deployment <deployment-name>
kubectl get service <service-name>
kubectl get se <serviceentry-name>
kubectl get configmap <configmap-name>
kubectl get secret <keystore-secret-name>
kubectl get secret <secret-name>

Все компоненты должны присутствовать в проекте и должна отсутствовать ошибка "Error from server (NotFound)".

Проверка внешних интеграций:

Инструкция по проверке работоспособности Kafka Gateway представлена в разделе Проверка работоспособности.