Федерация: путь A и путь B

1. Что такое федерация

• management_model (27017) — модель управления.
• environment_data (27018/27019 в зависимости от раскладки) — данные окружения.
• federated_model (27019) — федеративная БД, общая для нескольких окружений/площадок.

install-ng при конфигурировании ищет management server через федерацию. Если её нет/она указывает не туда — падение на No suitable management server found или таймаут.

2. Путь A — федерация внутри окружения

• Первая нода ставится без -S.
• install-ng создаёт federated_model в модели и поднимает федеративный mongod локально.
• marvinweb получает /federated/.
• Add-node остальных + -x → extend_clusters() добавляет mongodb_federated_node2/3.
• Требуется ≥3 ONLINE MGMT-нод.

Когда: один кластер из 3 нод, одна площадка.

3. Путь B — федерация в базовой системе

• Одна инсталляция помечается base_system=true и владеет федеративной БД.
• Остальные ставятся с -S (scale-out) и подключаются через federateddbconnection.
• На каждой ноде поднимается federatedhaproxy как прокси к базовой БД.
• Данные подключения штатно добываются скриптом /opt/ampli/scripts/supportability/pre_scaleout_info.py на базовой системе (JSON: endpoints, ssl key/cert, DSS policy, deployment_id).

Когда: несколько окружений/площадок, performance scale-out.

4. Почему -S на первой ноде — ошибка для пути A

В install-ng:

is_scale_out = options.is_scale_out and options.install_type in ["combined"]
management.initialize(..., skip_federated_db=is_scale_out)

skip_federated_db=True убирает federated_model из списка создаваемых кластеров. Для пути A это значит: федерации в модели нет, расширять нечего, /federated/ не рендерится.

Симптомы:

• /federated/_status/ → 404 (нет location в nginx) или 30-сек таймаут.
• install-ng: configuring machines failed: No suitable management server found.
• В модели кластера federated_model нет.

5. Что проверить до старта

# на ноде, mTLS
sudo curl -sk --cert <CERT> --key <KEY> https://127.0.0.1:8443/model/mongocluster/ | jq
sudo curl -sk --cert <CERT> --key <KEY> https://127.0.0.1:8443/model/environment/ | jq

• Есть ли federated_model в списке кластеров (путь A).
• base_system и federateddbconnection (путь B).
• Флаг запуска первой ноды: не -S для пути A.
• cfg/product/activescale.yml → install_type.combined.clusters содержит federated_model.

6. Проверка после

sudo curl -sk --cert <CERT> --key <KEY> \
  https://127.0.0.1:8443/federated/_status/ \
  -w '\nHTTP=%{http_code} time=%{time_total}s\n'

Ожидается 200 и < 50 мс. Если 30 000 мс — pymongo topology-hang, федерация/порт не та.

Также:

• replSetGetStatus для federated_model: PRIMARY + 2 SECONDARY.
• pgrep -af mongod — 3 процесса на ноду.
• services.cfg содержит секции федеративных mongodb (grep -oE '^\[...\]' | sort).

7. Грабли

1. -S на первой ноде → федерация не создана (путь A).
2. mongo_federated_replicaset: management_model — яд, не использовать.
3. Ручной federated_mongo_connection_string в group_vars — лабораторный костыль; на чистом прогоне его быть не должно.
4. Бэкапы .orig/.bak в group_vars — ansible грузит все, бэкап побеждает.
5. Порт 27019 занят/не слушает — проверить ss -ltnp, конфиг mongod.

8. Пошаговая последовательность для пути A

Порядок важен: федерация создаётся на первой ноде и потом только расширяется. Если сделать шаги в другом порядке, расширять будет нечего.

Шаг 1. Первая нода — install-ng без -S. Это единственное место, где решается судьба федерации. Первая нода создаёт federated_model в модели и поднимает федеративный mongod локально; marvinweb получает location /federated/. Флаг -S (scale-out) на этом шаге выставляет skip_federated_db=True, и кластер в модели создаётся, а федеративный — нет.

Шаг 2. Проверить федерацию до добавления нод. Не переходить дальше, пока не выполнено:

sudo curl -sk --cert <CERT> --key <KEY> \
  https://127.0.0.1:8443/federated/_status/ \
  -w '\nHTTP=%{http_code} time=%{time_total}s\n'

Норма — 200 и меньше 50 мс. Тридцать секунд означают pymongo topology-hang: федерация или порт не те. Дополнительно: federated_model присутствует в списке кластеров модели (GET /model/mongocluster/), а в services.cfg есть секция федеративного mongod на 27019.

Шаг 3. Подготовить очередь и добавить остальные ноды. Очередь для каждой ноды берётся с рабочего узла и правится: environment.json с новым deployment_id, machine.json с ролью SPXCTRLSTORAGEMGMT и только двумя реально поднятыми NIC (лишние MAC дают фантомные интерфейсы), column.json без поля status (иначе падение на column NOTINITIALIZED), реальные MGMT/storage адреса и MAC.

Шаг 4. Запуск с -x (extend). На добавляемых нодах расширение идёт через extend_clusters(), которое дописывает в federated_model узлы mongodb_federated_node2/node3. Требование продукта — не меньше трёх ONLINE MGMT-нод; на двух нодах репликасет не соберётся в устойчивом виде.

Шаг 5. Проверить репликасет и процессы. replSetGetStatus для federated_model должен показать PRIMARY и два SECONDARY. pgrep -af mongod — три процесса на ноду (управление, данные окружения, федерация). Расхождение в числе процессов означает, что один из кластеров не поднялся, и «федерация вроде жива» — иллюзия.

Шаг 6. Только теперь S3-сервисы и приёмка. DSS, неймспейсы, политика, S3 PUT — всё это проверяется после того, как федерация стабильна. Если гонять приёмку параллельно с add-node, часть проверок упадёт по таймауту и вы будете искать несуществующую проблему.

9. Как отличить путь A от пути B на живой системе

Отличать надо по модели, а не по документации установки: документация описывает намерение, модель описывает факт. Четыре поля закрывают вопрос.

Быстрый признак «снаружи»: GET /federated/_status/ на ноде, где федерации нет, отдаёт 404 (нет location в nginx) либо висит до таймаута. Живой, но чужой ответ — это путь B: запрос ушёл через прокси на базовую систему.

Ещё один маркер — способ получения данных подключения. В пути B они штатно добываются на базовой системе скриптом pre_scaleout_info.py из каталога supportability: JSON с endpoints, ключами и сертификатами, политикой DSS и deployment_id. Если вы видите, что кто-то вручную правил federated_mongo_connection_string в group_vars — это не путь A и не путь B, а лабораторный обход, и на чистом прогоне его быть не должно.

10. Что ломается при смешивании путей и как откатиться

Смешивание — самая дорогая ошибка, потому что она не даёт явной ошибки на старте. Типовые комбинации:

1. Первая нода с -S, остальные тоже scale-out. Федерации нет нигде. install-ng падает на configuring machines failed: No suitable management server found, /federated/ не рендерится. Лечения «дописать кластер потом» нет: модель уже создана без federated_model.
2. Первая нода без -S, а остальные ставят с -S в расчёте на базовую систему. Ноды пытаются подключиться к федерации, которой в их понимании нет; получаются таймауты 30 секунд и висящие задачи конфигурирования. Федерация существует, но не там, где её ищут.
3. Ручная правка group_vars «чтобы заработало». federated_mongo_connection_string: mongodb://127.0.0.1:27019 — допустимая вендор-уровневая настройка для пути A. А вот mongo_federated_replicaset: management_model — яд: федеративный клиент начинает искать репликасет управления. То же с бэкапами .orig/.bak в group_vars: ansible грузит все файлы каталога, и бэкап побеждает рабочую правку. Симптом — «правку применил, ничего не изменилось».
4. Смена пути на живой системе. Перевести кластер из A в B или обратно «на месте» нельзя: это разные модели владения БД, а не флаг. Данные федерации не переносятся правкой конфига.

Откат возможен только один — чистый прогон. То есть повторная установка с нуля с правильным флагом на первой ноде и правильной очередью для остальных. «Дожима» нет: нельзя добавить federated_model в уже созданную модель через API или досоздать репликасет руками так, чтобы это считалось штатным состоянием. Вендор такой процедуры не описывает, а самодельная конструкция развалится на первом же апгрейде или add-node.

Практический порядок отката:

• Зафиксировать, что именно сломано: нет federated_model (случай 1), федерация есть но не находится (случай 2), конфиг перебит бэкапами (случай 3).
• Проверить, есть ли на нодах данные, которые нельзя потерять. Если да — сначала выгрузить их через S3, потом переустанавливать.
• Очистить group_vars от .orig/.bak, убрать самодельные federated_* оверрайды.
• Переустановить первую ноду без -S, дождаться 200 < 50 мс на /federated/_status/.
• Добавить остальные ноды и проверить PRIMARY + 2 SECONDARY.

Единственное, что можно чинить без переустановки, — конфигурационные грабли: порт в federated.cfg не 27019, занятый 27019 (ss -ltnp), лишние файлы в group_vars. Всё, что касается отсутствия federated_model в модели, лечится только новым прогоном.

11. Источники

• Software Documentation Center
• Внутренняя практика (обезличено): разбор федерации на 3-нодном стенде.