На схеме ниже представлено федеративное взаимодействие пользователей из разных тенантов Федерации:
Федерация — протокол взаимодействия тенантов. Является транспортом по доставке данных между тенантами. Отвечает за проверку:
- Соответствия требованиям доверия (Трастов).
- Прав пользователей на внешнюю коммуникацию.
- Готовность сервисов к взаимодействию.
- Обеспечивает надежность и безопасность передачи данных.
Тенант — независимые части организации: отдельные инсталляции, набор доменов или пользователей. Могут находиться в одной или разных инсталляциях. Пользователи не могут взаимодействовать и коммуницировать до формирования траста между тенантами.
Инсталляция — независимые развернутые стенды разных организаций. Могут включать в себя несколько тенантов.
Траст — доверительное отношение между двумя и более тенантами. Могут быть сформированы:
- Между тенантами в разных инсталляциях On-premises.
- Между тенантами внутри одной инсталляции.
- Тенант из On-premise инсталляции с тенантом в SaaS-версии продукта.
Особенности работы Федерации:
-
Звонки между федерациями могут быть только гостевые.
-
Общение между двумя инсталляциями осуществляется по протоколу gRPC + TLS. Эндпоинт для взаимодействия в общем виде выглядит так:
federation.<домен удаленной инсталляции>:443
Схема взаимодействия между инсталляциями A и B по протоколу mTLS:
-
Для настройки Федерации вам понадобится доступ к серверу Мессенджер и ВКС и доступ к Панели администратора VK WorkSpace по адресу
https://biz.<ваш домен>. -
Для корректной работы сервиса Федерация добавьте на серверы каждой инсталляции дополнительные вычислительные ресурсы:
- 10% от имеющихся мощностей vCPU.
- 1 ГБ SSD.
- 2 ГБ RAM на каждую тысячу федеративных пользователей. Ожидаемый прирост RAM — около 1 ГБ в год в зависимости от количества сообщений Федерации.
-
Проверьте, что у всех инсталляций Федерации есть доступ друг к другу. Например, проверьте, что запрос из Инсталляции А доходит до Инсталляции В:
curl -I federation.<домен Инсталляции В>Если доступов нет, администраторам инсталляций необходимо запросить друг у друга адреса Federation Proxy и разрешить обращаться только по адресам
federation.<домен инсталляции>:443. -
Для включения mTLS на каждой инсталляции необходимо сформировать следующий набор артефактов:
- публичный сертификат СА — cacert.pem
- публичный сертификат сервера — server.cert.pem
- приватный (секретный) ключ сервера — server.key.pem
- публичный сертификат клиента — client.cert.pem
- приватный (секретный) ключ клиента — client.key.pem
Как создать сертификаты — см. в разделе ниже.
Для осуществления взаимодействия Инсталляция A должна передать публичный сертификат клиента и приватный ключ клиента Инсталляции B и наоборот.
Итого на Инсталляции A должен быть набор следующих файлов:
- публичный сертификат СА — server.cacert.pem
- публичный сертификат сервера — server.cert.pem
- приватный (секретный) ключ сервера — server.key.pem
- публичный сертификат клиента — client.cert.pem
- приватный(секретный) ключ клиента — client.key.pem
- публичный сертификат CA удаленной инсталляции, которым подписан клиент — client_B.cacert.pem
- публичный сертификат клиента от удаленной инсталляции — client_B.cert.pem
- приватный(секретный) ключ клиента от удаленной инсталляции — client_B.key.pem
Все сертификаты рекомендуется разместить в директории /opt/certs.
-
Начиная с версии Мессенджера 26.1 вы можете управлять доступами пользователей Федерации при помощи скрипта. Для этого необходимо наличие на компьютере интерпретатора языка Python версии 3.0 и выше и менеджера пакетов pip. Если версия вашей инсталляции ниже 26.1, пропустите этот шаг.
Перейдите на машину, где развернута Панель администратора VK WorkSpace и проверьте, есть ли в системе tenantID:
sudo docker exec -it bizpostgres1 psql pdd_postgres -U postgres
Если tenantID есть, в выводе команды будет:
SELECT common_tenant.tidFROM common_tenantORDER BY common_tenant.id ASCLIMIT 1;
Если ответ пустой, сгенерируйте новый tenantID, последовательно выполнив команды:
sudo docker exec -it bizf1 bash. env/bin/activate./manage.py shellfrom pdd.common.models import Tenantt = Tenant(name='test') # в параметре name укажите название вашей инсталляции на ланитинце (на свое усмотрение)t.save()print(t.tid)
После команды print(t.tid) будет вывод tenantID. Сохраните это значение, оно понадобится вам ниже.
Получите у администратора удаленной инсталляции его tenantID. Он понадобится вам ниже.
TenantID можно сгенерировать самостоятельно через кодирование домена в base58. Например, если нужно объединить домены example1.ru, example2.ru, example3.ru в один тенант:
-
Перейдите на сайт.
-
В поле Input введите короткое название тенанта (например,
corpmail). -
В поле Output отобразится tenantID (например,
HdeYhnp4L8b). Длина tenantID не должна превышать 11 символов.
-
В веб-интерфейсе установщика VK Workspace нажмите кнопку
в правом верхнем углу и выберите Продукты → Мессенджер. -
Включите переключатель Kafka Kubernetes operator.
-
Нажмите кнопку Сохранить настройки.
-
Перейдите на главную страницу веб-интерфейса установщика, нажав на логотип VK WorkSpace.
-
Выберите Kafka Kubernetes operator и распределите сервисы.

-
Запустите автоматическую установку, нажав на кнопку Play
.
Перед включением убедитесь, что у вас есть доступ до удаленной инсталляции (см. предусловия).
-
В веб-интерфейсе установщика VK Workspace нажмите кнопку
в правом верхнем углу и выберите Продукты → Мессенджер. -
Включите переключатель для Федерации.
-
Нажмите кнопку Сохранить настройки.
-
Перейдите на главную страницу веб-интерфейса установщика, нажав на логотип VK WorkSpace.
-
Нажмите кнопку Добавить → Распределение продуктов Helm.
-
В открывшейся форме укажите Кластер K8s и Namespace для Федерации.
-
Нажмите кнопку Сохранить настройки.
-
Запустите автоматическую установку, нажав на кнопку Play
.
-
В веб-интерфейсе установщика VK Workspace перейдите в Проекты → vkteams.
-
В окне Формы проекта vkteams выберите Federation (Настройка федерации). Откроется форма с параметрами для заполнения:

Заполните параметры в соответствии с таблицей:
Параметр
Действие
Примечание
Включить федерацию
Включить переключатель
Включает сервисы Федерации
Включить event manager
Включить переключатель
Включает event manager для отображения признака федеративности чатов и пользователей
grpc публичный серверный сертификат CA
Указать сертификат
В формате PEM:
-----BEGIN CERTIFICATE-----...-----END CERTIFICATE-----grpc серверный сертификат
Указать сертификат
В формате PEM:
-----BEGIN CERTIFICATE-----...-----END CERTIFICATE-----grpc приватный ключ серверного сертификата
Указать ключ
В формате PEM:
-----BEGIN PRIVATE KEY-----...-----END PRIVATE KEY-----Имя инсталляции
Указать название
Название инсталляции на латинице
-
В разделе Инстансы федерации нажмите кнопку + Добавить и заполните поля для каждой удаленной инсталляции:
Параметр
Действие
Примечание
Адрес удаленного стенда
Указать адрес удаленного стенда в формате
federation.<домен удаленной инсталляции>:443При наведении на иконку ⓘ появляется подсказка с описанием параметра
Публичный сертификат CA удаленной инсталляции, которым подписан клиент
Указать сертификат
В формате PEM:
-----BEGIN CERTIFICATE-----...-----END CERTIFICATE-----Имя удаленной инсталляции на латинице (cert_cn)
Указать название
CN из клиентского сертификата
Имя удаленной инсталляции на латинице (name)
Указать название
Название удаленной инсталляции
Публичный сертификат клиента от удаленной инсталляции
Указать сертификат
В формате PEM:
-----BEGIN CERTIFICATE-----...-----END CERTIFICATE-----Приватный (секретный) ключ клиента от удаленной инсталляции
Указать ключ
В формате PEM:
-----BEGIN RSA PRIVATE KEY-----...-----END RSA PRIVATE KEY-----tenantID удаленной инсталляции
Получить у администратора удаленной инсталляции
При наведении на иконку ⓘ появляется подсказка с описанием параметра. Кнопка +Добавить позволяет добавлять несколько tenantID
-
В дополнительных настройках укажите:
Параметр
Действие
Примечание
Локальный тенант
Указать идентификатор локального tenantID из Шага 1
При наведении на иконку ⓘ появляется подсказка с описанием параметра
message-send-api-enabled
Включить переключатель
Включает новый метод для отправки сообщений
Включить шифрование данных
Включить переключатель
Включает взаимную аутентификацию по сертификатам (mTLS)
-
Перейдите на главную страницу веб-интерфейса установщика, нажав на логотип VK WorkSpace.
-
Запустите автоматическую установку, нажав на кнопку Play
.
Для версии Мессенджера 26.2 и выше взаимодействие между инсталляциями настраивается через трасты. Порядок действий обязателен: тенанты → траст → подтверждение.
-
Добавьте тенанты. На каждой инсталляции зарегистрируйте всех участников траста: для собственного тенанта укажите
isLocal=true, для остальных —isLocal=false.curl -s -X POST "http://stentor-<hostname>/api/v1/biz/federation/tenant/add?tenant=<tenantID>&name=<имя инсталляции>&installation=<имя инсталляции>&isLocal=true"где:
tenant— tenantID тенанта;nameиinstallation— имя инсталляции;isLocal—trueдля локального тенанта,falseдля тенантов других инсталляций.
-
Проверьте, что тенанты добавлены:
curl -s "http://stentor-<hostname>/api/v1/biz/federation/tenant/list" -
Создайте траст (один раз, на любой инсталляции — она станет создателем траста):
curl -s -X POST "http://stentor-<hostname>/api/v1/biz/federation/trust/create" \-H 'Content-Type: application/x-www-form-urlencoded' \-d "creatorTenant=<tenantID создателя>" -d 'name=<имя траста>' -d "tenants=<tenantID участника>"В ответе вернется
trustIDвидаfid:150/<tenantID>/<trustID>. Сохраните его — он понадобится на следующих шагах. -
Проверьте, что траст создан:
curl -s "http://stentor-<hostname>/api/v1/biz/federation/trust/get" -
Подтвердите участие в трасте:
curl -s -X POST "http://stentor-<hostname>/api/v1/biz/federation/trust/confirm" \-H 'Content-Type: application/x-www-form-urlencoded' -d "trustID=<trustID>"На инсталляции-создателе — траст станет активным и будет отправлен на каждую инсталляцию участника траста.
На инсталляции участника — необходимо подтвердить участие в активном трасте.
-
При необходимости выйдите из траста или деактивируйте его:
curl -s -X POST "http://stentor-<hostname>/api/v1/biz/federation/trust/exit" \-H 'Content-Type: application/x-www-form-urlencoded' -d "trustID=<trustID>"На инсталляции-создателе траст будет деактивирован — федеративное взаимодействие станет недоступно всем участникам траста.
На инсталляции участника — участник выйдет из траста и прекратит федеративное взаимодействие в рамках этого траста.
-
При необходимости модифицируйте набор участников траста (доступно только создателю траста):
-
Удалите участника из траста:
curl -X POST 'https://stentor-imserver-<hostname>/api/v1/biz/federation/trust/modify' -d "trustID=<trustID>" -d "tenantsDel=<tenant>" -
Добавьте нового участника в траст:
curl -X POST 'https://stentor-<hostname>/api/v1/biz/federation/trust/modify' -d "trustID=<trustID>" -d "tenantsAdd=<tenant>"
Вновь добавленному участнику необходимо будет подтвердить участие в трасте.
-
При объединении инсталляции «на одну ВМ» и кластерной инсталляции соединение по gRPC между ними может обрываться. Для решения добавьте в конфигурацию nginx отдельный server-блок для хоста federation.<домен>:
upstream cluster-fed-4vm-2981 {server 100.70.136.109:80; # node cluster-fed-4vm-2981-standart-01server 100.70.137.112:80; # node cluster-fed-4vm-2981-standart-03server 100.70.137.86:80; # node cluster-fed-4vm-2981-standart-02server 100.70.137.91:80; # node cluster-fed-4vm-2981-standart-04}# Custom for federationserver {server_name federation.cluster-fed-4vm-2981.imdevops.ru;listen 443 http2 ssl;access_log /var/log/nginx/cluster-fed-4vm-2981.imdevops.ru-access.log;error_log /var/log/nginx/cluster-fed-4vm-2981.imdevops.ru-error.log;ssl_certificate /etc/nginx/ssl/cluster-fed-4vm-2981.imdevops.ru.crt;ssl_certificate_key /etc/nginx/ssl/cluster-fed-4vm-2981.imdevops.ru.key;location / {grpc_pass grpc://cluster-fed-4vm-2981;grpc_set_header Host $host;grpc_set_header X-Real-IP $remote_addr;grpc_set_header X-Forwarded-For $proxy_add_x_forwarded_for;grpc_set_header X-Forwarded-Proto $scheme;grpc_set_header Trailer "X-Grpc-Trailer";grpc_read_timeout 3600s;grpc_send_timeout 3600s;grpc_connect_timeout 3600s;grpc_buffer_size 16k;}}# Default configserver {server_name cluster-fed-4vm-2981.imdevops.ru *.cluster-fed-4vm-2981.imdevops.ru;listen 443 http2 ssl;access_log /var/log/nginx/cluster-fed-4vm-2981.imdevops.ru-access.log;error_log /var/log/nginx/cluster-fed-4vm-2981.imdevops.ru-error.log;ssl_certificate /etc/nginx/ssl/cluster-fed-4vm-2981.imdevops.ru.crt;ssl_certificate_key /etc/nginx/ssl/cluster-fed-4vm-2981.imdevops.ru.key;location / {proxy_pass http://cluster-fed-4vm-2981;proxy_set_header Host $host;proxy_set_header X-Real-IP $remote_addr;proxy_http_version 1.1;proxy_set_header Connection "";}}
Скрипт используется в версии Мессенджера 26.1 и выше. Если версия вашей инсталляции ниже 26.1, перейдите к шагу 5.
Для использования скрипта необходимо наличие на компьютере интерпретатора языка Python версии 3.0 и выше и менеджера пакетов pip.
-
Скачайте и разархивируйте архив в любой удобной директории.
-
Перейдите в директорию и выполните команды:
python3 -m venv .venvsource .venv/bin/activatepip install -r requirements.txt
Чтобы пользователи из разных инсталляций могли общаться друг с другом, нужно добавить пользователей в белый список.
На обеих инсталляциях нужно:
- Составить список пользователей, которым разрешено федеративное общение, и запустить команду, которая сформирует файл с белым списком.
- Передать файл с белым списком в удаленную инсталляцию и получить такой же файл от удаленной инсталляции.
- Загрузить файлы с белыми списками на каждой инсталляции.
-
Создайте файл whitelist.yaml и наполните его списком пользователей, которым разрешено федеративное взаимодействие. Формат файла:
trust: "fid:150/<tenantID>/<trustID>" # идентификатор трастаusers:"i.ivanov@company_domain":"n.belov@company_domain":"a.petrov@company_domain":- trust — идентификатор траста, созданного на шаге «Настройка взаимодействия»;
- users — список пользователей. В конце email обязательно ставьте двоеточие. Email в этом случае — это ключ объекта, в котором потом могут быть дополнительные значения.
-
Создайте файл с белым списком remote_trust_whitelist.yaml — на сервере Мессенджер и ВКС выполните команду:
python3 main.py --stentor-base-url stentor-<hostname> --whitelist ./example/whitelist.yaml --outfile remote_trust_whitelist.yamlгде:
-
stentor-base-url — имя хоста к api-stentor, как правило имеет вид
stentor-<hostname>; -
whitelist — whitelist.yaml, описанный выше;
-
outfile — remote_trust_whitelist.yaml со списком fid'ов пользователей, который необходимо передать в удаленную инсталляцию.
Команда создает файл remote_trust_whitelist.yaml, где каждому пользователю присваивается федеративный идентификатор (fid). Файл имеет следующую структуру:
trust: "fid:150/<tenantID>/<trustID>"users:"i.ivanov@company_domain":fid: fid:0/HZnKEBoqDU/100401"n.belov@company_domain":fid: fid:0/HZnKEBoqDU/100402"a.petrov@company_domain":fid: fid:0/HZnKEBoqDU/100403 -
-
Передайте файл remote_trust_whitelist.yaml в удаленную инсталляцию.
-
Получите файл remote_trust_whitelist.yaml от удаленной инсталляции.
-
На сервере Мессенджер и ВКС добавьте полученный файл в любую директорию и выполните команду:
python3 main.py --stentor-base-url stentor-<hostname> --whitelist remote_trust_whitelist.yaml
Email-адреса пользователей в объединяемых инсталляциях должны быть уникальны: одного и того же email не должно быть одновременно на инсталляции А и на инсталляции В.
Если такой пользователь есть:
- Определите, на какой инсталляции этому пользователю разрешается логиниться.
- Запустите создание whitelist на этой инсталляции.
- Передайте полученный whitelist на вторую инсталляцию.
- На второй инсталляции этот пользователь залогиниться не сможет.
Пример: есть учетная запись ab@mail.ru и объединяемые инсталляции 1n и 8n. Учетная запись должна логиниться в 1n — запустите создание whitelist на 1n и передайте полученный файл на 8n. На 8n эта учетная запись логиниться не сможет, потому что Федерация будет считать ее сервисной.
При изменениях на стендах необходимо вручную перезапускать поды Boss — для них отключен автоматический рестарт подов при изменении конфигов.
Версии сервисов выкатываются с определенным интервалом. Если на стенде стояла старая версия, а затем ее поменяли на новую, она могла остаться в кеше — из-за этого Федерация поначалу может работать некорректно.
Сгенерированные сертификаты и ключи должны быть доступны на чтение/запись только для root-пользователя/сервисов Мессенджер и ВКС в рамках прав доступа файловой системы.
-
Выпустите CA сертификат и ключ, последовательно выполнив команды:
# mkdir /root/mtls# mkdir /root/mtls/private# mkdir /opt/certs# openssl genrsa -out /root/mtls/private/cakey.pem 4096# openssl req -new -x509 -days 3650 -key /root/mtls/private/cakey.pem -out /opt/certs/server.cacert.pemКаждая инсталляция Федерации выпускает свой публичный сертификат CA.
-
Выпустите серверный сертификат и ключ:
Сохраните приведенную ниже конфигурацию в файл /root/mtls/san.cnf — она используется в шагах 4–5 ниже.
[ req ]distinguished_name = req_distinguished_name[v3_req]subjectAltName = @alt_names[alt_names]DNS.1 = federation.domain.ru # хост локальной инсталляции[ req_distinguished_name ]C = RUST = MoscowL = MoscowO = CompanyACN = <installation_А> # укажите имя локальной инсталляции на латинице -
Перейдите в директорию с сертификатами /opt/certs и создайте приватный ключ:
# cd /opt/certs# openssl genrsa -out server.key.pem 4096 -
Переподпишите с SNA:
# openssl req -new -nodes -out server.csr.pem -keyout server.key.pem -config /root/mtls/san.cnf -subj "/CN=<company_installation_name>" -
Выпустите сертификат (подпишите у CA):
# openssl x509 -req -in server.csr.pem -CA server.cacert.pem -CAkey /root/mtls/private/cakey.pem -CAcreateserial -out server.cert.pem -days 365 -extensions v3_req -extfile /root/mtls/san.cnf -
Убедитесь, что в SAN-сертификате есть хост локальной инсталляции:
# openssl x509 -in server.cert.pem -noout -text | grep -A1 "Subject Alternative Name" -
Под каждую инсталляцию, с которой устанавливается соединение, выпустите клиентские ключ и сертификат. В CN и SAN добавьте информацию удаленной инсталляции (в которую будете передавать эти сертификаты). В конфигурации сервиса Fedproxy полю cert_cn для каждой инсталляции задайте значение соответственно CN клиентских сертификатов:
# openssl genrsa -out client.key.pem 4096# openssl req -new -key client.key.pem -out client.csr.pem -subj "/CN=<имя удаленной инсталляции>"# openssl x509 -req -in client.csr.pem -CA server.cacert.pem -CAkey /root/mtls/private/cakey.pem -CAcreateserial -out client.cert.pem -days 365 -extfile <(echo "subjectAltName=DNS:<хост удаленной инсталляции>")где <имя удаленной инсталляции> — значение параметра cert_cn конфигурационного файла federation.yml.
Пример команды:
# openssl genrsa -out client.key.pem 4096# openssl req -new -key client.key.pem -out client.csr.pem -subj "/CN=installation_В"# openssl x509 -req -in client.csr.pem -CA server.cacert.pem -CAkey /root/mtls/private/cakey.pem -CAcreateserial -out client.cert.pem -days 365 -extfile <(echo "subjectAltName=DNS:federation.domain.ru")Полученные сертификаты client.cert.pem, client.key.pem и server.cacert.pem (переименовав в client.cacert.pem) передайте в инсталляцию B.
Функциональность доступна для инсталляций версии 26.2 и выше.
Вы можете управлять правами пользователей на федеративное взаимодействие:
- Выдать права — пользователь получает статус активности на федеративное взаимодействие в рамках траста/тенантов.
- Изъять права:
- В локальном тенанте пользователь получает статус запрета на федеративное взаимодействие в рамках траста.
- Во все тенанты траста направляется информация об изъятии прав у пользователя на федеративное взаимодействие в рамках траста.
- Пользователь удаляется из всех федеративных чатов траста, но:
- Если пользователь состоит в более чем одном трасте, то удаляются только те чаты, которые не подходят под активные трасты.
- Личные чаты с федеративными пользователями, взаимодействие с которыми было доступно только в рамках данного траста, становятся доступны только для просмотра.
- Групповые федеративные чаты траста, в котором были изъяты права, доступы только для просмотра и выхода из них.
- Возобновить взаимодействие — пользователь получает статус активности на федеративное взаимодействие в рамках траста/тенантов.
Администратор инсталляции может управлять правами пользователей Федерации в своей инсталляции. Например, администратор инсталляции А может запретить пользователю инсталляции В Иванову писать пользователям инсталляции А. При этом у Иванова останется возможность взаимодействовать с пользователями других инсталляций Федерации — С и D.
-
Создайте файл whitelist.yaml, который содержит всех пользователей Федерации. Формат файла:
trust: "fid:150/<tenantID>/<trustID>"users:"test1@fed1-el7.v3.im-sandbox.devmail.ru":fid: fid:0/HZnKEBoqDU/100401action: init"test2@fed1-el7.v3.im-sandbox.devmail.ru":fid: fid:0/HZnKEBoqDU/100402action: allow"test3@fed1-el7.v3.im-sandbox.devmail.ru":fid: fid:0/HZnKEBoqDU/100403action: denyгде:
- trust — идентификатор траста;
- action — принимает значение:
- init — инициализировать (создать) федеративного пользователя.
- allow — вернуть пользователю возможность осуществлять федеративное взаимодействие.
- deny — запретить пользователю осуществлять федеративное взаимодействие.
-
Запустите скрипт для применения изменений:
python3 main.py --stentor-base-url stentor-<hostname> --whitelist ./example/whitelist.yaml
Чтобы откатить Федерацию и вернуть инсталляцию к состоянию до настройки, выполните шаги ниже.
-
В веб-интерфейсе установщика VK Workspace перейдите в Проекты → vkteams.
-
В окне Формы проекта vkteams выберите Federation (Настройка федерации) и выключите переключатели:
- Включить федерацию;
- Включить event manager;
- message-send-api-enabled.

-
Нажмите кнопку Сохранить настройки.
-
Перейдите на главную страницу веб-интерфейса установщика, нажав на логотип VK WorkSpace.
-
Запустите автоматическую установку, нажав на кнопку Play
.
На машине, где развернут Мессенджер, выполните:
kubectl delete virtualservice fed-gw-ingress -n vkteamskubectl delete virtualservice fedproxy-ingress -n vkteams
После отката проверьте, что корректно работают:
- создание тредов;
- добавление реакций;
- обновление прочитанности сообщений;
- отправка сообщений;
- создание чатов;
- поиск.
Попросите пользователей перезапустить клиент Мессенджера — после отката часть пользователей может наблюдать проблемы до перезапуска клиента.
Если этого достаточно, на этом можно остановиться.
-
На главной странице веб-интерфейса установщика раскройте раздел Federation.

-
Для каждого сервиса нажмите на шестеренку в строке с названием сервиса, в открывшемся окне нажмите кнопку Удалить в правом верхнем углу.

-
На главной странице установщика выполните перезапуск кнопкой Play
.
Технический писатель: Москвина Анна