Миграция IVA One на версию 1.1

Условия миграции

установлен IVA One версии 1.0.3
выполнена интеграция IVA One с IVA MCU
выполнена интеграция IVA One с IVA Mail

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

В IVA One версии 1.1 появился новый модуль — Панель Администрирования.
Для доступа к панели администрирования необходимо отдельное доменное имя, корректно разрешаемое в DNS

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

Дистрибутив IVA One состоит из следующих компонентов:

containers.tar — архив c контейнерами компонентов IVA One, включающий в себя основной набор сервисов приложения IVA One
iva-one.tgz — архив helm-чарта для установки и настройки компонентов IVA One

Загрузка дистрибутива производится из официального репозитория (файлового хранилища) компании IVA Technologies, либо выполняется иным способом

Загрузка дистрибутива из локального источника

Порядок выполняемых действий:

загрузить установочные образы на хост-машину в домашнюю директорию
создать директорию для установки IVA One с помощью команд:
```
sudo rm -rf /opt/iva/iva-one
sudo mkdir -p /opt/iva/iva-one
```
разархивировать архив helm-чарта в директорию /opt/iva/iva-one:
```
sudo tar xf iva-one.tgz -C /opt/iva/iva-one --strip-components=1
```

переименовать файл values.yaml предыдущей версии:
```
sudo mv /opt/iva/values.yaml /opt/iva/values.yaml.back
```
скопировать файл values.yaml из нового дистрибутива в директорию /opt/iva:
```
sudo cp -n /opt/iva/iva-one/values.yaml /opt/iva/values.yaml
```

загрузить контейнеры из архива в окружение k3s:

sudo ctr --address /run/k3s/containerd/containerd.sock -n=k8s.io images import containers.tar

В случае появления ошибок необходимо обратиться к специалистам технической поддержки компании IVA Technologies через сервисный портал

убедиться, что загруженные контейнеры стали доступны в окружении k3s:

sudo crictl images

Пример вывода:

IMAGE                                                   TAG                            IMAGE ID            SIZE
cr.fluentbit.io/fluent/fluent-bit                       4.0.7                          46f8e15ff109f       46MB
docker.hi-tech.org/iva/core/id/base                     v0.26.2                        dcff3802bd74b       282MB
docker.hi-tech.org/iva/core/id/base                     v0.26.4                        fd3dcc83c73ef       528MB
docker.hi-tech.org/iva/core/id/base                     v0.26.5                        8230bd3a7312f       288MB
docker.hi-tech.org/iva/core/id/base                     v0.26.6                        c24b1b32ff82b       528MB
docker.hi-tech.org/iva/core/link/adapter                v0.5.2                         fddf8366bae0a       12.5MB
docker.hi-tech.org/iva/core/link/adapter                v0.6.0                         a783055746d86       29.7MB
docker.hi-tech.org/iva/core/link/notifications          v0.11.6                        57558868ca57f       12MB
docker.hi-tech.org/iva/core/link/notifications          v0.13.0                        467edca9531cc       31MB
docker.hi-tech.org/iva/core/link/notifications          v0.14.0                        48ce16ee7c003       31MB
docker.hi-tech.org/iva/core/link/notifications          v0.15.0                        be070449f0ee1       31MB
docker.hi-tech.org/iva/one/backend/admin-api-gateway    v1.0.0                         fbbfc4f022bf0       36.2MB
docker.hi-tech.org/iva/one/backend/admin-api-gateway    v1.1.0                         ca73270ca27ec       36.3MB
docker.hi-tech.org/iva/one/backend/api-gateway          v0.35.5                        4460c25851b8a       13.2MB
docker.hi-tech.org/iva/one/backend/api-gateway          v0.37.0                        b5eb3b62f74bd       30.9MB
docker.hi-tech.org/iva/one/backend/api-gateway          v0.38.0                        8f6bc16b96e65       13.4MB
docker.hi-tech.org/iva/one/backend/api-gateway          v0.39.0                        c74f4c78a069e       30.9MB
docker.hi-tech.org/iva/one/backend/api-gateway          v0.40.0                        f842fbf321dcd       30.9MB
docker.hi-tech.org/iva/one/backend/call                 v0.38.2                        b99a4d16ebd40       11.2MB
docker.hi-tech.org/iva/one/backend/call                 v0.40.0                        cd6408cad983b       28.7MB
.....

настроить корректное отображения IP-адресов пользователей в окружении k3s:

При использовании внешнего прокси-сервера содержимое файла traefik-real-ip.yaml нужно изменить согласно утвержденным требованиям безопасности

sudo cp /opt/iva/iva-one/extra/traefik-real-ip.yaml /var/lib/rancher/k3s/server/manifests/traefik-real-ip.yaml

Обновление настроек values

Версия IVA One 1.1 не поддерживает автоматический перенос настроек из файла конфигурации values.yaml.
Перенос настроек необходимо выполнять вручную

Порядок выполняемых действий:

открыть файл /opt/iva/values.yaml.back с помощью команды:
```
sudo nano /opt/iva/values.yaml.back
```
скопировать значения настроек из секции iva и других модифицированных разделов файла предыдущей версии /opt/iva/values.yaml.back
открыть файл новой версии /opt/iva/iva-one/values.yaml с помощью команды:
```
sudo nano /opt/iva/iva-one/values.yaml
```

вставить скопированные значения в файл новой версии /opt/iva/iva-one/values.yaml

Пример раздела iva файла values.yaml новой версии:

В данном примере интеграция с IVA Mail не выполнена

iva:
   id:
     domain: &iva_id_domain "<IVA_ID_DOMAIN>"
     url: &iva_id_url "https://<IVA_ID_DOMAIN>"
     authCookieDomain: &iva_id_auth_cookie_domain "<SLD_IVA_DOMAIN>"
     trustedCaSecrets: &iva_id_trusted_ca_secrets []
   eventbus:
     serviceType: NodePort  # Select LoadBalancer for HA k8s cluster, otherwise you may use NodePort
     externalPort: 32222    # NodePort, may be empty for LoadBalancer
     loadBalancerIP: ""     # Optional, may be used for LoadBalancer, leave empty for auto allocation
   admin:
     domain: &iva_admin_domain "<IVA_ONE_ADMIN_DOMAIN>"
     url: &iva_admin_url "https://<IVA_ONE_ADMIN_DOMAIN>"
   one:
     domain: &iva_one_domain "<IVA_ONE_DOMAIN>"
     url: &iva_one_url "https://<IVA_ONE_DOMAIN>"
     id:
       secret: &iva_one_id_secret " <Client_Secret>"
   mail:
     enabled: &iva_mail_enabled false
     url: &iva_mail_url ""
     domains: &iva_mail_domains ""
     jump:
       username: &iva_mail_jump_username "admin"
       password: &iva_mail_jump_password "admin"
   mcu:
     url: &iva_mcu_url "<IVA_MCU_DOMAIN>"
     appId: &iva_mcu_app_id "APP_ID"
     appSecret: &iva_mcu_app_secret "APP_PASS"
     domainId: &iva_mcu_domain_id "DOMAIN_ID"

где:

строка domain — указать наименование домена:

Доменное имя является web-адресом сервера
- <IVA_ONE_ADMIN_DOMAIN> — доменное имя для доступа к панели администрирования IVA One
- <IVA_ID_DOMAIN> — доменное имя IVA ID
- <IVA_ONE_DOMAIN> — доменное имя IVA One
строка url указать URL для доступа к клиенту:
- <IVA_ID_DOMAIN> — URL для доступа к IVA ID (клиент iva-id)
- <IVA_ONE_DOMAIN> — URL для доступа к IVA One (клиент iva-one)
- <IVA_MCU_DOMAIN> — URL для доступа к IVA MCU (клиент iva-mcu)
строка authCookieDomain — указать домен второго уровня для domain:
- <SLD_IVA_DOMAIN> — наименование домена второго уровня
строка secret — указать домен второго уровня для domain:
- <Client_Secret> — сгенерированный в IVA ID секрет клиента (пример формата секрета: lKCb3o46l1FFlEMgTee5OkglO9zkk4nC)
строка appId:
- APP_ID — указать ID приложения IVA One в IVA MCU

строка appSecret:

APP_PASS — указать пароль приложения IVA One в IVA MCU

После создания интеграционного приложение IVA One пароль нельзя будет посмотреть.
В случае утери пароля, можно создать новый пароль

строка domainId:
- DOMAIN_ID — указать ID домена IVA MCU

Обновление IVA One

Порядок выполняемых действий:

запустить процесс обновления, выполнив команду:
```
sudo helm upgrade iva-one /opt/iva/iva-one -f /opt/iva/values.yaml -n <iva_namespace>
```
где <iva_namespace> — имя целевого пространства (namespace) IVA One в Kubernetes, если оно отличается от имени по умолчанию (default)
дождаться завершения обновления

Выполнение обновления может занимать длительное время

Пример вывода при успешном обновлении:
```
Release "iva-one" has been upgraded. Happy Helming!
NAME: iva-one
LAST DEPLOYED: Wed Oct 02 12:32:21 2025
NAMESPACE: default
STATUS: deployed
REVISION: 7
```

проверить статус развертывания pod (статус подов), выполнив команду:

sudo kubectl get pods

Статусы подов должны быть в состоянии Running.

Статусы подов Completed и Exited также не являются ошибкой развертывания и сообщают об успешной установке

Пример вывода:

NAME                                      READY   STATUS    RESTARTS      AGE
centrifugo-7687566f89-944gr               1/1     Running   0             20m
iva-admin-api-gateway-54cbf7cd5c-scxk6    1/1     Running   0             21m
iva-admin-web-75c59856dc-ptc6m            1/1     Running   0             21m
iva-diskstorage-74688c6498-8ldcb          1/1     Running   0             13m
iva-eventbus-0                            2/2     Running   0             31m
iva-eventbus-1                            2/2     Running   0             31m
iva-eventbus-2                            2/2     Running   0             31m
iva-eventbus-box-7db9d8687b-tf48c         1/1     Running   0             31m
iva-eventbus-operator-866cd89c9c-7br6p    1/1     Running   3 (31m ago)   31m
iva-id-0                                  1/1     Running   0             14m
iva-link-adapter-f747bddb8-wkkzl          1/1     Running   0             14m
iva-link-notifications-6c44c99448-k4lgd   1/1     Running   0             14m
iva-mail-adapter-7b8f8fb77c-5xb27         1/1     Running   13 (35m ago)  15m
iva-one-api-gateway-78847d7b59-c8qz6      1/1     Running   0             13m
iva-one-calls-57cb87696f-wnm52            1/1     Running   0             14m
iva-one-chats-55bc9496f7-6mnsh            1/1     Running   0             14m
iva-one-profiles-758b5c6c54-v84q2         1/1     Running   0             14m
iva-one-web-7d6d554669-bbxvd              1/1     Running   0             21m
ivaid-operator-69c49bc655-jwps4           1/1     Running   0             14m
minio-58dc86f4cb-2m7dl                    1/1     Running   0             31m
opensearch-0                              1/1     Running   0             31m
postgresql-0                              1/1     Running   0             22m
valkey-0                                  2/2     Running   0             22m
valkey-1                                  2/2     Running   0             22m
valkey-2                                  2/2     Running   0             22m
valkey-3                                  2/2     Running   0             22m
valkey-4                                  2/2     Running   0             22m
valkey-5                                  2/2     Running   0             22m

Ошибка пода iva-one-profiles

Если новая версия пода iva-one-profiles не запускается и находится в статусе CrashLoopBackOff, то необходимо:

получить пароль пользователя iva_user в Postgres, выполнив команду:

sudo kubectl -n default get secret iva-one-postgresql-secret -o jsonpath='{.data.password}' | base64 --decode

модифицировать таблицу в базе данных iva_one_profiles, выполнив команду:

После ввода команды необходимо подтвердить действие введением пароля пользователя iva_user в Postgres

sudo kubectl exec -it postgresql-0 -- psql -U iva_user -d iva_one_profiles -c "ALTER TABLE users DROP COLUMN verify_at; DELETE FROM goose_db_version WHERE version_id = 20250815131624;"

При использовании внешней базы данных для модификации таблицы iva_one_profiles необходимо в окне запросов базы данных выполнить команду:

"ALTER TABLE users DROP COLUMN verify_at; DELETE FROM goose_db_version WHERE version_id = 20250815131624;"

определить ID пода iva-one-profiles, выполнив команду:

sudo kubectl -n default get pods  | grep iva-one-profiles

Пример вывода:

iva-one-profiles-758b5c6c54-v84q2                0/1     CrashLoopBackOff   0 (13m ago)   13m

перезапустить под iva-one-profiles, выполнив команду:
```
sudo kubectl -n default delete pod <pod_id>
```
где <pod_id> — идентификатор пода iva-one-profiles, полученный в выводе предыдущей команды

Пример команды:
```
sudo kubectl -n default delete pod iva-one-profiles-758b5c6c54-v84q2t
```

Настройка IVA ID

Порядок выполняемых действий:

установить параметр Valid redirect URIs:
Войти в IVA ID → Нажать Manage Realms → Выбрать IVA → Перейти в раздел Clients → Выбрать iva-one → Вкладка Settings → Выбрать секцию Access settings → В строке Valid redirect URIs установить значение: * → Нажать кнопку Save
добавить роль manage-users:
Перейти в раздел Clients → Выбрать iva-one → Вкладка Service accounts roles → В выпадающем списке Assign role выбрать: Clients roles → Включить флаговую кнопку manage-users → Нажать кнопку Assign
изменить имя клиента iva-desktop (при необходимости):
Перейти в раздел Clients → Выбрать iva-desktop → Вкладка Settings → Выбрать секцию General settings → В строке Client ID установить значение: iva-one-desktop → Нажать кнопку Save
создать роль iva-admin:

Перейти в раздел Realm roles → Нажать кнопку Create role → В строке Role name установить значение: iva-admin → Нажать кнопку Save

Роль iva-admin необходима для доступа к панели администрирования IVA One
добавить пользовательский атрибут avatarFileId:

Перейти в раздел Realm settings → Вкладка User profile→ Нажать кнопку Create attribute → Выполнить следующие настройки:
- в секции General settings заполнить поле Attribute [Name]: avatarFileId
- в секции General settings поле Display Name → Нажать кнопку Add translations → Supported languages → Russian → Заполнить поле Translation: ID файла аватара → Нажать кнопку Ok
- в секции Validations → Нажать кнопку Add validator → Validator type: length → Minimum length: 0 → Maximum length: 255 → Нажать кнопку Save
- нажать кнопку Create
установить Edit mode: UNSYNCED (при интеграции IVA ID с LDAP)

Перейти в раздел User federation → Выбрать LDAP провайдера → Выбрать секцию LDAP searching and updating → В выпадающем списке Edit mode выбрать: UNSYNCED

После завершения миграции необходимо выполнить настройки согласно пункту Подключение к панели администрирования IVA One