Установка 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
.....

Установка 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, предназначенный для безопасного хранения конфиденциальной информации

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

Для создания секретов необходимо скопировать сертификаты в домашнюю директорию и создать секреты для 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)

При использовании сертификатов (tls.crt и tls.key), выпущенных недоверенным центром, необходимо:

создать секрет с сертификатом недоверенного центра:
```
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-one-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 необходимо указать основные параметры развертывания клиента iva-one, выполнив следующие действия:

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

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

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>"
  one:
    domain: &iva_one_domain "<IVA_ONE_DOMAIN>"
    url: &iva_one_url "https://<IVA_ONE_DOMAIN>"

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

Доменное имя является web-адресом сервера
- <IVA_ID_DOMAIN> — доменное имя IVA ID
- <IVA_ONE_DOMAIN> — доменное имя IVA One
  - строка url — указать URL для доступа к клиенту:
- &iva_id_url — URL для доступа к IVA ID (клиент iva-id)
- &iva_one_url — URL для доступа к IVA One (клиент iva-one)
  - строка authCookieDomain — указать домен второго уровня для domain:
- <SLD_IVA_DOMAIN> — наименование домена второго уровня

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

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

логин: 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 (Платформа 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-eventbus-*
iva-id-0
iva-one-profiles
iva-one-api-gateway
iva-one-calls