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

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

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

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

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

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

Примечание:

*

• Да — категория ПО обязательна для функционирования сервиса (это означает, что сервис не может выполнять свои основные функции без установки данной категории ПО).

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

**

• Рекомендовано — рекомендованный правообладателем АО «СберТех» продукт.

• Опционально — альтернативный по отношению к рекомендованному правообладателем АО «СберТех» продукт.

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

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

Примечание:

***

• Да — компонент или продукт необходим для функционирования сервиса (это означает, что сервис не может выполнять свои основные функции без установки данного компонента).

• Нет — необязательный для функционирования сервиса компонент или продукт (это означает, что сервис может выполнять свои основные функции без установки данного компонента).

**** Рекомендуется установка программного продукта, правообладателем которого является АО «СберТех», при этом не исключена возможность (допускается правообладателем) использования аналога других производителей. Аналоги, в отношении которых продукт успешно прошел испытания и подтвердил свою работоспособность, указаны в разделе «Системное программное обеспечение».

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

Для установки компонента рекомендуются следующие лимиты и реквесты развертывания File Stotage Gateway:

resources.limits.cpu=1
resources.limits.memory=2000Mi
resources.requests.cpu=1
resources.requests.memory=2000Mi

Количество Pod достаточное для работы: 1

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

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

Для установки компонента FSGW предусмотрена только ручная установка сервиса.

Так же вам может потребоваться ожидание старта ISTIO, в переменные окружения добавить WAIT_ISTIO_START=1

Для ожидания инжекта секрета от Vault Agent в переменные окружения добавить WAIT_FILE_SECRET=<file_path>, file_path - полный путь к файлу

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

Минимально необходимые требования (для тестирования и разработки):

• кafka-topics для отправления задач асинхронной репликации;

• любое хранилище данных, поддерживающее работу по S3 протоколу.

Расширенные требования (ПРОМ):

• TLS сертификаты для Аудита;

• установка компонентов мониторинга (Agent, Sender);

• доступ до Vault KV Engine совместимом хранилище или его аналога.

Сборка docker-образа установку или развертывание на стенд можно осуществить сборочной службой в составе FEX, подробнее в документации на FEX

Установка#

Типовая схемы развертывания#

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

Подготовка конфигурационных файлов FSGW#

Подробное описание параметров и файлов конфигурации можно найти вРуководство прикладного разработчика.

Пример сетевых настроек#

Настройка входящих соединений#

Данным руководством предполагается что у вас уже настроен ingress и service для него.

Объявите Route до service ingress:

kind: Route
apiVersion: route.openshift.io/v1
metadata:
  name: fsgw-route-ingress
spec:
  host: fsgw-ingress-ci02707148-idevgen-synfex.sh1.dev-gen.someDomain.ru
  to:
    kind: Service
    name: fsgw-svc-ingress
    weight: 100
  port:
    targetPort: http-80
  wildcardPolicy: None

kind: Route
apiVersion: route.openshift.io/v1
metadata:
  name: fsgw-route-ingress
spec:
  host: fsgw-mtls-ingress-ci02707148-idevgen-synfex.sh1.dev-gen.someDomain.ru
  to:
    kind: Service
    name: fsgw-svc-ingress
    weight: 100
  port:
    targetPort: https-443
  tls:
    termination: passthrough
  wildcardPolicy: None

Создайте Gateway:

apiVersion: networking.istio.io/v1beta1
kind: Gateway
metadata:
  name: fsgw-gw-ingress
spec:
  selector:
    istio: fsgw-ingress
  servers:
    # в случае входящего mTls траффика так же необходимы сертификаты
    - hosts:
        - >-
          fsgw-mtls-ingress-ci00477970-idevgen-synapse-file-integration.sh4.dev-gen.someDomain.ru
      port:
        name: tls-443
        number: 443
        protocol: HTTPS
      tls:
        caCertificates: /etc/istio/ingressgateway-ca-certs/ca-chain.cert.pem
        mode: MUTUAL
        privateKey: /etc/istio/ingressgateway-certs/tls.key
        serverCertificate: /etc/istio/ingressgateway-certs/tls.crt
    # Прямое подключение без обертывания в в mTLS/TLS
    - hosts:
        - >-
          fsgw-ingress-ci00477970-idevgen-synapse-file-integration.sh4.dev-gen.someDomain.ru #Соответствует FQDN хоста
      port:
        name: http-8080
        number: 8080
        protocol: HTTP

Объявите service приложения:

kind: Service
apiVersion: v1
metadata:
  name: fsgw-svc-file-storage-gateway
  labels:
    app: fsgw-file-storage-gateway
    name: fsgw-file-storage-gateway
spec:
  ports:
    - name: http-8080
      protocol: TCP
      port: 8080
      targetPort: 8080
  selector:
    app: fsgw-file-storage-gateway
  type: ClusterIP
  sessionAffinity: None

Перенаправьте трафик с ingress на приложение:

apiVersion: networking.istio.io/v1beta1
kind: VirtualService
metadata:
  name: fsgw-vs-ingress
  namespace: ci02707148-idevgen-synfex
spec:
  exportTo:
    - .
  gateways:
    - fsgw-gw-ingress
  hosts:
    - fsgw-mtls-ingress-ci02707148-idevgen-synfex.sh1.dev-gen.someDomain.ru
    - fsgw-ingress-ci02707148-idevgen-synfex.sh1.dev-gen.someDomain.ru
  http:
    - route:
        - destination:
            host: fsgw-svc-file-storage-gateway-unver
            port:
              number: 8080

Настройка исходящих соединений#

Предполагается, что у вас уже настроен egress и service для него.

Настройте gateway:

apiVersion: networking.istio.io/v1beta1
kind: Gateway
metadata:
  name: fsgw-gw-egress
spec:
  selector:
    istio: fsgw-egress
  servers:
    - hosts:
        # Тут перечисляем хосты на которые нам необходимо будет ходить
        - nun-edz.someDomain.ru
        - bennu-edz.someDomain.ru
        - str-vat-was2027.someDomain.ru
      port:
        # Порт на egress для маршрутизации траффика к вышеперечисленным хостам
        name: http-7070
        number: 7070
        protocol: HTTP

Объявите ServiceEntry до нужных узлов:

apiVersion: networking.istio.io/v1beta1
kind: ServiceEntry
metadata:
  name: fsgw-se-ceph-egress
spec:
  exportTo:
    - .
  hosts:
    - nun-edz.someDomain.ru
    - bennu-edz.someDomain.ru
  location: MESH_EXTERNAL
  ports:
    - name: http-ceph-7070
      number: 7070
      protocol: HTTP
    - name: tls-ceph-443
      number: 443
      protocol: TLS
  resolution: DNS

apiVersion: networking.istio.io/v1beta1
kind: ServiceEntry
metadata:
  name: fsgw-se-mcuks-egress
spec:
  exportTo:
    - .
  hosts:
    - str-vat-was2027.someDomain.ru
  location: MESH_EXTERNAL
  ports:
    - name: http-mcuks-7070
      number: 7070
      protocol: HTTP
    - name: tls-mcuks-9443
      number: 9443
      protocol: TLS
  resolution: DNS

Если необходим TLS до ресурсов, к которым приложение будет подключаться, настройте DestinationRule:

apiVersion: networking.istio.io/v1beta1
kind: DestinationRule
metadata:
  name: fsgw-dsr-ceph-egress
spec:
  exportTo:
    - .
  host: nun-edz.someDomain.ru
  trafficPolicy:
    loadBalancer:
      simple: ROUND_ROBIN
    portLevelSettings:
      - port:
          number: 443
        tls:
          mode: SIMPLE

apiVersion: networking.istio.io/v1beta1
kind: DestinationRule
metadata:
  name: fsgw-dsr-mcuks-egress
spec:
  exportTo:
    - .
  host: str-vat-was2027.someDomain.ru
  trafficPolicy:
    loadBalancer:
      simple: ROUND_ROBIN
    portLevelSettings:
      - port:
          number: 9443
        tls:
          caCertificates: /etc/istio/egressgateway-ca-certs/mcuks.pem
          clientCertificate: /etc/istio/egressgateway-certs/mcuks.crt
          mode: MUTUAL
          privateKey: /etc/istio/egressgateway-certs/mcuks.key
          sni: str-vat-was2027.someDomain.ru

Перенаправьте трафик из приложения на egress и с egress на целевой хост:

apiVersion: networking.istio.io/v1beta1
kind: VirtualService
metadata:
  name: fsgw-vs-ceph-egress
spec:
  exportTo:
    - .
  gateways:
    - fsgw-gw-egress
    - mesh
  hosts:
    - nun-edz.someDomain.ru
  http:
    - match:
        - gateways:
            - mesh
          port: 7070
      route:
        - destination:
            host: fsgw-svc-egress
            port:
              number: 7070
          weight: 100
    - match:
        - gateways:
            - fsgw-gw-egress
          port: 7070
      route:
        - destination:
            host: nun-edz.someDomain.ru
            port:
              number: 443
          weight: 100

apiVersion: networking.istio.io/v1beta1
kind: VirtualService
metadata:
  name: fsgw-vs-ceph2-egress
spec:
  exportTo:
    - .
  gateways:
    - fsgw-gw-egress
    - mesh
  hosts:
    - bennu-edz.someDomain.ru
  http:
    - match:
        - gateways:
            - mesh
          port: 7070
      route:
        - destination:
            host: fsgw-svc-egress
            port:
              number: 7070
          weight: 100
    - match:
        - gateways:
            - fsgw-gw-egress
          port: 7070
      route:
        - destination:
            host: bennu-edz.someDomain.ru
            port:
              number: 443
          weight: 100

apiVersion: networking.istio.io/v1beta1
kind: VirtualService
metadata:
  name: fsgw-vs-mcuks-egress
spec:
  exportTo:
    - .
  gateways:
    - fsgw-gw-egress
    - mesh
  hosts:
    - str-vat-was2027.someDomain.ru
  http:
    - match:
        - gateways:
            - mesh
          port: 7070
      route:
        - destination:
            host: fsgw-svc-egress
            port:
              number: 7070
          weight: 100
    - match:
        - gateways:
            - fsgw-gw-egress
          port: 7070
      route:
        - destination:
            host: str-vat-was2027.someDomain.ru
            port:
              number: 9443
          weight: 100

Опционально: при интеграции с Vault KV совместимое хранилище необходимо открыть сетевой доступ до Vault KV совместимое хранилище.

В Gateway добавить:

- hosts:
    - secret-storage-url.someDomain # URL до Vault KV совместимое хранилище 
    port:
      name: tls-8550
      number: 8550
      protocol: TLS
    tls:
      mode: PASSTHROUGH

Объявить ServiceEntry

apiVersion: networking.istio.io/v1beta1
kind: ServiceEntry
metadata:
  name: egress-secman-se
spec:
  exportTo:
    - .
  hosts:
    - secret-storage-url.someDomain # URL до Vault KV совместимое хранилище 
  location: MESH_EXTERNAL
  ports:
    - name: tls-8443 #порт Vault KV совместимое хранилище 
      number: 8443
      protocol: TLS
    - name: tls-8550
      number: 8550
      protocol: TLS
  resolution: DNS

Объявить VirtualService

apiVersion: networking.istio.io/v1beta1
kind: VirtualService
metadata:
  name: egress-secman-vs
spec:
  exportTo:
    - .
  gateways:
    - fsgw-gw-egress-dev-unver
    - mesh
  hosts:
    - secret-storage-url.someDomain # URL до Vault KV совместимое хранилище 
  tls:
    - match:
        - gateways:
            - mesh
          port: 8443 #порт Vault KV совместимое хранилище 
          sniHosts:
            - secret-storage-url.someDomain # URL до Vault KV совместимое хранилище 
      route:
        - destination:
            host: fsgw-svc-egress-dev-unver
            port:
              number: 8550
    - match:
        - gateways:
            - fsgw-gw-egress-dev-unver
          port: 8550
          sniHosts:
            - secret-storage-url.someDomain # URL до Vault KV совместимое хранилище 
      route:
        - destination:
            host: secret-storage-url.someDomain # URL до Vault KV совместимое хранилище 
            port:
              number: 8443 #порт Vault KV совместимое хранилище 

Открыть порт на Egress добавив в Service секцию

- name: tls-8550
  port: 8550
  protocol: TCP
  targetPort: 8550

А также необходимо сформировать application.yaml с параметрами приложения, подробнее в Руководство прикладного разработчика

Не забудьте проверить установку согласно Чек-лист валидации установки и Проверка работоспособности

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

Настройка интеграции со смежными сервисами осуществляется в процессе конфигурации параметров для конкретного внешнего сервиса в определенных ConfigMaps:

• настройка интеграции с компонентом Аудит продукта Platform V Audit SE;

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

  настройка производиться в конфигурационном файле application.properties/application.yml параметрами начинающимися с префикса audit. подробнее в Руководство прикладного разработчика

• настройка интеграции с компонентом Объединенный мониторинг Unimon продукта Platform V Monitor;

  подробное описание по настройке объединенного мониторинга Unimon описано в документации на компонент MONA программного продукта OPM - Platform V Monitor.

• настройка интеграции с компонентом Журналирование продукта Platform V Monitor;

  настройка осуществляется путем изменения конфигурации application.yaml, подробнее в Руководство прикладного разработчика

• настройка интеграции с компонентом Управление секретами и сертификатами продукта Vault KV Engine совместимом хранилище;

  настройка осуществляется путем изменения конфигурации application.yaml, подробнее в Руководство прикладного разработчика

Обновление#

Обновление осуществляется по модели "RollingUpdate".

Исходные данные: сервис FSGW запущен в pod, осуществляется обмен файлами.

1. Прекратите использование FSGW, дождавшись последней отправки/приема файлов.

2. Измените ссылку на docker-образ File Storage Gateway в deployment вашего проекта в пространстве Kubernetes.

3. Проверьте, что ConfigMaps и Secrets соответствуют текущим требованиям к конфигурации, так как для корректной работы новых версий образа может потребоваться обновленная конфигурация компонента (уточняйте актуальное состояние конфигурации для каждой новой версии образа). Подробнее о application.yaml описано в документе Руководство прикладного разработчика.

4. Увеличьте номер ревизии в аннотации deployment.kubernetes.io/revision в deployment для возможности отката на предыдущую версию деплоймента.

Не забудьте проверить установку согласно Чек-лист валидации установки и Проверка работоспособности

kind: Deployment
apiVersion: apps/v1
metadata:
  name: <имя вашего проекта>
  namespace: <имя вашего namespace>
  annotations:
    deployment.kubernetes.io/revision: "2" # <- увеличиваем номер ревизии на единицу
spec:
  selector:
    matchLabels:
      name: <имя вашего проекта>
  template:
    metadata:
      labels:
        app: <имя вашего проекта>
        name: <имя вашего проекта>
      annotations:
        sidecar.istio.io/inject: "true"
        sidecar.istio.io/proxyLimitsCPU: 300m
        sidecar.istio.io/proxyLimitsMemory: 512Mi
        sidecar.istio.io/proxyRequestsCPU: 200m
        sidecar.istio.io/proxyRequestsMemory: 300Mi
    spec:
      # ...
      containers:
        # ...
        - name: FSGW
          env:
            - name: TZ
              value: Europe/Moscow # добавление часового пояса для отображаемого времени в логах
          image: "<образ File Storage Gateway sidecar>" # <- обновляем ссылку на докер образ Сервиса файловой передачи в registry
          resources:
          # ...

Удаление#

Для удаления компонента необходимо:

• прекратить взаимодействие с компонентом, дождаться завершения всех операций, остановить работу компонента;

• убрать из deployment упоминание контейнера FSGW и применить deployment;

• удалить все артефакты Kubernetes относящиеся к компоненту FSGW.

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

• после запуска приложения зайдите в консоль Kubernetes и убедитесь в том, что успешно отвечают liveness- и readiness-пробы;

• проверьте логи запущенного pod и убедитесь, что в логах нет ошибок при запуске контейнера сервиса файловой интеграции.

Пример:

livenessProbe:
  httpGet:
    path: /actuator/health
    port: 8080
    scheme: HTTP
  initialDelaySeconds: 60
  timeoutSeconds: 5

• для проверки работоспособности аудита проанализировать логи компонентов на наличие ошибок связанные с аудитом. Перейти в Platform V Audit (компонент AUDT) проверить наличие записей событий отправленных туда компонентом.

• для проверки работоспособности мониторинга перейти в Platform V Monitor и убедиться в наличии метрик мониторинга.

• для проверки удаленного журналирования перейти в Platform V Monitor (LOGA) и убедиться в наличии записей журнала.

Так как компонент File Storage Gateway не зависит от внешних сервисов, баз данных и других контейнеров, то настраивать отдельную проверку readiness-пробу для него не требуется.

Пример:

readinessProbe:
  httpGet:
    path: /actuator/health
    port: 8080
    scheme: HTTP
  initialDelaySeconds: 60
  timeoutSeconds: 5

Откат#

Откатить компонент File Storage Gateway на предыдущую версию deployment можно с помощью утилиты kubectl:

kubectl rollout undo deployment/<имя вашего проекта>

При этом связанные сущности, например ConfigMap необходимо вручную привести в соответствие версии File Storage Gateway

Для возможности реализации отката необходимо увеличивать номер ревизии в deployment с обновлением версии File Storage Gateway.

kind: Deployment
apiVersion: apps/v1
metadata:
  name: <имя вашего проекта>
  namespace: <имя вашего namespace>
  annotations:
    deployment.kubernetes.io/revision: "2" # <- номер ревизии

Максимальное число откатов по умолчанию ограничено десятью последними развертываниями. Данное значение можно изменить, указав в поле revisionHistoryLimit свое значение.

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

• проблемы с S3-совместимым хранилищем:

  • решение: Убедиться что для пользователя (access-key которого указан в конфигурации) разрешены операции чтения и записи в bucket, использующемся в интеграционном взаимодействии. Убедиться, что Bucket не переполнен и передаваемые файлы занимают не больше, чем свободное место в bucket.

• не работают пробы на readiness и liveness.

  • решение: Проверить, что данный функционал активирован в конфигурационном файле:

    management:
      health:
        livenessState:
          enabled: true
        readinessState:
          enabled: true
      endpoint:
        health:
          probes:
            enabled: true
    

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

1. Правильно сконфигурированы ConfigMaps config map с файлом application.yaml, где описываются основные настройки сервиса:

   1. Верны указаны все порты.

   2. Верно заполнен адрес S3-совместимого хранилища, а также указан действующий ключ доступа (ceph.access-key).

   3. При использовании Platform V Audit верно заполнены все необходимые для этого поля.

2. Данные в Secrets корректно заполнены и имеют актуальное состояние.

3. Под отвечает liveness- и readiness-пробам.

4. В логах работы компонента файловых интеграций нет ошибок.