РАЗВЕРТЫВАНИЕ СИСТЕМЫ. PORTAINER

Получение архива дистрибутива системы

Для получения ссылки на загрузку архива и пароль от него направьте на адрес службы поддержки пользователей support@dppm.pro обращение: «Предоставьте доступ на загрузку архива и пароль от него для компании Х», только после предоставления доступа выполните нижеописанные действия.

По полученной ссылке скачайте архив (например planr_ХХХ.х.zip, где Х номер версии ПО). Структура архива устроена следующим образом (Рисунок 2):

Структура каталогов дистрибутива

• Каталог planr – содержит набор файлов конфигурации PLAN-R и всех необходимых сервисов.
  • stop.sh – файл bash-скрипта, останавливающий систему PLAN-R;
  • start.sh – файл bash-скрипта, запускающий систему PLAN-R;
  • .env – переменные среды, отвечающие за настройку системы PLAN-R (Подробная информация представлена в разделе Переменные окружения);
  • Файл docker-compose.yml – файл, содержащий все настройки системы PLAN-R и сервисов необходимых для работы системы;
  • Каталог /scripts – содержит скрипты для бэкапа базы данных postgresql (dump.sh) и восстановления из бэкапа базы данных (restore.sh) (см. п. 8.4.2 Настройка бэкапов системы)
  • Каталог /logging – содержит необходимые файлы конфигурации для системы логирования (Grafana, Loki, Fluent-bit);
• Каталог images – содержит заархивированные docker-образы системы PLAN-R и всех необходимых компонентов привязанных к версии ПО.
  • load.sh – файл bash-скрипта, который выполняет загрузки docker-образов из архива;
  • push-to-registry.sh – файл bash-скрипта, выполняет загрузку образов в приватный репозиторий;
• planr-x.x.x.tgz – heml chart для установки в среде Kubernetes (Preview) (см. п. 8.5 Установка PLAN-R в Kubernetes (preview)).

Скачанный архив рекомендуется скопировать в каталог /opt/dppm/dist, предварительно его создав, если он не существует.

Подготовка к установке (Linux)

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

1. Убедится, что установлено необходимое ПО Docker (19.03.0+) и docker-compose (1.27.1+)

# docker --version
Docker version 24.0.7, build afdd53b

# docker-compose –version
Docker Compose version v2.23.3-desktop.2

2. Рекомендуется подготовить структуру каталогов для развертывания системы.

Рекомендуемая структура каталогов:

• /opt/dppm/ – каталог текущей развернутой системы
• /opt/dppm/distr – каталог для хранения скачанных дистрибутивов
• /opt/dppm/postgres_dump – каталог для бэкапов базы данных

Создайте структуру каталогов выполнив следующие команды.

# mkdir /opt/dppm && mkdir /opt/dppm/distr && mkdir /opt/dppm/postgres_dump
# cd /opt/dppm
# ls -lha

total 16K
drwxr-xr-x 4 root root 4.0K Mar 28 14:05 .
drwxr-xr-x 5 root root 4.0K Mar 28 14:05 ..
drwxr-xr-x 2 root root 4.0K Mar 28 14:05 distr
drwxr-xr-x 2 root root 4.0K Mar 28 14:05 postgres_dump

3. Переместите скачанный дистрибутив в каталог /opt/dppm/distr/

# mv <path*to_distr>/planr*<_version_>.zip /opt/dppm/distr/
# cd /opt/dppm/distr
# ls -la

total 2638584
drwxr-xr-x 2 root root       4096 Mar 28 14:05 .
drwxr-xr-x 4 root root       4096 Mar 28 14:05 ..
-rw-r-xr-x 1 root root 2701895280 Mar 28 14:05 planr_XXX.x.zip

4. Извлеките файлы из архива в каталог /opt/dppm, выполнив команды в соответствующем порядке (пароль можно получить по запросу на почту support@dppm.pro)

# unzip -P <_password_> /opt/dppm/distr/planr\_<_version_>.zip -d /opt/dppm/
# ls -lha

Извлечение файлов приложения из архива

5. После распаковки архива переходим в каталог /opt/dppm/images для загрузки docker образов командой ./load.sh. После успешной загрузки образов каталог ./images можно удалить.

• cd /opt/dppm/images
• ./load.sh

Распаковка образов PLAN-R

Установка PLAN-R (Linux)

1. Выполняем подготовку к установке (8.2.1 Подготовка к установке (Linux))
2. Переходим в директорию /opt/dppm/planr/, редактируем файл с переменными среды .env (8.4 Конфигурирование системы)
3. Выполняем старт системы с помощью ./start.sh

Успешный старт системы

Установка PLAN-R (Portainer)

1. Установить ПО Portainer (https://www.portainer.io/install) или использовать уже существующий.
2. Выполняем подготовку к установке (8.2.1 Подготовка к установке (Linux))
3. В Portainer заходим в stacks (1) ->Add stack (2), создаём новый стак с названием planr.

Создание нового стака

4. Копируем все конфигурацию из файла /opt/dppm/planr/docker-compose.yml в поле Web Editor (1), и содержимое файла с переменными среды /opt/dppm/planr/.env в поле Environment variables (2). Обязательно добавляем в переменные среды ENV_FILE=stack.env (3), это необходимо для того, чтобы Portainer считал заданные переменные среды из поля environment variables.

Настройка файлов конфигурации для Portainer

5. Если планируется использовать систему логирования - необходимо указать абсолютный путь до файлов конфигурации, которые лежат на сервере, где установлен Portainer. Для этого находимо найти сервисы Grafana, loki, fluent-bit и указать абсолютный путь до файлов конфигурации на сервере.

Указание абсолютного пути к фалам конфигурации

6. Производим конфигурирование системы путём изменения переменных среды в поле Environment variables. (8.4 Конфигурирование системы)
7. Нажимаем кнопку “Deploy the stack” и убеждаемся, что контейнеры запустились.

Работа системы PLAN-R в Portainer

Установка PLAN-R (Windows)

1. Скачать и установить Docker Desktop следуя инструкциям по ссылке https://docs.docker.com/desktop/install/windows-install
2. Создать директорию для развертывания, например С:\Plan-r.
3. Скачать архив с последней версией дистрибутива.
4. Разархивировать содержимое архива в директорию С:\Plan-r с помощью специальных программ-архиваторов например WinRar. Во время разархивации программа должна запросить пароль (пароль можно получить через запрос в службу поддержки support@dppm.pro).
5. Запустить консоль PowerShell от имени администратора и выполнить следующие команды:
   • cd C:\Plan-r \planr-r _ <_version_>\images
   • Get-ChildItem .\ *.tar | foreach {docker load --input $ _.FullName}

Загрузка образов системы в Docker

6. Перейти в директорию C:\Plan-r \planr_<version>\planr. Сконфигурировать систему путём изменения файла с переменными среды .env под свои нужды (8.4 Конфигурирование системы). Запустить PLAN-R следующей командой.

• cd C:\PLAN-R\planr_403.0\planr\
• docker compose --env-file ./.env -p "planr" up -d

Старт приложения PLAN-R

7. Зайти в приложение Docker Desktop и убедится, что всё работает корректно.

Работающее приложение PLAN-R

Обновление системы

Подготовка к обновлению системы

1. Перед проведением обновления системы, рекомендуется выполнить резервное копирование (см. п. 8.4.2.1 Создание бэкапа базы данных перед обновлением)
2. Перейти в папку разворота системы по умолчанию /opt/dppm/planr. Остановить систему, сделать бэкап текущей конфигурации PLAN-R, перенеся текущий каталог разворота в каталог /opt/dppm/planr_old/planr

• cd /opt/dppm/planr
• ./stop.sh
• mv /opt/dppm/planr/planr opt/dppm/planr_old/ planr

Бэкапирование предыдущих настроек

3. Переместите скачанный дистрибутив в каталог /opt/dppm/distr/

• $ mv <path_to_distr> /planr_ <version>.zip /opt/dppm/distr/
• $ cd /opt/dppm/distr
• $ ls -lha

Перемещение скачанного архива в каталог

4. Извлеките файлы из архива в каталог /opt/dppm, выполнив команды в соответствующем порядке (пароль можно получить по запросу на почту support@dppm.pro)

• unzip -P <password> /opt/dppm/distr/planr_<version>.zip -d /opt/dppm/
• ls -lha

Извлечение файлов приложения из архива

5. После распаковки архива переходим в директорию ./images для загрузки docker образов командой ./load.sh. После успешной загрузки образов каталог ./images можно удалить.

• cd /opt/dppm/images_<version>
• ./load.sh

Распаковка образов PLAN-R

Обновление системы PLAN-R (Linux)

1. Выполняем подготовку к обновлению системы (8.3.2 Обновление системы PLAN-R (Linux))
2. Выполняем слияние актуального файла конфигурации .env и файла конфигурации созданного ранее (находящегося в директории /opt/dppm/planrold/planr_ <_version>). Вносим необходимые изменения в переменные среды если требуется (8.4 Конфигурирование системы)
3. Запускаем систему командой ./start.sh

Успешный старт системы

Обновление PLAN-R в Portaiener

1. Выполняем подготовку к обновлению системы (см. п. 8.4.2.1 Создание бэкапа базы данных перед обновлением).
2. Вставляем содержимое актуального файла docker-compose.yml из архива с актуальной версией в окошко (1)

Обновление файла конфигурации docker-compose.yaml в Portainer

3. Выполняем слияние актуального файла конфигурации .env, находящегося в поле Environment variables.. Вносим необходимые изменения в переменные среды если требуется (8.4 Конфигурирование системы)
4. Выполняем обновление нажав кнопку Update the stack (1).

Кнопка обновления стака в Portainer

Конфигурирование системы

Переменные среды

Файл переменных среды. env (Environment variables если используется Portainer) содержит в себе все настройки системы, которые применяются при старте. После изменения файла с переменными среды, для применения настроек, нужно выполнить ./start.sh для вступления изменений в силу. Описание всех переменных среды приведено в таблице ниже.

Таблица 4. Описание значений переменной COMPOSE_PROFILES

Для контроля запуска нужных сервисов используется переменная COMPOSE_PROFILES (https://docs.docker.com/compose/profiles/).

Например, если планируется использовать внешнюю базу данных, то её профиль необходимо исключить, тогда переменная примет следующие значения

• COMPOSE_PROFILES=main,redis,rabbitmq,logging

Описание доступных профилей для старта указано в следующей таблице.

Таблица 5. Значение переменной COMPOSE_PROFILES

Настройка бэкапов системы

Создание бэкапа базы данных перед обновлением

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

• Создание бэкапа с помощью скрипта ./dump.sh входящим в комплект поставки Для этого выполните скрипт dump.sh. Данный скрип создаст бэкап базы данных на текущий момент в директории /opt/dppm/postgres_dump
  • ./dump.sh -p /opt/dppm/postgres_dump

Создание бэкапа базы данных перед обновлением

• Создание бэкапа встроенными средствами Для этого переходим в директорию /opt/dppm/postges_dump (создаём, если её не существует) и выполняем следующую команду.
  • docker exec postgres /bin/bash -c "export PGPASSWORD=planr && pg_dump -U planr planr" | gzip -9 > planr_latest.sql.gz
  • ls -lha

Создание бэкапа базы данных перед обновлением

Настройка бэкапов по расписанию

Для созданию бэкапов по расписанию необходимо добавить скрипт dump.sh в таблицу исполнения скриптов по расписанию crontab. Параметры запуска скрипта можно посмотреть, выполнив ./dump.sh -h.

Параметры запуска скрипта dump.sh

Пример использования скрипта в crontab приведен ниже. В данном случае скрипт выполняется каждую ночь в 3:00, делает бэкап в директорию /opt/dppm/postgres_dump/ с периодом ротации 14 (Это означает что в папке всегда будет хранится 14 актуальных бэкапов) и количеством файлов, которые не удалятся в любом случаи – 5.

Исполнение скрипта по расписанию

Восстановление базы данных из бэкапа

Для восстановления базы данных из бэкапа используем скрипт ./restore.sh. Пример использования скрипта по восстановлению базы данных из бэкапа представлен на рисунке ниже.

Восстановление базы из файла бэкапа

Способы аутентификации

Настройка аутентификации через OIDC на примере keycloack

Настройка интеграции с OIDC провайдерами настраивается с помощью переменных среды в файле ./planr/.env. Описание необходимы переменных среды можно найти в таблице (см. Таблица 4. Описание значений переменной COMPOSE_PROFILES )

Заходим в keyclocak, создаём новый realm с именем Planr, либо используем уже существующий. Переходим в созданный или существующий Realm, нажимаем “Realm setting” и скачиваем файл “OpenID Endpoint Configuration”.

Скачивание файла OpenID Endpoint Configuration

Переходим во вкладку “Clients” и создаем клиента. Во вкладке Capability Setting обязательно включить “Client authentication”. В вкладке “Login Settings” обязательно указать Valid redirect URLs (тут нужно указать FQDN хоста, на котором развернут PLAN-R, например https://PLAN-R.ru/*).

Создание клиента для Planr realm

Включение Client authentication

Указание Valid redirect URLs

Переходим к настройкам переменных среды в файле ./planr/.env. Открываем ранее скачанный файл OpenID Endpoint Configuration.json (справа на скриншоте) и сопоставляем данные для авторизации с переменными среды. Значение переменной OPENDID_CLIENTID и OPENID_CLIENTSECRET можно взять из Keycloak, перейдя в нужный Realm, далее открыть созданного ранее клиента planr и перейти на вкладку “Сredentials”. Переменная OPENID_CALLBACKURL должна содержать FQDN хоста, на котором развернут PLAN-R в формате http://PLANR-HOST/api/v1/auth/openid.

После сохранения настроек применить изменения командой ./start.sh

Настройка переменных среды для для авторизации через OIDC

Если все настроено правильно при входе должна появиться иконка OpenID.

Кнопка OpenID.

Настройка SSO Kerberos

Для включения SSO авторизации Kerberos нужно выполнить следующие условия:

• KERBEROS_ENABLED=true (включение доступной стратегии авторизации kerberos)
• KERBEROS_CONF_PATH=/etc/krb5.conf (абсолютный или относительный путь к файлу конфигурации krb5.conf)
• KERBEROS_KEYTAB_PATH=/etc/krb5_multi.keytab (абсолютный или относительный путь к keytab файлу (ссылка генерация keytab файла)).
• COMPOSE_PROFILES=all,kerberos (добавить профиль kerberos для запуска необходимого сервиса для авторизации).
• Убедится, что в DNS существует A и RTP запись для сервера, где будет расположен PLAN-R
• Настроить браузеры для SSO

При соблюдении всех условий при авторизации должна появится кнопка “kerberos”, при нажатии на которую происходит аутентификация по сеансу операционной системы.

Кнопка аунтификации по сеансу операционной системы

Генерация keytab файла

SPN (Service Principal Name) — уникальный идентификатор экземпляра сервиса. SPN используется аутентификацией Kerberos для сопоставления экземпляра сервиса с учетной записью сервиса (service logon account). Это позволяет клиентским приложением аутентифицироваться в роли сервиса, даже не зная имени пользователя.

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

Когда клиент хочет воспользоваться сервисом, он находит экземпляр сервиса и составляет SPN для этого экземпляра, далее использует этот SPN для аутентификации.

Keytab-файл — это файл, содержащий пары Kerberos принципалов и их ключей (полученных с использованием Kerberos пароля). Эти файлы используются для аутентификации в системах, использующих Kerberos, без ввода пароля. Если пароль принципала изменится, то keytab-файл необходимо будет сгенерировать заново.

Windows DC

1. Создание пользователя для привязки SPN (Необходимо запретить смену пароля и не ограничивать его срок действия, иначе придётся перегенерировать keytab-файл)

Создание пользователя на windows DC

2. В командной строке доменного контролера выполнить привязку SPN к учётной записи

• setspn -A HTTP/plan-r.ru planr-sso

Привязка SPN к созаной учетной записи

3. Создание и привязка keytab файла происходит с помощью следующей команды где:

• ktpass -princ HTTP/plan-r.ru@IV.DP.RU -mapuser planr-sso -pass Pa$$word -ptype KRB5_NT_PRINCIPAL -out C:\planr.keytab

где:

• -princ — имя принципала, содержащее SPN и Kerberos-область (realm);
• -mapuser — пользователь, к которому привязывается SPN;
• -pass — пароль пользователя;
• -ptype — указывает тип принципала (рекомендуется KRB5_NT_PRINCIPAL);
• -out — путь и имя генерируемого файла.

Создание Keytab файла

4. Заходим в оснастку ADUC и убеждаемся, что для созданной учетной записи “User logon name” сменилось на имя привязанной SPN. Включена поддержка 128 и 256 битного шифрования для Kerberos.

Проверка учетной записи

Samba DC

1. Создание пользователя для привязки SPN к пользователю.

• samba-tool user create --random-password planr-sso
• samba-tool user setexpiry planr-sso –noexpiry
• samba-tool spn add HTTP/plan-r.ru planr-sso

Создание и привязка SPN к пользователю

2. Генерируем keytab файл с помощью следующей команды.

Генерация keytab фалйла для samba DC

3. Перенести файл на сервер и указать путь к нему с помощью переменной KERBEROS_KEYTAB_PATH

Установка PLAN-R в Kubernetes (preview)

Установка в кластер осуществляется путем установки helm chart в кластер при помощи утилиты helm (https://helm.sh/docs/intro/install/).

Ограничения:

• Не настроена централизованная система сбора логов.
• Не реализована поддержка SSO Kerberos.

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

• Postgresql
• Rabbitmq
• Redis

Получение образов системы

Перед установкой необходимо перенести образы из полученного архива в приватный Container registry, с которого в последующим будет осуществляется загрузка образов в Kubernetes кластер.

1. По полученной ссылке (см. п. 8.1 Получение архива дистрибутива системы) скачиваем архив и распаковываем его на любой сервере, имеющем доступ к Container registry и установленным docker для загрузки образов.
2. Выполняем авторизацию в приватном Container Registry выполнив docker login <your.private.registry>.

Выполнение авторизации в приватном репозитории

3. В разархивированном дистрибутиве переходим в директорию images и выполняем скрипт push-to-registry.sh с аргументом -r <your.private.registry>. (также можно указать <your.private.registry>/dppm/ в качестве префикса, тогда все загруженные образы будут доступны по пути <your.private.registry>/dppm/). Данный скрипт выполняет загрузку всех образов из директории images. Eсли какие-либо образа не должны быть загружены в приватный репозиторий, из директории ./images их необходимо удалить.

Загрузка образов в приватный репозиторий

4. При установки helm chart обязательно указать global.imageRegistry: <your.image.registry> либо image.registry: <your.image.registry>

Установка PLAN-R helm chart

1. Переходим в полученный разархивированный дистрибутив. Перед установкой убеждаемся, что установлен helm и есть подключение к нужному кластеру.

Проверка доступности Kubernetes кластера

2. Записываем значения параметров по умолчанию planr-values.yaml для последующей их кастомизации.

• helm show values planr-0.1.0.tgz > planr-values.yaml

3. Редактируем необходимые значения в planr-values.yaml. Описание параметров helm chart (см. в п. 8.5.3 Параметры PLAN-R helm chart).
4. Выполняем установку (рекомендуется заранее создать отдельное пространство имён, либо создать его во время установки добавив аргумент --create-namespace planr):

• helm install planr plan-r-0.1.0.tgz -f planr-values.yaml --namespace planr

Параметры PLAN-R helm chart

• Helm chart содержит в себе 3 sub-charts (PostgreSql, RabbitMq, Redis). Полное описание параметров можно найти по следующим ссылкам:

https://artifacthub.io/packages/helm/bitnami/postgresql/11.9.13

https://artifacthub.io/packages/helm/bitnami/redis/16.13.2

https://artifacthub.io/packages/helm/bitnami/rabbitmq/11.16.2

Если планируется использовать уже развернутые решения, деплой sub-charts можно отключить следующими параметрами. В данном случаи в секции planrConfig.secrets, необходимо указать строки для подключения к уже развернутым сервисам.

• postgresql.enable: false
• rabbitmq.enable: false
• redis.enable: false

В следующей таблице представлены все параметры, используемые при установке helm chart.

Таблица 6. Параметры, используемые при установке helm chart