Инструкция по установке экземпляра ПО

Установка Platform UI осуществляется методом развертывания на кластере Kubernetes с использованием утилит kubectl, helm. Необходимые образы и скрипты для установки находятся в публичном репозитории registry.datasapience.ru.

Образы и скрипты для установки экземпляра ПО расположены в проекте {$DATASAPIENCE_REPO}:

Docker-images:

registry.datasapience.ru/${DATASAPIENCE_REPO}/gbcm/gbcm-ui:{$TAG}

registry.datasapience.ru/${DATASAPIENCE_REPO}/gbcm-backend/cluster-manager:{$TAG}

registry.datasapience.ru/${DATASAPIENCE_REPO}/gbcm/gbcm-documentation:{$TAG}

Helm Charts:

https://registry.datasapience.ru/chartrepo/${DATASAPIENCE_REPO}/charts/gb-cm-ui.tgz

https://registry.datasapience.ru/chartrepo/${DATASAPIENCE_REPO}/charts/cm-cluster-manager.tgz

https://registry.datasapience.ru/chartrepo/${DATASAPIENCE_REPO}/charts/gb-cm-documentation.tgz

${DATASAPIENCE_REPO} – URL репозитория DataSapience
${TAG} – тэг, актуальной версии, которую планируется устанавливать

Порядок установки

Установка Platform UI производится путем выполнения шагов, описанных ниже.

Перед установкой требуется проверить наличие необходимых утилит. Это выполняется следующими командами:

kubectl version

helm version

Обе команды должны выдать версию установленной утилиты. В противном случае, если при запуске одной из команд произошла ошибка, необходимо установить недостающую утилиту.
К данной инструкции приложен архив с конфигурацией клиента в KeyCloak для корректной работы сервиса аутентификации/авторизации пользователей (keycloak-clustermanager.zip)
К данной инструкции приложены таблицы, содержащие примеры заполнения параметров установки:

Приложение 1 – таблица со списком параметров для настройки компонентов API и backend (cm_values_back)

Приложение 2 – таблица со списком параметров для настройки компонентов фронта (cm_values_front)

Приложение 3 – таблица со списком параметров для настройки компонентов документации (cm_values_documentation)

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

После создания в Postgres схемы onprem_deployment необходимо установить расширение Postgres pgcrypto. Для установки расширения необходимо выполнить следующие запросы:

DROP EXTENSION IF EXISTS pgcrypto;

SET search_path TO public, pgcrypto, onprem_deployment;

CREATE EXTENSION pgcrypto

Регистрация Helm-репозитория DataSapience

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

`$DATASAPIENCE_REPO` – URL репозитория DataSapience, например hps://registry.datasapience.ru/chartrepo/clustermanager
`$DATASAPIENCE_REPO_USER` – Имя пользователя репозитория DataSapience
`$DATASAPIENCE_REPO_PASS_FILE` – Путь к файлу с паролем пользователя репозитория DataSapience

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

helm repo add datasapience $DATASAPIENCE_REPO username $DATASAPIENCE_REPO_USER password $(cat $DATASAPIENCE_REPO_PASS_FILE

Получение Helm-чартов

Для получения Helm-чартов необходимо создать директорию для хранения файлов развёртывания, например clustermanager, и перейти в неё, выполнив команды:

mkdir clustermanager

cd clustermanager

Получить Helm-чарты для модулей Platform UI можно, выполнив команды:

helm pull datasapience/cm-cluster-manager

helm pull datasapience/gb-cm-ui

helm pull datasapience/gb-cm-documentation

Далее необходимо распаковать архивы tgz:

tar -xvf cm-cluster-manager-0.0.1.tgz

tar -xvf gb-cm-ui-0.0.1.tgz

tar -xvf gb-cm-documentation-0.0.1.tgz

В соответствии со сценарием развертывания необходимо определить параметры для каждого модуля, для этого необходимо указать дополнительные файлы с параметрами для каждого модуля. Дополнительные файлы конфигурации по каждому из модулей: cm_values_back, cm_values_front и cm_values_documentation (Приложение 1, Приложение 2, Приложение 3).

Получение docker-образов

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

docker login

При выполнении данной команды производится авторизация под учетной записью с доступом к репозиторию, по завершении которой создается json-файл конфига docker-а. Обычно файл создается в следующей директории: ‘~/.docker/config.json’

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

kubectl create secret generic regcred \--from-file=.dockerconfigjson=<path/to/.docker/config.json> \
--type=kubernetes.io/dockerconfigjson

Для ее выполнения необходимо заменить <path/to/.docker/config.json> на директорию созданного ранее конфиг-файла docker-а.

Параметры docker-образов

Для указания пути к репозиторию с docker-образами модулей и конкретных версий docker-образов для развертывания необходимо в файлах с дополнительными параметрами развертывания задать/изменить значения для следующих параметров:

`service.image.repository` – путь к репозиторию с docker-образами

`service.image.tag` – версия модуля, которая требуется для установки

Параметры развертывания

В процессе установки Platform UI производится развертывание модуля cm-cluster-manager, который включает перечень сервисов, таких как PostgreSQL, Kafka и Keycloak, которые имеют свои особенности по настройке параметров при установке Platform UI. Описание основных параметров чартов Platform UI представлено в Приложении 1 и Приложении 2.

Важно

Обратите внимание, что параметр explore.enabled в cm_values_front должен иметь значение false.

Параметры БД PostgreSQL

Настройка параметров БД PostgreSQL зависит от того необходимо ли совместное развёртывание сервиса или будет реализовано подключение к существующей внешней БД.

При совместном развёртывании БД PostgreSQL необходимо установить параметр `service.postgresql.enabled` в значение `true`, а также задать значения параметров в блоке `service.secrets.gbcm-db-secret`, которые необходимы для подключения к БД. Важно, что для параметров ‘service.secrets.gbcm-db-secret.[db.username]‘ и ‘service.postgresql.auth.username’ должны быть заданы идентичные значения.* Остальные параметры из блока ‘service.postgresql’* остаются в значениях, заданных по умолчанию.
При использовании внешней БД PostgreSQL необходимо установить параметр `service.postgresql.enabled` в значение `false` , а также задать значения параметров в блоке `service.secrets.gbcm-db-secret`.

Параметры Keycloak

Настройка параметров сервиса Keycloak зависит от того необходимо ли совместное развёртывание сервиса или будет реализовано подключение к существующему внешнему сервису.

При совместном развёртывании сервиса Keycloak необходимо:
установить параметр `service.keycloak.enabled` в значение `true`,
задать параметр `service.extra_vars.KEYCLOAK_ISSUER_URI’ и параметры блока `service.secrets.keycloak-auth`, которые необходимы для подключения к Keycloak. Также, при необходимости, задать параметр `service.secrets.KEYCLOAK_FLOW`, который необходим для обозначения используемого Keycloak Flow. Задать можно либо Standard Flow, либо Implicit Flow. По умолчанию используется Standard Flow,
задать параметры блока `service.keycloak.ingress` для ingress, в том числе параметры аннотации для корректной работы CORS политик: ‘service.annotations.nginx.ingress.kubernetes.io/cors-allow-origin’(URL фронта Platform UI) и ‘service.annotations.nginx.ingress.kubernetes.io/enable-cors’.

Остальные параметры из блока ‘service.keycloak’ остаются в значениях, заданных по умолчанию.

При использовании внешнего сервиса Keycloak необходимо установить параметр `service.keycloak.enabled` в значение `false` , а также задать значение параметра ‘service.extra_vars.KEYCLOAK_ISSUER_URI’

Параметры Kafka

Настройка параметров сервиса Kafka зависит от того необходимо ли ставить сервис или нет.

Если ставить сервис Kafka необходимо, то параметр `service.extra_vars.LISTENER_ENABLE` должен быть установлен в значение `true` и должны быть заданы параметры сервиса для его развертывания:

'service.extra_vars.KAFKA_BOOTSTRAP-SERVERS',

'service.extra_vars.KAFKA_SECURITY_PROTOCOL',

'service.extra_vars.KAFKA_AUTH_USER',

'service.extra_vars.KAFKA_AUTH_PASSWORD'

С описанием данных параметров можно ознакомиться в Приложении 1.

Если ставить сервис Kafka не нужно, то параметр `service.extra_vars.LISTENER_ENABLE` должен быть установлен в значение `false`

Конфигурация Keycloak

Для Platform UI необходимо сконфигурировать сервис KeyCloak:

зарегистрировать аутентификационного клиента (Client), если он был не зарегистрирован ранее
добавить роли Platform UI (Client Roles)

Конфигурация Keycloak может быть выполнена путем импорта файла конфигурации. К данной инструкции приложен архив keycloak-clustermanager.zip. Архив содержит следующие файлы:

kc_import.sh – скрипт импорта
cm-import-keycloak.cfg – пример конфига для импорта, параметры указаны справочно
cm-keycloak-release-2.5.0.zip – файл с настройками

Для импорта архив нужно разархивировать. Импорт файла конфигурации Keycloak можно реализовать двумя способами:

Выполнить импорт через интерфейс Keycloak (такая возможность есть не во всех версиях Keycloak)
Выполнить скрипт импорта kc_import.sh

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

В боковой панели консоли администратора Keycloak для выбранного Realm выбрать пункт «Manage» – «Import»
Выбрать папку с файлами cm-keycloak (которую ранее разархивировали) «Select file»
На следующем шаге:
если клиент был сконфигурирован ранее, выключить «Import clients» в «OFF», в «If a resource exists» выбрать «Overwrite»
если клиент не был ранее сконфигурирован, оставить «Import clients» в «ON», в «If a resource exists» выбрать «Fail»
Нажать «Import» для импорта конфигурации

Для выполнения импорта файла конфигурации посредствам запуска скрипта импорта kc_import.sh, необходимо выполнить следующие шаги:

Определить и задать переменные в конфигурационном файле cm-import-keycloak.cfg:
BASE_URL - ссылка на веб-интерфейс Keycloak (как правило должна заканчиваться на /auth)
APP_REALM - реалм, в котором находятся настройки приложения, которое необходимо экспортировать/импортировать
USER - пользователь, из-под которого скрипт будет логиниться в Keycloak
PASSWORD - пароль пользователя
USER_REALM - реалм, в котором заведён пользователь
CLIENT_NAME - имя клиента, настройки которого необходимо экспортировать/импортировать
GROUPS_PREFIX - Начало имени групп, которые необходимо экспортировать/импортировать (необязательный параметр для import.sh)
DATA_PATH - локальный путь в файловой системе куда/откуда будут экспортированы/импортированы настройки в виде структуры папок с JSON файлами
Отредактировать скрипт импорта kc_import.sh (если необходимо)

Данный скрипт берёт файлы с конфигурацией из папки, указанной в переменной DATA_PATH и импортирует их в Keycloak.

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

Скрипт выполняет предварительную проверку и если импортируемая сущность уже существует в Keycloak, то он её обновляет, если нет - создает. Client Role Composites и Group Role Mappings не поддерживают метод Update, в связи с чем они всегда предварительно удаляются, а затем создаются заново.

Выполнить скрипт импорта, запустив следующую команду:
```
./kc_import.sh <path/to/cm-import-keycloak.cfg>
```

Для ее выполнения необходимо заменить <path/to/cm-import-keycloak.cfg> на директорию файла конфига импорта cm-import-keycloak.cfg.

В результате выполнения импорта:

В Keycloak появится новый клиент: cluster.manager.frontend
В Keycloak появятся клиентские роли:
- admin;
- security_admin;
- admin_api;
- admin_gp;
- admin_nova;
- admin_ch;
- admin_dwh;
- readonly;
- user_gp;
- user_nova;
- user_ch;
- user_dwh
В Keycloak появятся группы:
- cluster-manager-admin;
- cluster-manager-admin-ch;
- cluster-manager-admin-dwh;
- cluster-manager-admin-gp;
- cluster-manager-admin-nova;
- cluster-manager-api-admin;
- cluster-manager-security_admin;
- cluster-manager-user;
- cluster-manager-user-ch;
- cluster-manager-user-dwh;
- cluster-manager-user-gp;
- cluster-manager-user-nova.

Таблица настроек соответствия ролей и групп:

Группа	Роль
cluster-manager-admin	admin
cluster-manager-admin-ch	admin_ch
cluster-manager-admin-dwh	admin_dwh
cluster-manager-admin-gp	admin_gp
cluster-manager-admin-nova	admin_nova
cluster-manager-api-admin	admin_api
cluster-manager-security_admin	security_admin
cluster-manager-user	readonly
cluster-manager-user-ch	user_ch
cluster-manager-user-dwh	user_dwh
cluster-manager-user-gp	user_gp
cluster-manager-user-nova	user_nova

Примечание

Неиспользуемые роли и/или группы можно удалить.

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

Открыть Keycloak и на вкладке «Clients» найти клиента cluster.manager.frontend
На открывшейся странице клиента cluster.manager.frontend в полях «Valid redirects URLs» и «Web origins» необходимо проставить соответствующий домен фронта Platform UI
В разделе «Capability config» задать настройки аутентификации: поставить галочку для Implicit flow или активировать Client authentication и поставить галочку для Standard flow.
Нажать кнопку «Save»

Также необходимо убедиться в корректных настройках Client Scopes. Для этого:

Перейти в раздел Client Scopes для Realm и убедиться, что создан client scope под названием «cluster-manager».

Если не создан, то создать и добавить в него следующие Mappers:

a. client roles:

i.  Mapper type: User Client Role

ii. Name: client roles

iii. Add to access token: ON

b. user-groups:

i.  Mapper type: Group Membership

ii. Name: user-groups

iii. Token Claim Name: group_membership

iv. Full group path: ON

v.  Add to ID token: ON

vi. Add to access token: ON

vii. Add to userinfo: ON

viii. Add to token introspection: ON

Перейти в раздел «Client Scopes» клиента cluster.manager.frontend и убедиться, что добавлен scope «cluster-manager» и Assigned type = default.

Следующим шагом администратору требуется создать пользователей в Keycloak и добавить их в соответствующие группы.

Установка компонентов

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

`$UI_NAMESPACE` - Kubernetes namespace для модуля ui, например `clustermanager`
`$BACKEND_NAMESPACE` - Kubernetes namespace для модуля backend, например `clustermanager`
`$DOC_NAMESPACE` - Kubernetes namespace для модуля documentation, например `clustermanager`

Далее выполнить команды:

helm install cm-cluster-manager ./cm-cluster-manager -namespace $BACKEND_NAMESPACE -create-namespace \--debug -f cm_values_back.yaml

helm install gbcm-ui ./gb-cm-ui -n $UI_NAMESPACE \--debug -f cm_values_front.yaml

helm install gbcm-documentation ./gb-cm-documentation -n $DOC_NAMESPACE \--debug -f cm_values_documentation.yaml

helm upgrade cm-cluster-manager ./cm-cluster-manager \--namespace $BACKEND_NAMESPACE \--debug -f cm_values_back.yaml

helm upgrade gbcm-ui-1 ./gb-cm-ui \--namespace $UI_NAMESPACE \--debug -f cm_values_front.yaml

helm template ./gb-cm-ui \--namespace $UI_NAMESPACE \--debug -f cm_values_front.yaml

helm upgrade gbcm-documentation ./gb-cm-documentation \--namespace $DOC_NAMESPACE \--debug -f cm_values_documentation.yaml

Добавление сертификатов при установке CM

При ошибке работы сертификатов нужно выполнить следующую инструкцию:

Получить всю цепочку сертификатов для CM:
1. Зайти в браузере на адрес, по которому должен быть расположен frontend CM;
2. В браузере рядом с адресом нажать на кнопку Secure;
3. В появившемся окне будет цепочка сертификатов. Каждый сертификат из цепочки скачать и разместить на управляющий сервер, с которого производится установка и настройка CM;
Выгрузить truststore из пода бекэнд сервиса на управляющий сервер, с которого производится установка и настройка CM:
```
kubectl -n <namespace_name> cp <backend_pod_name>:/usr/local/openjdk-17/lib/security/cacerts~/cacerts
```
Через keytool добавить всю цепочку сертификатов, полученную в пункте 1, в truststore из пункта 2. Для каждого сертификата выполнить команду ниже:
```
keytool -importcert -file <cert_name> -keystore cacerts -alias "<придумать_название_сертификата>"
```

В файл decision-backend-values.yaml прописать persistent volume:

# PV-8: Java CA certs

persistentVolumes:
    - name: cacerts
      mountPath: /usr/local/openjdk-17/lib/security/cacerts
      subPath: cacerts
      configMap: cacerts
      items:
          - key: cacerts
            path: cacerts
...
extra_vars:
    ...
    # Java OPTS
        - name: JDK_JAVA_OPTIONS
          value: >-

-Djavax.net.ssl.trustStore=/usr/local/openjdk-17/lib/security/cacerts

-Djavax.net.ssl.trustStorePassword=changeit

Создать configmap с этим JKS:

kubectl -n cm create configmap cacerts --from-file=cacerts=./cacerts

Передеплоить бекэнд-сервис:

helm upgrade cm-cluster-manager ./cm-cluster-manager --namespace
<namespace_name> --debug -f decision-backend-values.yaml

kubectl -n <namespace_name> delete pod <backend-pod>