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

В руководстве приведены инструкции по установке компонента DCGN продукта Platform V Print (DCG).

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

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

Сервисы компонента DCGN представляют собой облачное решение, поставляемое для установки в контейнеризованную среду (Kubernetes или OpenShift (опционально)).

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

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

Примечание:

*

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

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

**

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

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

Здесь и далее поддерживаемой системой приложений-контейнеров является Kubernetes (использование OpenShift – опционально), в инструкциях по настройке, в именах переменных и параметрах системы могут встречаться названия систем контейнеризации, которые одинаковы и применимы для обоих сред контейнеризации.

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

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

Примечание:

• Обязательно — компонент или продукт необходим для функционирования компонента DCGN.

• Опционально — необязательный для функционирования компонент или продукт, рекомендуется его установка, но допускается использование аналога других производителей.

Тип зависимости определяется:

• One-Time Password (OTP) / OTT (OTTS) — можно отключить на уровне конфигурационых файлов ingress/egress. Управляется поставкой разных дистрибутивов конфигураций. Критично только для инсталляций с обязательным требованием использования One-Time Password (OTP) / OTT.

• Deploy tools (CDJE) — рекомендуется установка дистрибутива с помощью Deploy Tools, при желании можно использовать другой инструмент развертывания.

• Объединенный мониторинг Unimon (MONA) — устанавливаются при необходимости. Поставляется отдельным дистрибутивом МОNA, установка в namespace выполняется через Deploy Tools.

• Журналирование (LOGA) — допустимо сконфигурировать отправку логов в другую систему журналирования.

• Аудит (AUDT) — DCGN может взаимодействовать с платформенным компонентом Аудит.

• IAM proxy (AUTH), Объединенный сервис авторизации (ОСА) (AUTZ) — обязательны для работы через пользовательский интерфейс.

• Platform V Synapse Service Mesh (SSM) — обязательна к установке указанная версия и сборка, если инсталляция с One-Time Password (OTP) / OTT и для некоммунальной инсталляции.

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

Список минимальных требований к ресурсам КТС приведен ниже. Допустимы два способа развертывания DCGN - в коммунальную и автономную (изолированную) инсталляции.

Коммунальная инсталляция предполагает установку в один namespase продукта (DCGN) совместно с продуктами Платформы.

Автономная инсталляция предполагает установку в один namespase одного продукта (DCGN).

Конфигурация БД для тестовых стендов#

Конфигурация БД для НТ, ПРОМ стендов#

Требуется наличие кластера Patroni (PostgreSQL + pgbouncer + Patroni).

Требование квот кластера (коммунальная инсталляция) для НТ, ПРОМ стендов#

Требование квот кластера (автономная инсталляция)#

Ресурсы, необходимые для сервисов компонента DCGN#

Автономная инсталляция:

Коммунальная инсталляция:

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

Дистрибутив компонента DCGN представляет собой ZIP-архив (как для коммунальной, так и для автономной инсталляций):

Настройки DCGN, в том числе рекомендуемые настройки безопасности окружения, приведены в настоящем документе.

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

Для установки и работы DCGN необходимо провести подготовительные мероприятия, а именно, подготовить КТС. Подготовка КТС подразумевает получение кластера БД и namespase K8s или OSE (опционально). Размер квот соответствует указанному в разделе «Аппаратные требования» настоящего документа.

До развертывания DCGN необходимо выполнить развертывание сервисов и инфраструктурных компонентов Platform V. Наличие платформенных зависимостей приведено выше в разделе «Платформенные зависимости» настоящего документа. Развертывание сервисов и инфраструктурных компонентов Platform V производится в соответствии с документацией на установку соответствующего сервиса или инфраструктурного компонента.

Установка#

Рекомендации по наполнению продукта зависимостями при сборке с помощью Build Tools (Solution Merger Job)#

Образы контейнеров не входят в состав дистрибутива компонента DCGN. Базовые образы и образы sidecar необходимо указывать при сборке продукта используя Solution Merger Job. Перед запуском инструмента дополнения продукта зависимостями в конфигурации необходимо указать, какие базовые образы следует использовать вместо образов, указанных в Dockerfile по умолчанию.

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

Базовый образ

Рекомендуемый стек:

1. Альт 8 СП

2. OpenJDK версии 11:7.6.

3. Пакет для управления шрифтами «fontconfig».

Альтернативный (опциональный) стек:

1. RHEL7.

2. OpenJDK версии 11:7.6.

3. Пакет для управления шрифтами «fontconfig».

Пример из merger.yml

base_image_mapping:        # маппинг базовых docker образов
    - from: .*openjdk11.*
      to: <укажите базовый образ необходимый для инсталляции> # пример nexus_host/repository/base/rhel7openjdk11:7.6-252.1561619826-86

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

В конфигурации развертывания DCGN присутствуют ссылки на образы sidecar контейнеров, Dockerfile которых отсутствует в дистрибутиве продукта (образы технологических сервисов, поставляемых в других платформенных продуктах), поэтому в конфигурации Solution Merger Job следует явно указать какие хеши образов использовать для таких sidecar контейнеров. Необходимо указывать образы sidecar контейнеров соответствующие версиям, указанным в данном руководстве в разделе «Платформенные зависимости».

Пример из merger.yml

image_link_mapping:        # маппинг ссылок на образы (применяется, чтобы указать актуальные ссылки на образы sidecar контейнеров)
  # IGEG (Istio SE)
  ":.+proxyv2@sha256:[0-9a-f]{64}": ": <укажите образ необходимый для инсталляции>" # пример nexus_host/repository/synapse_security/istio/proxyv2@sha256:cdd42336b164955a0550a8ce338b577177dcdd975799af3d0d8a7352f2d20fb9
  # OTTS 4.1.8, если необходима интеграция с One-Time Password (OTP) / OTT
  ":.+ott-client-api@sha256:[0-9a-f]{64}": ": <укажите образ необходимый для инсталляции>" # пример nexus_host/repository/ott-client-api@sha256:764085215941ecb7e90429326113fe63b78b024e8595ac3249c5d88d128574ac
  # LOGA fluent-bit
  ":.+fluent-bit@sha256:[0-9a-f]{64}": ": <укажите образ необходимый для инсталляции>" # пример nexus_host/repository/ulogger/fluent-bit@sha256:04da83ed2af92600f7e0b4055d707c038c6e549ed14dba6372b0a2a50ddae32d

Автоматизированная установка DCGN с использованием Deploy Tools#

Установка DCGN включает в себя следующие этапы:

1. Создание пользователя и схемы БД.

2. Создание namespace в среде контейнеризации.

3. Создание и настройка сертификатов.

4. Настройка параметров.

5. Установка DCGN в контейнеризованную среду (Kubernetes или OpenShift (опционально)).

В разделах ниже приведено более подробное описание по каждому этапу установки.

Создание пользователя и схемы БД#

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

Пример создания пользователя и схемы

create user dcgn_<BLOCK_ID> with encrypted password '<пароль>';
create schema dcgn_<BLOCK_ID>;
grant connect on database postgres to dcgn_<BLOCK_ID>;
grant all on schema dcgn_<BLOCK_ID> to dcgn_<BLOCK_ID>;
alter user dcgn_<BLOCK_ID> VALID UNTIL 'INFINITY';
grant usage on schema dcgn_<BLOCK_ID> to dcgn_<BLOCK_ID>;

create tablespace dcgn_ts_data owner dcgn location '/pgdata/ts/dcgn_ts_data';
create tablespace dcgn_ts_idx owner dcgn location  '/pgdata/ts/dcgn_ts_idx';
create tablespace dcgn_ts_lob owner dcgn location '/pgdata/ts/dcgn_ts_lob';

В указанном примере параметр «BLOCK_ID» — постфикс блока/контура, в который устанавливается DCGN.

Если установка производится инструментами Deploy Tools, то значение параметра можно посмотреть в файле ansible/common.conf.yml common-репозитория блока/контура.

При установке компонента DCGN инструментами Deploy Tools, создание пользователя и схемы БД можно произвести в полуавтоматическом режиме, смотрите раздел «Инициализация БД».

Примечание.

Рекомендуемое значение параметров

для БД - max_connection=200

для pgBouncer значение max_client_conn=2000 (max_connection*10)

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

На этом шаге нужно создать namespase в кластере K8s или OSE (опционально), в котором будут создаваться объекты, необходимые для работы DCGN.

Созданный namespase необходимо подключить к Istio Service mesh или OpenShift Service mesh (опционально).

Создание и настройка сертификатов#

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

В поставляемой конфигурации DCGN настроен mTLS. Поэтому необходимо выпустить egress и ingress сертификаты для блока/контура, где производится установка DCGN. Сертификаты необходимо поместить в защищенное хранилище и его параметры передать в соответствующие конфигурации DCGN.

Авторизация внешних/внутренних вызовов#

В поставляемой конфигурации DCGN настроен механизм аутентификации и авторизации (входящие/исходящих вызовы). Поэтому необходимо добавить параметр, который проверяет сертификат клиента на соответствие регулярному выражению.

Сертификаты для One-Time Password (OTP) / OTT#

В поставляемой конфигурации DCGN подключен компонент Платформы One-Time Password (OTP) / OTT, опционально. Для взаимодействия с компонентом One-Time Password (OTP) / OTT необходимо выпустить сертификаты для блока/контура, где производится установка DCGN. Сертификаты необходимо поместить в защищенное хранилище и его параметры передать в соответствующие конфигурации DCGN.

Более подробное описание конфигурации приводится в документации Platform V Backend на компонент One-Time-Token в «Руководстве по установке».

Сертификаты для SSL-взаимодействия с Kafka для Журналирования (LOGA)#

В поставляемой конфигурации DCGN используется SSL-взаимодействие с Kafka для Журналирования (LOGA). Поэтому необходимо выпустить сертификаты Kafka для блока/контура, где производится установка DCGN.

Сертификаты для SSL-взаимодействия с БД#

В поставляемой конфигурации DCGN используется SSL-взаимодействие с БД. В директории /home/postgres/ssl проверить наличие сгенерированных серверных сертификатов, при их отсутствии сгенерировать серверные сертификаты. Сгенерировать клиентский сертификат (используя корневые сертификаты) и при необходимости осуществить подписание, как серверных сертификатов, так и клиентских сертификатов в УЦ. Корневой и клиентский сертификаты необходимо поместить в защищенное хранилище сертификатов и передать его параметры в соответствующие конфигурации DCGN.

Настройка параметров#

Компонент IAM Proxy#

Для отображения ссылки на сервис template-registry необходимо добавить junction-конфигурацию в сервис RDS:

rds-server@ZoneConfig[Core]/JunctionConfig[DCGN_templaterregistry]/applyJctRequestFilter=
rds-server@ZoneConfig[Core]/JunctionConfig[DCGN_templaterregistry]/junctionPoint=/template-registry
rds-server@ZoneConfig[Core]/JunctionConfig[DCGN_templaterregistry]/junctionName=DCGN. Template Registry
rds-server@ZoneConfig[Core]/JunctionConfig[DCGN_templaterregistry]/indexUrl=/template-registry/ui/
rds-server@ZoneConfig[Core]/JunctionConfig[DCGN_templaterregistry]/authorizeByRoleTemplate=
rds-server@ZoneConfig[Core]/JunctionConfig[DCGN_templaterregistry]/sslCommonName=*
rds-server@ZoneConfig[Core]/JunctionConfig[DCGN_templaterregistry]/transparent=true
rds-server@ZoneConfig[Core]/JunctionConfig[DCGN_templaterregistry]/serverAddresses={nginx_ui_host:port};
rds-server@ZoneConfig[Core]/JunctionConfig[DCGN_templaterregistry]/https=true

При интеграции с СУДИР выполнить регистрацию UI реестра шаблонов DCGN в СУДИР по принятым процессам в используемой инсталляции.

Компонент Объединенный сервис авторизации (ОСА)#

Для создания в Объединенном сервисе авторизации (ОСА) привилегий, наборов привилегий (ролей) и групп пользователей DCGN нужно импортировать ролевую модель DCGN в Объединенный сервис авторизации (ОСА) (AUTZ). Импорт производится путем REST-запроса на импорт ролевой модели в Объединенный сервис авторизации (ОСА) (AUTZ). Импорт может быть выполнен как на шаге установки дистрибутива (смотрите раздел «Выполнение установки»), так и после установки DCGN. При установке с помощью компонента Deploy Tools импорт происходит при выборе playbook IMPORT_SECURITY_PARAMS.

Установка DCGN в контейнеризованную среду (Kubernetes или OpenShift (опционально))#

Установка производится путем создания объектов в контейнеризированной среде на основе поставляемых в дистрибутиве yaml-конфигураций и установкой для них параметров, характерных для блока/контура.

Далее приведен пример установки с помощью компонента Deploy Tools.

Установка с помощью компонента Deploy Tools#

Перед началом установки убедитесь, что инструменты Deploy Tools сконфигурированы должным образом. Для более тонкой настройки смотрите инструкции компонента Deploy Tools.

Создание репозитория конфигураций#

Необходимо создать репозиторий для миграции и хранения конфигураций компонента DCGN. Репозиторий создается в той же проектной области, где находится common-репозиторий Deploy Tools.

Common-репозиторий — git-репозиторий глобальных настроек (переменных), которые используются всеми компонентами Platform V в рамках блока/контура.

Имя репозитория формируется по маске \<PREFIX\>_\<CHANNEL\>_\<FPI_NAME\>_\<ENVIR\>\[_\<REPO_BLOCK_ID\>\], где:

• PREFIX — в большинстве случаев константа ci00380023_efs;

• CHANNEL — сегмент или инсталляция (например: ukofl, emp, corp, fis и т. п.);

• FPI_NAME — dcgn;

• ENVIR — окружение, тип стенда (например: dev, st, ift, nt, psi и т. п.);

• REPO_BLOCK_ID — блок/контур (например: b1, sb_sk и т. п.), в случае блочной структуры хранения конфигурации.

Значение параметров определяются в соответствии с конфигурацией Deploy Tools.

Далее в созданном репозитории нужно создать ветку \<BRANCH_NAME\> , где «BRANCH_NAME» — наименование ветки репозитория.

Конфигурация common-репозитория#

Для установки компонента DCGN необходимо внести информацию в common-репозиторий стенда. Для этого нужно выполнить следующие действия:

1. В файл subsystems.json добавить блок настроек для возможности установки DCGN инструментами Deploy Tools согласно примеру ниже:

   Пример минимальной конфигурации для указанной версии компонента Deploy Tools Если версия отличается, смотрите инструкции компонента Deploy Tools.

    "DOCGEN": {                                  // наименование компонента Platform V
       "nexus_host": "<заполнить>",              // host нексус-репозитория
       "nexusPathToArtifact": "<заполнить>",     // путь до артефакта
       "nexus_repo": "<заполнить>",            // наименование нексус-репозитория
       "groupId": "<заполнить>",
       "artifactId": "<заполнить>",            // идентификатор maven артефакта
       "fpType": "bts",                        // тип компонента Platform V
       "fpi_name": "dcgn",                     // идентификатор компонента Platform V
       "serviceName": "dcgn",
       "strict": "true",
       "versionFilter": "D-01",                // регулярное выражения для фильтрации версий артефактов
       "repoFullName": "<заполнить>",          // репозиторий конфигурации
       "fpi_name_ose": "<заполнить>",          // наименование созданного namespace
       "registryPath": "<заполнить>",         // базовый путь до каталога с образами DCGN
     "agents": {                            // перечисление подключаемых агентов
       "UFS_MONITORING_CLIENT": {           // наименование агента компонента Объединенный мониторинг Unimon
            "groupId": "<заполнить>",
            "artifactId": "<заполнить>", // идентификатор maven артефакта
            "version": "<заполнить>",       // версия клиента компонента Объединенный мониторинг Unimon
            "fpi_name": "ufs-monitoring",   // идентификатор компонента Platform V
            "exclude": [                    // исключения, необходимо указать пути ingress/egress конфигураций согласно расположению в дистрибутиве агента компонента Объединенный мониторинг Unimon
                "package/conf/openshift/istio/config/ingress/*",
                "package/conf/k8s/base/istio/config/egress/egressgateway-monitoring",
                "package/conf/k8s/base/istio/config/egress/egressgateway-monitoring-client",
                "package/conf/k8s/base/istio/config/egress/egressgateway-kafka-monitoring",
                "package/conf/openshift/istio/deployments/ingress/*",
                "package/conf/openshift/istio/deployments/egress/*
             ]
             }
         }
    }
   

В данном руководстве рассматривается вариант установки агента Объединенный мониторинг Unimon, сконфигурированного как подключаемый агент к основному компоненту, это описывается в блоке UFS_MONITORING_CLIENT. Потребитель оставляет за собой право выбрать любой способ, предложенный компонентом Deploy tools. Так как используется pull-модель, дистрибутив DCGN не содержит в себе средства тиражирования метрик, а дистрибутив Объединенный мониторинг Unimon поставляется отдельно. В параметре version необходимо указать версию Объединенный мониторинг Unimon. Протестированные версии и как их сконфигурировать описано в разделе «Изменение конфигурации компонента Объединенный мониторинг Unimon».

2. В common-репозиторий необходимо добавить конфигурации подключения к БД DCGN:

   • В файл ansible/common.conf.yml для выполнения liquibase-скриптов:

     DCGN_POSTGRES_DB_URL: <URL подключения к БД Postgres>
     

   • В файл ansible/_passwords.conf:

     jdbc.DOCGEN.user=<Имя созданной учетной записи БД>
     jdbc.DOCGEN.password=<Пароль созданного учетной записи БД>
     

   • Для необходимости задания разных учетных записей для DCGN и для выполнения скриптов мигарации БД, в целях разделения полномочий на DDL и DML операции, необходимо добавить в файл ansible/_passwords.conf:

     liquibase.jdbc.DOCGEN.user=<Имя учетной записи БД для выполнения сприптов liquibase>
     liquibase.jdbc.DOCGEN.password=<Пароль учетной записи БД для выполнения сприптов liquibase>
     

   • В файл installer/system/efs/config/parameters/_global.jdbc.conf для подключения к БД из приложений:

     jdbc.dcgn_postgres.ssl.mode=<Режим работы SSL>
     jdbc.dcgn_postgres.url=<URL подключения к БД Postgres>
     

     Если не задан DCGN_POSTGRES_DB_URL, то параметр jdbc.dcgn_postgres.url используется и для выполнения liquibase-скриптов.

     Подробнее о возможных режимах работы SSL описано в документе «Руководство по системному администрированию», в разделе «Настройка и конфигурирование DCGN». Пример формирования URL для подключения к БД с использованием параметров SSL:

     jdbc:postgresql://<db-host>:<db-port>/<db-name>?sslmode=${jdbc.dcgn_postgres.ssl.mode}&sslfactory=org.postgresql.ssl.DefaultJavaSSLFactory
     

     Параметр sslfactory=org.postgresql.ssl.DefaultJavaSSLFactory является обязательным для испольования защищенного хранилища сертификатов Java-приложения.

3. В common-репозиторий в файл multiclusters.json добавить путь до реестра образов контейнеров:

   "registry": "<URL registry, где хранятся образы контейнеров>",
   "registry_path": "${fpConfig.registryPath}"
   

Используемые глобальные параметры внешних продуктов#

Для интеграции со внешними и инфраструктурными компонентами в файлах конфигурации DCGN используются ссылки на глобальные параметры из common-репозитория. В глобальных параметрах содержится информация об адресах подключения к БД, базовые URL для HTTP(-S) взаимодействий с компонентами, адреса подключения к серверам Kafka и др.

Внимание!

Отсутствие глобальных параметров без изменения поставляемой конфигурации DCGN может привести к ошибкам во время установки.

Конфигурация DCGN#

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

Общий список конфигураций:

• dcgn.all.conf — общие настройки сервисов DCGN. В основном содержит ссылки на глобальные параметры.

• dcgn.docgen-service.conf — настройки для Docgen service.

• dcgn.template-provider.conf — настройки для Template provider.

• dcgn.template-registry.conf — настройки для Template registry.

• dcgn.fluent-bit-sidecar.all.conf — настройки, которые используются для интеграции с сервисом Журналирования (LOGA).

• dcgn.istio.all.conf — общие настройки для istio. Включают в себя настройки для интеграции с сервисом Аудит (AUDT).

• dcgn.ott-sidecar.all.conf — настройки, которые используются для интеграции с сервисом OTTS.

Описание всех настроек из файлов конфигураций приведено в документе «Руководство по системному администрированию», в разделе «Настройка и конфигурирование DCGN».

При установке агента мониторинга добавляются файлы конфигурации компонента Объединенный мониторинг Unimon:

• *-monitoring.all.conf — общие настройки сервиса UNIMON.

• *-monitoring.unimon-agent.conf — настройки unimon-agent

• *-monitoring.unimon-sender.conf — настройки unimon-sender.

Как сконфигурировать мониторинг, смотрите в документе «Руководство по установке» клиентской части Объединенный мониторинг Unimon.

Миграция конфигурации из дистрибутива в репозиторий#

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

1. Перейти к job Jenkins, предназначенной для развертывания (установки) приложений.

2. В меню слева нажать на опцию «Build with parameters».

3. Установить параметры сборки:

   • SUBSYSTEM: DOCGEN;

   • COMPONENTS: Основная ФП DOCGEN; - так же выбрать UFS_MONITORING_CLIENT если установка происходит совместно с агентом Объединенный мониторинг Unimon

   • DISTRIB_VERSION: <выбрать версию дистрибутива>;

   • OSE_CLUSTERS: <выбрать кластер K8s/OpenShift (опционально)>;

   • Репозиторий/ветка с настройками ФП: <основная ветка конфигурации в соответствии с настройками Deploy Tools>;

   • PARAMS (набор playbook): <выбрать MIGRATION_FP_CONF>.

4. Запустить сборку, нажав кнопку «Build».

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

Ниже приведен пример структуры репозитория после миграции:

├── config
│   └── parameters
│       ├── dcgn.all.conf
│       ├── dcgn.docgen-service.conf
│       ├── dcgn.istio.all.conf
│       ├── dcgn.template-provider.conf
│       └── dcgn.template-registry.conf
├── inventory
│   ├── inventory
│   └── nginx_upstreams_inventory
└── version.conf

Инициализация БД#

Конфигурация Deploy Tools#

Для запуска скриптов инициализации БД необходимо настроить инструменты Deploy Tools.

1. Настроить правила распаковки родительского дистрибутива и его зависимостей для профиля db-init, файл environment.json.

{
    ...
    "downloadProfiles": {
      ...
      "db-init": {
        "parentUnpackIncludes": [
          "/package/conf/**"
        ],
        "parentUnpackExcludes": [
          "/package/conf/distrib.yml"
        ],
        "dependenciesUnpackIncludes": [
          "/package/**"
        ],
        "dependenciesUnpackExcludes": []
      }
      ...
    }
    ...
}

2. Добавить playbook DB_INIT в список возможных сценариев развертывания, файл environment.json.

    ...
    "playbooks_fpi": {
      "DB_INIT": {
        "id": 1 // идентификатор playbook, порядковый номер относительно других playbooks в репозитории
      },
      ...
    }
    ...

3. Добавить параметры в файл ansible/common.conf.yml, значения указаны в качестве примера.

DB_SCHEMA_SUFFIX: "_DEV" # суффикс БД - уникальный идентификатор
...
DCGN_POSTGRES_DB_HOST: 127.0.0.1 # IP-адрес БД
DCGN_POSTGRES_DB_PORT: 5432      # порт
DCGN_POSTGRES_DB_NAME: postgres  # имя БД
DCGN_POSTGRES_DB_URL: jdbc:postgresql://{{ DCGN_POSTGRES_DB_HOST }}:{{ DCGN_POSTGRES_DB_PORT }}/{{ DCGN_POSTGRES_DB_NAME }}
# базовая директория для хранения табличных пространств (опционально)
DCGN_POSTGRES_DB_TS_LOCATION: /pgdata/ts
# табличное пространство для основных данных (наименование и расположение на файловой системе)
DCGN_POSTGRES_DB_TS_DATA: dcgn_ts_data
DCGN_POSTGRES_DB_TS_DATA_LOCATION: "{{ DCGN_POSTGRES_DB_TS_LOCATION }}/{{ DCGN_POSTGRES_DB_TS_DATA }}" # /pgdata/ts/dcgn_ts_data
# табличное пространство для индексов (наименование и расположение на файловой системе)
DCGN_POSTGRES_DB_TS_IDX: dcgn_ts_idx
DCGN_POSTGRES_DB_TS_IDX_LOCATION: "{{ DCGN_POSTGRES_DB_TS_LOCATION }}/{{ DCGN_POSTGRES_DB_TS_IDX }}"   # /pgdata/ts/dcgn_ts_idx
# табличное пространство для больших объектов (наименование и расположение на файловой системе)
DCGN_POSTGRES_DB_TS_LOB: dcgn_ts_lob
DCGN_POSTGRES_DB_TS_LOB_LOCATION: "{{ DCGN_POSTGRES_DB_TS_LOCATION }}/{{ DCGN_POSTGRES_DB_TS_LOB }}"   # /pgdata/ts/dcgn_ts_lob

4. Добавить учетную запись БД в _passwords.conf под которой будут выполняться скрипты инициализации БД.

# глобальная учетная запись, для инициализации пользователей и схем БД компонентов платформы
POSTGRES_DB_INIT_USERNAME=<имя пользователя>
POSTGRES_DB_INIT_PASSWORD=<пароль>
# или специфичная для компонента DCGN учетная запись
DCGN_POSTGRES_DB_INIT_USERNAME=<имя пользователя>
DCGN_POSTGRES_DB_INIT_PASSWORD=<пароль>

# Пользователь БД будет создан с этими данными
jdbc.DOCGEN.user=<имя пользователя>
jdbc.DOCGEN.password=<пароль>

5. Создать директории табличных пространств на файловой системе БД.

# директория, указанная в параметре DCGN_POSTGRES_DB_TS_DATA_LOCATION
mkdir -p /pgdata/data/ts/dcgn_ts_data
chown postgres:postgres /pgdata/data/ts/dcgn_ts_data

# директория, указанная в параметре DCGN_POSTGRES_DB_TS_IDX_LOCATION
mkdir -p /pgdata/data/ts/dcgn_ts_idx
chown postgres:postgres /pgdata/data/ts/dcgn_ts_idx

# директория, указанная в параметре DCGN_POSTGRES_DB_TS_LOB_LOCATION
mkdir -p /pgdata/data/ts/dcgn_ts_lob
chown postgres:postgres /pgdata/data/ts/dcgn_ts_lob

Запуск скриптов инициализации БД#

1. Перейти к job Jenkins, предназначенной для развертывания (установки) приложений.

2. В меню слева нажать на опцию «Build with parameters».

3. Установить параметры сборки:

   • SUBSYSTEM: DOCGEN;

   • COMPONENTS: Основная ФП DOCGEN;

   • DISTRIB_VERSION: <выбрать версию дистрибутива>;

   • OSE_CLUSTERS: <выбрать кластер K8s/OpenShift (опционально)>;

   • Репозиторий/ветка с настройками ФП: <основная ветка конфигурации в соответствии с настройками Deploy Tools>;

   • PARAMS (набор playbook): <выбрать DB_INIT>.

4. Запустить сборку, нажав на кнопку «Build».

В результате выполнения будут созданы следующие объекты БД:

• пользователь (с именем - jdbc.DOCGEN.user и паролем - jdbc.DOCGEN.password) и одноименная схема БД;

• табличные пространства, указанные в параметрах: DCGN_POSTGRES_DB_TS_DATA, DCGN_POSTGRES_DB_TS_IDX, DCGN_POSTGRES_DB_TS_LOB.

Настройка мультитенантности#

Коммунальная инсталляция#

Для поддержки мультитенантности в соответствующих конфигурациях (смотрите раздел «Конфигурация DCGN») требуется задать следующие параметры:

dcgn.template-provider.unimonId
dcgn.template-registry.unimonId
dcgn.docgen-service.unimonId
dcgn.template-provider.rn
dcgn.template-registry.rn
dcgn.docgen-service.rn

Platform V Backend#

Для поддержки мультитенантности в Platform V Backend требуется выполнить следующие действия:

1. Для обратной совместимости с бэкенд в конфигурации мониторинга нужно включить автономный режим (см. в документе «Руководство по установке» клиентской части Объединенный мониторинг Unimon).

2. В соответствующих конфигурациях (смотрите раздел «Конфигурация DCGN») не задавать параметры:

dcgn.template-provider.unimonId
dcgn.template-registry.unimonId
dcgn.docgen-service.unimonId

Примечание.

Для инсталляции с настроенным взаимодействием через Topic (Kafka) и без unimon server параметр «unimonId» задается произвольным значением (смотрите раздел «Конфигурация DCGN» ufs-monitoring.unimon-sender.conf — настройки unimon-sender).

Изменение конфигурации компонента Объединенный мониторинг Unimon#

Необходимо сконфигурировать клиента мониторинга согласно инструкции компонента Объединенный мониторинг Unimon с учетом требований к сервису DCGN, выставить в файлах конфигурации клиента мониторинга значения настроек:

• unimon-sender.sidecar.istio.rewriteAppHTTPProbers=true

• unimon.server.enable=false, если на инсталяции не предполагается взаимодейтсиве с сервером Unimon.

• metric.label.rn - очистить значение, так как информация о RN передается на уровне метрик сервиса;

Проверка конфигурации#

Для проверки конфигурации нужно выполнить следующие действия:

1. Перейти к job Jenkins, предназначенной для развертывания (установки) приложений.

2. В меню слева нажать на опцию «Build with parameters».

3. Установить параметры сборки:

   • SUBSYSTEM: DOCGEN;

   • COMPONENTS: Основная ФП DOCGEN; - так же выбрать UFS_MONITORING_CLIENT если установка происходит совместно с агентом Объединенный мониторинг Unimon

   • DISTRIB_VERSION: <выбрать версию дистрибутива>;

   • OSE_CLUSTERS: <выбрать кластер K8s/OpenShift (опционально)>;

   • Репозиторий/ветка с настройками ФП: <основная ветка конфигурации в соответствии с настройками Deploy Tools>;

   • PARAMS (набор playbook): <выбрать FP_CONF_CHECK>.

4. Запустить сборку, нажав кнопку «Build».

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

Ниже приведен пример отсутствия глобальных переменных:

------------------------------------------------------------------------------------------
Проверка соответствия параметров в конфигурационных файлах <fp_name>.conf и _global.conf
------------------------------------------------------------------------------------------
Не найдено значений для global.platform.pprb.baseurl.audit в файле dcgn.template-registry.conf
Не найдено значений для global.platform.ingress.route.http в файле dcgn.istio.all.conf
Не найдено значений для global.platform.ingress.route.https в файле dcgn.istio.all.conf

Выполнение установки#

Для установки ПО необходимо выполнить следующие действия при запуске Job-развертывания:

1. Установить параметры сборки:

   • SUBSYSTEM: DOCGEN;

   • COMPONENTS: Основная ФП DOCGEN; - так же выбрать UFS_MONITORING_CLIENT если установка происходит совместно с агентом Объединенный мониторинг Unimon

   • DISTRIB_VERSION: <выбрать версию дистрибутива>;

   • OSE_CLUSTERS: <выбрать кластер K8s/OpenShift (опционально)>;

   • Репозиторий/ветка с настройками ФП: <основная ветка конфигурации в соответствии с настройками Deploy Tools>;

   • PARAMS (набор playbook): <выбрать SHIFT_OK>.

2. Запустить сборку, нажав кнопку «Build».

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

В случае если playbook SHIFT-OK отсутствует, то нужно выбрать playbooks, приведенные в таблице ниже.

Набор возможных playbooks зависит от конфигурации инструментов Deploy Tools.

Рекомендации после установки компонентом Deploy Tools#

Для облегчения интеграции потребителей с DCGN, которые используют Deploy Tools, рекомендуется:

• добавить глобальные параметры для подключению к сервисам DCGN,

• добавить playbook импорта архива шаблона в DCGN.

Глобальные параметры для подключения к сервисам#

В файл installer/system/efs/config/parameters/_global.resources.conf добавить глобальные параметры для подключения к сервисам:

• сервис генерации документов (docgen-service),

• провайдер шаблонов (template-provider).

Примечание. Наименования параметров носит рекомендательный характер.

Playbook импорта шаблонов#

Для возможности импортирования архивов шаблонов рекомендуется добавить playbook импорта шаблонов — IMPORT_DCGN_PARAMS. Deploy Tools поставляется с common-конфигурациями, в которых по умолчанию настроен playbook.

Если необходимо настроить playbook вручную (например, если в common-репозитории переопределен блок playbooks_import для среды):

• В common-репозитории в environment.json добавить:

"IMPORT_DCGN_PARAMS": {
   "id": 14, // идентификатор playbook, порядковый номер относительно других playbooks в репозитории
   "description": "Импорт архивов шаблонов DCGN", // Необязательный параметр для отображения при выборе playbook и в отчете в результатах
   "dataDir": "dcgn_templates" // Обязательный параметр, указывающий на директорию в conf/data/ в дистрибутиве с архивами шаблонов для сервиса
   "authType": "ott" // тип авторизации, для OTTS необходимо указать "ott", по-умолчанию - "basic" (Basic Authorization)
 },

• Занести в _global.resources.conf адрес нового загрузчика в формате:

global.import.service.dcgn.url=${global.platform.url.template-registry}

В pipeline для playbook должны быть настроенны OTT-авторизация и SSL, подробнее по настройке в документации компонента Deploy Tools.

Обновление#

Обновление с версии 1.0.0 на версию 1.2.0#

Обновление происходит по следующим шагам:

1. Для работы с сервисом template-registry выполнить настройку IAM proxy и Объединенного сервиса авторизации (ОСА). Подробнее описано в разделе «Настройка параметров» настоящего документа.

2. Задать значения для параметров конфигураций для версии 1.0.1 и 1.1.0, описанные в «Руководстве по системному администрированию» в разделе «Настройка и конфигурирование DCGN».

3. Удалить неиспользуемые конфигурации от ранних версий DCGN из namespace. Для удаления неиспользуемых конфигураций воспользуйтесь playbooks «OPENSHIFT_DEL_RES» в pipeline SECURITY от Deploy tools. В openshift_del_res.conf необходимо указать ресурсы для удаления:

openshift_del_res.project.1.cluster = <имя кластера из multiClusters>
openshift_del_res.project.1.projects = <имя проекта, откуда будут удалены ресурсы сервиса DCGN>
# список проектов на удаление, можно списком, через запятую
openshift_del_res.projectList = 1
###################### УДАЛЕНИЕ ОБЪЕКТОВ ПО ИМЕНИ И ТИПУ ######################

# тут писать имена удаляемых ресурсов, можно список - через запятую
# удаление deploymants
openshift_del_res.delete_by_name.projects.dpl = off
# удаление deploymentconfigs
openshift_del_res.delete_by_name.projects.dc = off
# удаление imagestreams
openshift_del_res.delete_by_name.projects.is = off
# удаление routes
openshift_del_res.delete_by_name.projects.routes = off
# удаление configmaps
openshift_del_res.delete_by_name.projects.cfgmaps = dcgn-cm-fluent-bit-conf.unver,dcgn-cm-iam-publickey.unver,dcgn-cm-istio-unver,dcgn.all.conf.unver,dcgn-cm-docgen-service-logback-xml.unver,dcgn-cm-template-provider-logback-xml.unver,dcgn-cm-template-registry-logback-xml.unver,dcgn-egress-ott-conf-unver,dcgn-ingress-ott-conf-unver,dcgn.docgen-service.conf.unver,dcgn.fluent-bit-sidecar.all.conf.unver,dcgn.istio.all.conf.unver,dcgn.ott-sidecar.all.conf.unver,dcgn.template-provider.conf.unver,dcgn.template-registry.conf.unver
# удаление secrets
openshift_del_res.delete_by_name.projects.secrets = dcgn-logger-kafka-cert.unver,dcgn-ott-secrets.unver,egressgateway-certs.unver,egressgateway-ca-certs.unver,dcgn-ott-certs.unver,ingressgateway-certs.unver,ingressgateway-ca-certs.unver
# удаление pods
openshift_del_res.delete_by_name.projects.pods = off
# удаление services
openshift_del_res.delete_by_name.projects.srv = off
# удаление replicationcontrollers
openshift_del_res.delete_by_name.projects.rplc = off
# удаление horizontalpodautoscalers
openshift_del_res.delete_by_name.projects.hpa = off
# удаление replicasets
openshift_del_res.delete_by_name.projects.rs = off
# удаление serviceentries
openshift_del_res.delete_by_name.projects.se = off
# удаление gateways
openshift_del_res.delete_by_name.projects.gw = off
# удаление destinationrules
openshift_del_res.delete_by_name.projects.dsr = off
# удаление virtualservices
openshift_del_res.delete_by_name.projects.vs = off
# удаление envoyfilters
openshift_del_res.delete_by_name.projects.ef = off

4. Выполнить шаги из раздела «Обновление с версии 1.1.0 на версию 1.2.0».

Обновление с версии 1.1.0 на версию 1.2.0#

Обновление происходит по следующим шагам:

1. При сборке с помощью Build Tools (Solution Merger Job) наполнить продукт зависимостями согласно рекомендациям в пункте «Рекомендации по наполнению продукта зависимостями при сборке с помощью Build Tools (Solution Merger Job)».

2. Сконфигурировать параметры, которые были добавлены в версии 1.2.0. Новые параметры описаны в «Руководстве по системному администрированию» в разделе «Настройка и конфигурирование DCGN», для новых параметров в столбце «Версия ПО» указывается версия 1.2.0.

3. Сконфигурировать SSL для БД согласно разделу «Сертификаты для SSL-взаимодействия с БД».

4. В файл subsystems.json добавить базовый путь до каталога с образами DCGN согласно примеру в разделе «Конфигурация common-репозитория» в пункте 1.

5. Выполнить настройки, которые приведены в разделе «Конфигурация common-репозитория» в пункте 3.

6. Установить версию 1.2.0 (установка через Deploy Tools описана в разделе «Выполнение установки»).

Удаление#

Для удаления DCGN необходимо выполнить следующие действия:

1. Удалить созданный namespace в кластере K8s или OSE (опционально);

2. Если установка производилась Deploy Tools, удалить:

• репозиторий конфигураций;

• созданные глобальные переменные;

• созданный playbook импорта.

3. Удалить пользователя и схему БД.

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

Проверка корректности работы DCGN включает проверку по следующим позициям:

1. В контейнеризованной среде (Kubernetes или OpenShift (опционально)) созданы объекты, соответствующие конфигурации в дистрибутиве.

2. Поды сервисов запущены (находятся в статутсе Running) и контейнеры работают без ошибок.

3. На вызов Endpoint с healthcheck приходит ответ: {"success":true,"body":"ON"}. Формирование ссылки описано в документе «Руководство по системному администрированию», раздел «Правила формирования ссылки до healthcheck сервисов». Пример curl запроса, с целевым взаимодействием с сервисом через mTLS и передачей в запросе клиентского и корневого сертификатов:

curl --cert tls.crt --key tls.key --cacert root.crt протокол://хост:порт/docgen-service/healthcheck

4. Метрики состояния сервисов возвращают значение доступности сервиса (метрики указаны в документе «Руководство по системному администрированию», в разделе «События мониторинга»).

5. Пользователю UI DCGN после успешной аутентификации в IAM Proxy или СУДИР и авторизации открывается приложение «Реестр шаблонов документов» на вкладке меню «Шаблоны документов».

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

Откат#

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

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

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

В целях проверки корректности установки необходимо пройти по всем пунктам чек-листа.