Установка IVA One

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

Дистрибутив 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 в директорию /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
docker.hi-tech.org/iva/core/id/base                   latest                 2ac7c263affb3       282MB
docker.hi-tech.org/iva/core/link/adapter              v0.5.2                 fddf8366bae0a       12.5MB
docker.hi-tech.org/iva/core/link/notifications        v0.11.5                1fc7eeb420714       12MB
docker.hi-tech.org/iva/one/backend/api-gateway        v0.35.4                287753f51aae7       13.2MB
docker.hi-tech.org/iva/one/backend/call               v0.38.2                b99a4d16ebd40       11.2MB
docker.hi-tech.org/iva/one/backend/chats              v0.75.6                811ac9e673230       14.9MB
docker.hi-tech.org/iva/one/backend/users              v0.55.5                87d7099d4bb29       12.2MB
docker.hi-tech.org/iva/one/mail-adapter               v1.2.0                 467bb6541aac2       57MB
docker.hi-tech.org/iva/one/web/iva-one                v1.0.0                 ddae1ce5dbc50       35.3MB
docker.hi-tech.org/modules/diskstorage/disk-storage   1.3.2                  57e880337a211       707MB
.....

при использовании окружения 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-tls-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>
добавить сертификат корневого недоверенного центра в хранилище доверенных сертификатов на клиентских местах

Секрет для корневого центра сертификации в IVA ID

Пункт необязателен для выполнения

К IVA ID по защищенному TLS-соединению могут быть подключены внешние сервисы (например, LDAP-каталог), использующие сертификаты, выданные сторонними корневыми центрами.
Сертификаты этих центров должны быть добавлены в хранилище корневых сертификатов IVA ID.
Каждый сертификат корневого центра хранится в своем секрете.

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

sudo kubectl create secret generic mycompany-ca-truststore -n default --from-file=ca.crt=rootCA.crt

где:

mycompany-ca-truststore — название секрета
rootCA.crt — файл с сертификатом корневого центра

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

sudo kubectl create secret generic mycompany-ca-truststore-2 -n default --from-file=ca.crt=rootCA-2.crt

где:

mycompany-ca-truststore-2 — название секрета
rootCA-2.crt — файл с сертификатом корневого центра

Секрет для прокси-сервера push-уведомлений

Пункт необязателен для выполнения

IVA One поддерживает отправку push-уведомлений через провайдеров (APNs, FCM, WebPush) с использованием корпоративного прокси-сервера. Прокси-сервер используется для всех исходящих соединений к внешним push-сервисам.

Особенности использования прокси-сервера push-уведомлений:

поддерживаются схемы http и https
поддерживается Basic Authentication (в формате http://user:pass@host:port)

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

sudo kubectl create secret generic iva-one-push-proxy -n default \
  --from-literal=url=https://<USERNAME>:<PASSWORD>@<PROXY_DOMAIN>:<PORT>

где:

iva-one-push-proxy — название секрета для хранения URL-строки подключения
<USERNAME>:<PASSWORD> — имя пользователя и пароль для аутентификации на прокси-сервере
<PROXY_DOMAIN>:<PORT> — FQDN прокси-сервера и порт подключения, например, proxy.company.com:8080

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

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

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

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

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

указать параметры развертывания:

параметр trustedProxies

Необязательный параметр

Список доверенных прокси-серверов обслуживающих клиентские соединения. IP-адреса доверенных прокси-серверов удаляются из HTTP-заголовков, в результате остается только реальный IP-адрес клиента.

Для настройки параметра trustedProxies необходимо указать адреса прокси-серверов или их подсеть:
```
presets:
  trustedProxies: &trusted_proxies ["127.0.0.1", "172.16.0.0/12"]
```
Если прокси-сервера не используются, то необходимо оставить пустой список:
```
presets:
  trustedProxies: &trusted_proxies []
```

параметры секции 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 — указать наименование домена

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

где:
- <IVA_ID_DOMAIN> — доменное имя IVA ID
- <IVA_ONE_DOMAIN> — доменное имя IVA One
- <IVA_ONE_ADMIN_DOMAIN> — доменное имя панели администрирования IVA One
- <SLD_IVA_DOMAIN> — наименование домена второго уровня

строка trustedCaSecrets — список названий секретов для корневых центров сертификации

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

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

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

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

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

прокси-сервер push-уведомлений

Необязательный параметр

Для возможности использования прокси-сервера push-уведомлений необходимо задать URL в секрете, который был указан в секрете для прокси-сервера push-уведомлений и задать значение true в секции link-notifications
```
link-notifications:
  config:
    proxy:
      enabled: true
```

Процесс установки 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_ONE_NAMESPACE>

где <IVA_ONE_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 <podname> [-n <namespace_if_not_default>]

журнал работы пода (логи):
```
sudo kubectl logs <podname> [-n <namespace_if_not_default>]
```
где:
- <podname> — имя пода
- <namespace_if_not_default> — имя целевого пространства 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.com one.example.com

выбрать пространство (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 любым редактором (например nano), выполнив команду:
```
sudo nano /opt/iva/values.yaml
```
вставить скопированный секрет в поле secret: &iva_one_id_secret:

Пример:
```
iva:
  one:
    domain: &iva_one_domain "one.example.com"  # example: one.example.com
    url: &iva_one_url "https://one.example.com"  # example: https://one.example.com
    id:
      secret: &iva_one_id_secret "<Client_Secret>"
```
где <Client_Secret> — сгенерированный в IVA ID секрет клиента (пример формата секрета: lKCb3o46l1FFlEMgTee5OkglO9zkk4nC)
применить обновленную конфигурацию файла 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 (Платформа IVA MCU, почта IVA Mail и другие сервисы).

Запросить сертификаты можно следующими командами:

sudo kubectl -n default get secret iva-mcu-eventbus-secret -o jsonpath='{.data.ca\.crt}' | base64 --decode
sudo kubectl -n default get secret iva-mcu-eventbus-secret -o jsonpath='{.data.tls\.crt}' | base64 --decode
sudo kubectl -n default get secret iva-mcu-eventbus-secret -o jsonpath='{.data.tls\.key}' | base64 --decode

Управление 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-eventbus-*
iva-id-0
iva-one-profiles
iva-one-api-gateway
iva-one-calls