Установка IVA One

Выбор способа загрузки дистрибутива

Выбор способа загрузки дистрибутива зависит от сетевой доступности контура, в котором развертывается IVA One.

Варианты сетевой доступности:

серверы IVA One не имеют доступа к сети Интернет

По порту 433 TCP / HTTPS отсутствует доступ к публичному репозиторию контейнеров компании IVA Technologies
- если доступен собственный централизованный сервер реестра образов контейнеров, например, Harbor и т. п., то на локальном сервере реестра необходимо создать копию публичного репозитория контейнеров компании IVA Technologies с дистрибутивом IVA One — скопировать с registry.iva-uc.ru или загрузить из архива для офлайн-установки
  
  При развертывании IVA One образы контейнеров будут загружаться с локального сервера реестра
- если недоступен централизованный сервер реестра
  - на каждый сервер кластера IVA One загрузить архив, предназначенный для офлайн-установки
  - загрузить образы контейнеров в окружение Kubernetes
серверы IVA One имеют постоянный доступ к сети Интернет

По порту 433 TCP / HTTPS присутствует доступ к публичному репозиторию контейнеров компании IVA Technologies

При развертывании IVA One образы контейнеров автоматически загружаются с сервера реестра контейнеров registry.iva-uc.ru.

Ознакомиться с требованиями к объему свободного места на жестких дисках, необходимого для размещения архивов и образов контейнеров IVA One, можно в соответствующем разделе

Управление развертыванием из helm-чарта iva-one-helm-chart-X.Y.Z.tgz может выполняться:

на любом сервере кластера IVA One (с предварительно установленным менеджером пакетов Helm)
на специальном управляющем сервере, если такой уже присутствует в инфраструктуре

Загрузка архива helm-чарта

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

загрузить установочный архив iva-one-helm-chart-X.Y.Z.tgz на хост-машину в домашнюю директорию
создать директорию для установки 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-helm-chart-X.Y.Z.tgz -C /opt/iva/iva-one --strip-components=1
```

скопировать файл values.yaml в директорию /opt/iva:

sudo cp -n /opt/iva/iva-one/values.yaml /opt/iva/values.yaml

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

Онлайн-загрузка дистрибутива из централизованного сервера реестра образов контейнеров

Для онлайн-загрузки дистрибутива необходимо предоставить доступ либо к публичному репозиторию контейнеров компании IVA Technologies, либо к собственному серверу реестра образов контейнеров в сети клиента.

При загрузке дистрибутива из публичного репозитория контейнеров компании IVA Technologies проведение каких-либо дополнительных настроек не требуется, кроме возможной необходимости в настройке прокси-сервера в ОС.

При загрузке с сервера реестра образов контейнеров клиента необходимо указать адрес данного сервера в перечне файлов values.yaml вместо адреса публичного репозитория контейнеров компании IVA Technologies — registry.iva-uc.ru. Файлы расположены в каталоге /opt/iva/iva-one/charts.

Перечень файлов values.yaml в котором необходимо провести изменения:

address-book/values.yaml
admin-api-gateway/values.yaml
admin-web/values.yaml
api-gateway/values.yaml
calls/values.yaml
chats/values.yaml
diskstorage/values.yaml
federation-gateway/values.yaml
id/values.yaml
link-adapter/values.yaml
link-notifications/values.yaml
mail/values.yaml
mail-adapter/values.yaml
profiles/values.yaml
web/values.yaml

Офлайн-загрузка дистрибутива в файловую систему

Выполняется если централизованный сервер реестра образов контейнеров недоступен

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

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

загрузить установочный архив iva-one-images-offline-X.Y.Z.tar.gz на хост-машину в домашнюю директорию

распаковать архив и загрузить контейнеры из архива в окружение k3s с помощью команды:

gunzip iva-one-images-offline-X.Y.Z.tar.gz
sudo ctr --address /run/k3s/containerd/containerd.sock -n=k8s.io images import iva-one-images-offline-X.Y.Z.tar.gz

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

sudo crictl images

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

IMAGE                                                    TAG                            IMAGE ID            SIZE
.....
registry.iva-uc.ru/iva/core/federation-gateway           v0.2.2                         3da3d0cc1efe9       11MB
registry.iva-uc.ru/iva/core/id                           v0.26.8                        934ac114e3344       252MB
registry.iva-uc.ru/iva/core/link-adapter                 v0.8.1                         f82c6ef06b519       9.44MB
registry.iva-uc.ru/iva/core/link-notifications           v0.18.1                        e70a5a2f5231a       14.5MB
registry.iva-uc.ru/iva/diskstorage                       2.5.5                          defb2fc54f42e       574MB
registry.iva-uc.ru/iva/one/admin-api-gateway             v1.3.3                         f483e4c65105b       18.8MB
registry.iva-uc.ru/iva/one/admin-web                     v2.0.2                         6978e47a4e65e       25MB
registry.iva-uc.ru/iva/one/api-gateway                   v0.46.4                        054728375d2ef       10.2MB
registry.iva-uc.ru/iva/one/calls                         v0.47.0                        0359afda03a41       10.3MB
registry.iva-uc.ru/iva/one/chats                         v0.91.0                        7eb28393969b4       17.4MB
registry.iva-uc.ru/iva/one/profiles                      v0.65.0                        797f24cf1f89a       11.1MB
registry.iva-uc.ru/iva/one/web                           v1.2.2                         f0a769dd2559b       78.4MB
.....

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

При использовании внешнего прокси-сервера, содержимое файла 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

Установка cert-manager

Cert-manager устанавливается только в случае, если в инфраструктуре Kubernetes отсутствует собственный cert-manager, например, для отдельного пилотного развертывания Kubernetes.

При использовании Kubernetes клиента, штатный cert-manager в большинстве случаев уже присутствует, и шаг установки cert-manager можно пропустить

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

sudo kubectl apply -f /opt/iva/iva-one/deps/cert-manager.crds.yaml
sudo helm install cert-manager `ls /opt/iva/iva-one/deps/cert*.tgz` --namespace cert-manager --create-namespace

Создание секретов для сертификатов

Секрет — это специальный объект в Kubernetes, предназначенный для безопасного хранения конфиденциальной информации

Для корректной работы системы необходимы валидные сертификаты
(Подробнее — см. Требования)

Секреты для внешних HTTPS-соединений к IVA One

Для создания секретов необходимо скопировать сертификаты в домашнюю директорию и создать секреты для IVA ID и IVA One.

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

скопировать сертификаты в домашнюю директорию

удалить существующий секрет IVA ID (при его наличии) и создать новый с помощью команд:

sudo kubectl delete secret iva-id-tls-secret --ignore-not-found
sudo kubectl create secret tls iva-id-tls-secret --cert=tls.crt --key=tls.key --namespace=<IVA_NAMESPACE>

удалить существующий секрет IVA One (при его наличии) и создать новый с помощью команд:
```
sudo kubectl delete secret iva-one-tls-secret --ignore-not-found
sudo kubectl create secret tls iva-one-tls-secret --cert=tls.crt --key=tls.key --namespace=<IVA_NAMESPACE>
```
где:
- iva-id-tls-secret, iva-one-tls-secret — фиксированные наименования секретов, используемые в настройках в values.yaml helm-чарта
- tls.crt, tls.key — наименования файлов сертификатов (могут быть произвольными)
- <IVA_NAMESPACE> — имя целевого пространства (namespace) IVA One в Kubernetes, если оно отличается от имени по умолчанию (default)

Если для внешних HTTPS-соединений используются сертификаты, выпущенные недоверенным центром, то необходимо:

создать секрет с сертификатом недоверенного центра:
```
sudo kubectl delete secret myiva-ca-secret -n default --ignore-not-found
sudo kubectl create secret generic myiva-ca-secret -n default --from-file=ca.crt=rootCA.crt
```
где:
- myiva-ca-secret — имя секрета корневого сертификата
- rootCA.crt — файл сертификата недоверенного центра
создать секреты iva-id-tls-secret, iva-one-tls-secret для доступа к IVA One и IVA ID:
- создать цепочку сертификатов:
  cat tls.crt rootCA.crt > chain.crt
  где chain.crt — файл с цепочкой сертификатов
- удалить существующий секрет IVA ID (при его наличии) и создать новый с помощью команд:
  sudo kubectl delete secret iva-id-tls-secret --ignore-not-found sudo kubectl create secret tls iva-id-tls-secret --cert=chain.crt --key=tls.key --namespace=<IVA_NAMESPACE>
- удалить существующий секрет IVA One (при его наличии) и создать новый с помощью команд:
  sudo kubectl delete secret iva-one-tls-secret --ignore-not-found sudo kubectl create secret tls iva-one-tls-secret --cert=chain.crt --key=tls.key --namespace=<IVA_NAMESPACE>
добавить сертификат корневого недоверенного центра в хранилище доверенных сертификатов на клиентских местах

Настройка helm-чарта для установки IVA One

Архив helm-чарта распаковывается в отдельную директорию /opt/iva/iva-one.
Другие файлы или папки в данную директорию помещать нельзя.

Все дальнейшие действия по настройке выполняются в директории /opt/iva

Для корректной установки IVA One в файле /opt/iva/values.yaml необходимо указать основные параметры развертывания клиента iva-one, выполнив следующие действия:

Если для клиентского доступа используются прокси-серверы или внутренняя сеть Kubernetes имеет нестандартное адресное пространство, отличное от 10.42.0.0/16, то необходимо ознакомиться с разделом по настройке параметра развертывания trustedProxies

открыть файл /opt/iva/values.yaml с помощью команды:
```
sudo nano /opt/iva/values.yaml
```

указать параметры развертывания в секции iva

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

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 [mycompany-ca-truststore]
  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>"

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

Доменное имя является веб-адресом сервера
строка url — указать URL для доступа клиентов
строка authCookieDomain — указать домен второго уровня для domain

где:
- <IVA_ID_DOMAIN> — доменное имя IVA ID, например, id.example.ru
- <IVA_ONE_DOMAIN> — доменное имя IVA One, например, one.example.ru
- <IVA_ONE_ADMIN_DOMAIN> — доменное имя панели администрирования IVA One, например, admin.example.ru
- <SLD_IVA_DOMAIN> — наименование домена второго уровня указанного в строке domain, например, example.ru

строка trustedCaSecrets — список имен секретов для корневых центров сертификации, по умолчанию mycompany-ca-truststore

Если секретов несколько, то указать названия через запятую (,)

Если для клиентских HTTPS-соединений используются сертификаты, выпущенные недоверенным центром, то необходимо добавить секрет корневого сертификата в доверенное хранилище IVA One:

defaults: &defaults
  trustedCaSecrets: &trusted_ca_secrets
    - iva-selfsigned-ca-secret
    - myiva-ca-secret

где myiva-ca-secret — имя секрета корневого сертификата, созданного на предыдущем шаге

В обязательном порядке необходимо указать &trusted_ca_secrets

Процесс установки IVA One

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

перейти в директорию /opt/iva:
```
cd /opt/iva
```

запустить процесс установки из директории /opt/iva, выполнив команду:

sudo helm upgrade --install iva-one ./iva-one -f values.yaml

Пример вывода при успешной установке helm-чартов:

Release "iva-one" does not exist. Installing it now.
NAME: iva-one
LAST DEPLOYED: Wed Jul 16 11:30:38 2025
NAMESPACE: default
STATUS: deployed
REVISION: 1
TEST SUITE: None

При необходимости можно указать наименование целевого пространства (namespace) с помощью команды:

sudo helm upgrade --install iva-one /opt/iva/iva-one -f /opt/iva/values.yaml --namespace <IVA_NAMESPACE>

где <IVA_NAMESPACE> — наименование целевого пространства IVA One в Kubernetes.

Для сохранения манифестов и включения режима отладки без запуска helm-чартов необходимо воспользоваться командой:

sudo helm upgrade --install iva-one /opt/iva/iva-one -f /opt/iva/values.yaml --namespace default --dry-run --debug > ~/dry-run-output.yaml

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

sudo kubectl get po -A
sudo crictl ps -a
sudo watch kubectl get po -A

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

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

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

Дополнительная информация:

подробная информация о статусе подов:
```
sudo kubectl get all -A
```

подробная информация о поде:

sudo kubectl describe po <POD_NAME> [-n <IVA_NAMESPACE>]

журнал работы пода (логи):
```
sudo kubectl logs <POD_NAME> [-n <IVA_NAMESPACE>]
```
где:
- <POD_NAME> — имя пода
- <IVA_NAMESPACE> — имя целевого пространства IVA ONE (namespace) в Kubernetes. Если имя namespace не задано, то используется имя, установленное по умолчанию — default

Все изменения настроек в файле values.yaml и обновление модулей системы выполняются поверх существующей конфигурации с помощью следующей команды (запуск из директории /opt/iva):

sudo helm upgrade iva-one ./iva-one -f values.yaml

Создание постоянной учетной записи Администратора IVA ID

При развертывании IVA ID автоматически создается учетная запись временного Администратора IVA ID.

Учетные данные по умолчанию

логин: admin
пароль: admin

Учетная запись Администратора IVA ID необходима для входа в панель администрирования IVA ID.

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

войти в панель администрирования IVA ID по адресу https://<IVA_ID_DOMAIN>/admin (где <IVA_ID_DOMAIN> — доменное имя IVA ID)

Если войти в панель администрирования IVA ID не получается, то необходимо проверить наличие доменных имен с IP-адресами серверов IVA One и IVA ID в файле /etc/hosts.
Если данные в файле отсутствуют, то их необходимо добавить в следующем формате:

<IP_ADDRESS>  <IVA_ID_DOMAIN> <IVA_ONE_DOMAIN>

где:

<IP_ADDRESS> — IP-адрес сервера, на котором развернуты IVA ID и IVA One
<IVA_ID_DOMAIN> — доменное имя IVA ID
<IVA_ONE_DOMAIN> — доменное имя IVA One

Пример:

10.0.206.116   id.example.ru one.example.ru

выбрать пространство (realm) IVA ID master
перейти во вкладку Users / Пользователи и нажать кнопку Add user
указать логин для создаваемой постоянной учетной записи Администратора в следующей строке:
- Username / Имя пользователя (обязательный параметр) — логин Администратора, используемый в сервисах IVA One
сохранить введенные данные, нажав кнопку Create / Создать
перейти во вкладку Credentials / Учетные данные и создать постоянный пароль для учетной записи Администратора:
- нажать кнопку Set password
- в поле Password ввести пароль
- в поле Password confirmation повторить введенный пароль
- переключатель Temporary перевести в положение Off
- сохранить новый пароль, нажав кнопку Save
- подтвердить установление нового пароля, нажав кнопку Save password
перейти во вкладку Role mapping и нажать кнопку Assign role
отфильтровать список по Filter by realm roles и выбрать роль admin
сохранить выбор, нажав кнопку Assign
удалить временную учетную запись Администратора (созданную по умолчанию):
- перейти во вкладку Users
- выбрать временную учетную запись Администратора (созданную по умолчанию)
- нажать кнопку и выбрать Delete
- подтвердить удаление, нажав кнопку Delete

Секрет для клиента IVA One

В панели администрирования IVA ID необходимо задать секрет для клиента iva-one:

войти в панель администрирования IVA ID по адресу https://<IVA_ID_DOMAIN>/admin (где <IVA_ID_DOMAIN> — доменное имя IVA ID)
выбрать пространство (realm) IVA ID IVA
перейти во вкладку Clients и выбрать клиента iva-one
перейти во вкладку Credentials
сгенерировать новый секрет клиента в строке Client Secret, нажав кнопку Regenerate
скопировать новый сгенерированный секрет клиента

Скопированный секрет можно указать в файле конфигурации values.yaml или хранить внутри секрета Kubernetes:
- указание секрета в файле конфигурации values.yaml:
  - открыть файл конфигурации values.yaml любым редактором (например nano), выполнив команду:
    
    sudo nano /opt/iva/values.yaml
  - вставить скопированный секрет в поле secret:
    
    Пример:
    
    iva: one: domain: &iva_one_domain "<IVA_ONE_DOMAIN>" url: &iva_one_url "https://<IVA_ONE_DOMAIN>" id: secretName: &iva_one_id_secret_name "" secret: "<CLIENT_SECRET>"
    
    где:
    
    <IVA_ONE_DOMAIN> — доменное имя IVA One, например one.example.ru
    
    <CLIENT_SECRET> — скопированный секрет клиента (пример секрета: DSNKys16Dhfvwog5ivBh5FhT0TU61YEi)
- хранение в секрете Kubernetes:
  - создать секрет и присвоить ему имя с помощью команды:
    
    sudo kubectl create secret generic <KUBERNETES_SECRET_NAME> -n default \ --from-literal=secret="<CLIENT_SECRET>"
    
    где:
    
    <KUBERNETES_SECRET_NAME> — присваиваемое имя создаваемого секрета, например iva-one-id-secret-new
    
    <CLIENT_SECRET> — скопированный секрет клиента (пример секрета: DSNKys16Dhfvwog5ivBh5FhT0TU61YEi)
  - открыть файл конфигурации values.yaml любым редактором (например nano), выполнив команду:
    
    sudo nano /opt/iva/values.yaml
  - вставить имя секрета, созданного Kubernetes, в поле secretName: &iva_one_id_secret_name:
    
    Пример:
    
    iva: one: domain: &iva_one_domain "<IVA_ONE_DOMAIN>" url: &iva_one_url "https://<IVA_ONE_DOMAIN>" id: secretName: &iva_one_id_secret_name "<KUBERNETES_SECRET_NAME>" secret: ""
    
    где:
    
    <IVA_ONE_DOMAIN> — доменное имя IVA One, например one.example.ru
    
    <KUBERNETES_SECRET_NAME> — имя секрета, созданного в Kubernetes
применить обновленную конфигурацию файла values.yaml, выполнив команду:
```
sudo helm upgrade iva-one /opt/iva/iva-one -f /opt/iva/values.yaml
```

Подключение к панели администрирования IVA One

В панели администрирования IVA ID необходимо создать пользователя для подключения к панели администрирования IVA One:

войти в панель администрирования IVA ID по адресу https://<IVA_ID_DOMAIN>/admin (где <IVA_ID_DOMAIN> — доменное имя IVA ID)
выбрать пространство (realm) IVA ID IVA
перейти во вкладку Users / Пользователи и нажать кнопку Add user
указать логин пользователя в следующей строке:
- Username / Имя пользователя (обязательный параметр) — логин пользователя, используемый в панели администрирования IVA One
сохранить введенные данные, нажав кнопку Create / Создать
перейти во вкладку Credentials / Учетные данные и создать пароль для учетной записи создаваемого пользователя:
- нажать кнопку Set password
- в поле Password ввести пароль
- в поле Password confirmation повторить введенный пароль
- переключатель Temporary перевести в положение Off
- сохранить новый пароль, нажав кнопку Save
- подтвердить установление нового пароля, нажав кнопку Save password
перейти во вкладку Role mapping и нажать кнопку Assign role
отфильтровать список по Filter by realm roles и выбрать роль iva-admin
сохранить выбор, нажав кнопку Assign

После создания пользователя и назначения ему роли, необходимо войти в панель администрирования IVA One по адресу https://<IVA_ONE_ADMIN_DOMAIN> (где <IVA_ONE_ADMIN_DOMAIN> — доменное имя панели администрирования IVA One) и аутентифицироваться с данными ранее созданного пользователя

Если в браузере при открытии отображается белая страница, то необходимо удалить файлы cookie (куки) для домена IVA One

Управление IVA One в инфраструктуре k3s

Для управления и отладки IVA One в окружении k3s рекомендуется использовать программное обеспечение Lens.

Для подключения Lens к k3s необходимо выполнить следующие действия:

на сервере IVA One выполнить команду cat и скопировать ее вывод:
```
cat ~/.kube/config
```
добавить новое подключение к Kubernetes в Lens:

Navigator → Kubernetes Clusters → Local Kubeconfigs → Add kubeconfigs → Paste
вставить скопированный вывод команды cat в конфигурацию Lens
исправить в конфигурации IP-адрес в строке server для доступа к Kubernetes
применить изменения, нажав кнопку Add Clusters

Базовая диагностика IVA One

Некорректная распаковка образов контейнеров

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

df -h

Свободного дискового пространства должно быть достаточно, чтобы после распаковки образов контейнеров его оставалось не менее 15 % от общего размера дискового пространства.

Общее количество дискового пространства должно соответствовать требованиям к параметрам серверов.

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

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

убедиться, что физический сервер / платформа виртуализации соответствуют минимальным аппаратным требованиям для развертывания системы
проверить логи работы подов и задач:
```
sudo kubectl describe job
sudo kubectl logs <POD_NAME>
```
где <POD_NAME> — имя пода
убедиться, что на проблемной и рабочей системах совпадают версии, ID и размеры загруженных образов контейнеров:
```
sudo crictl images
```
проверить статус развертывания pod (статус подов), выполнив команду:
```
sudo crictl ps
```
проверить отображение образов контейнеров и событий кластера в Kubernetes, с помощью команд:
```
sudo crictl images
sudo kubectl get events
```

Журнал диагностики

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

iva-eventbus-*
iva-id-0
iva-one-profiles
iva-one-api-gateway
iva-one-calls