Создание инстанса MongoDB и первое подключение
ВВЕДЕНИЕ
MongoDB — документоориентированная СУБД: данные хранятся в гибких BSON-документах, поддерживаются индексы, агрегации и транзакции. Подходит для каталогов, профилей, событийных данных и приложений, схема которых меняется вместе с кодом.
В DevSpace MongoDB — управляемый сервис на базе Percona Operator for MongoDB. Вы заполняете одну форму, а платформа разворачивает сразу replica set: несколько узлов с репликацией, которые сами выбирают первичный узел при сбое — драйверы MongoDB переключаются на него автоматически, это штатный механизм самой СУБД. Когда данные перерастут один replica set, тот же сервис включает шардированный режим: несколько шардов, конфиг-серверы и mongos-роутеры.
Чем это отличается от привычной установки на VM:
-
replica set создаётся готовым — не нужно вручную инициализировать rs.initiate() и следить за узлами
-
пользователи и базы описываются декларативно в форме, а не через db.createUser()
-
учётные данные хранятся в секрете платформы
-
данные лежат на отдельных постоянных дисках и переживают перезапуск узлов
ПЕРЕД НАЧАЛОМ
Понадобятся:
-
доступ к пространству DevSpace и право создавать в нём сервисы
-
MongoDB Shell (mongosh) или драйвер MongoDB для проверки подключения
-
для резервного копирования — S3-совместимое хранилище (бакет и ключи доступа)
ПОШАГОВОЕ РУКОВОДСТВО
Шаг 1. Откройте Marketplace и выберите MongoDB
Войдите в дашборд DevSpace и откройте раздел Marketplace. Найдите карточку MongoDB (категория PaaS, подпись «Managed MongoDB service») и откройте её. У формы две вкладки: Form (поля) и YAML (та же конфигурация текстом). Под полем имени показан tenant-id вашего пространства.
Шаг 2. Заполните основные поля
Для примера в этой статье используются значения:
|
Поле
|
Значение
|
Зачем
|
|
Name
|
smtest
|
Имя инстанса: строчные латинские буквы, цифры, дефисы. Станет частью имён сервисов и секрета (mongodb-<name>-…).
|
|
replicas
|
3
|
Три узла replica set — нечётное число для соблюдения кворума
|
|
resourcesPreset
|
t1.small
| |
|
size
|
10Gi
|
Постоянный диск каждого узла.
|
|
storageClass
|
local
|
Класс хранилища. Выбор зависит от того, сколько экземпляров у сервиса и реплицирует ли он данные сам — подробнее в разделе «Параметры». После создания изменить нельзя.
|
|
external
|
включено
|
Опубликовать MongoDB наружу через LoadBalancer. Если клиенты живут в том же пространстве — оставьте выключенным.
|
|
version
|
v8
|
Мажорная версия MongoDB (v8, v7, v6).
|
|
sharding
|
выключено
|
Обычный replica set или шардированный режим — для данных, переросших один replica set.
|
Дальше в статье <name> — это имя, которое вы задали в поле Name: платформа подставляет его в имена сервисов, секретов и компонентов инстанса.
Подсказка: поля cpu и memory в группе resources позволяют задать ресурсы точнее пресета — заполняйте их, только когда типовых пресетов не хватает: явные значения имеют приоритет. Память указывайте с единицами измерения: 512Mi, 2Gi.
|

Шаг 3. Опишите пользователя и базу данных
В группе users добавьте пользователя user01 и задайте password. Пароль лучше задать явно: если оставить поле пустым, платформа сгенерирует его сама, но положит в отдельный секрет mongodb-<name>-user-user01, а на вкладке Secrets карточки показывается другой секрет — mongodb-<name>-credentials с учётными данными служебного администратора базы.

В группе databases добавьте базу db01 и в roles.admin укажите user01 — пользователь получит права readWrite и dbAdmin на эту базу. Для доступа только на чтение есть roles.readonly.

Шаг 4. Запустите развёртывание
Нажмите Deploy. Откроется карточка созданного инстанса — дождитесь статуса Ready в шапке.

Шаг 5. Убедитесь, что все компоненты запущены
Статус Ready означает, что платформа применила конфигурацию сервиса, но сами компоненты после этого ещё могут запускаться: узлы стартуют, replica set инициализируется и выбирает первичный узел — автоматически, без вашего участия. Поэтому, прежде чем подключаться, проверьте фактическое состояние развёртывания на вкладке Workloads карточки — по смыслу это аналог systemctl status на сервере: видно, что реально запущено и готово к работе.
В разделе Pods этой вкладки — по строке на каждый запущенный экземпляр компонента, справа в строке — статус и счётчик готовности в формате «готово/всего». Состав строк зависит от конфигурации. Для примера из этой статьи их три:
-
mongodb-<name>-rs0-0… mongodb-<name>-rs0-2 — узлы replica set rs0, по одному на replicas
Сервис готов к работе, когда в каждой строке статус Running, а числа в счётчике совпадают: 1/1, 2/2, 3/3. Значение «всего» у разных компонентов своё — важно только, чтобы числа были равны.
Строки со статусом Succeeded и счётчиком 0/1 — это нормально: разовая задача автоматики отработала и завершилась.

Если строка со статусом Running показывает 0/1, 1/2, 1/3, развёртывание ещё не завершилось — даже если в шапке уже Ready. Сразу после создания это нормально: компонентам нужно время на запуск. Если картина долго не меняется, откройте вкладку Events: там отображаются события запуска компонентов, по ним обычно видно, на чём запуск остановился. Если причина непонятна, обратитесь в поддержку и укажите имя инстанса. Возвращайтесь к вкладке Workloads и после изменений конфигурации: если изменение перезапускает компоненты, часть строк какое-то время будет не готова.
|
Шаг 6. Получите адрес и учётные данные
На вкладке Services карточки инстанса:
-
mongodb-<name>-rs0— внутренний адрес replica set для приложений из того же пространств
-
mongodb-<name>-rs0-0, -rs0-1, -rs0-2 — при включённом external каждый узел replica set получает собственный LoadBalancer с внешним IP (колонка External IP). Подключение снаружи идёт к конкретному узлу по его адресу, порядок — в разделе «Проверка»
-
mongodb-<name>-mongos— роутеры mongos (только в шардированном режиме)

В колонке Cluster IP у mongodb-<name>-rs0 стоит None — так и должно быть: этот сервис не выдаёт один общий адрес, а отдаёт драйверу адреса самих узлов. Внешние адреса узлов — в колонке External IP, порт у всех 27017. На скрине показан другой инстанс, mg01 с двумя узлами: у трёх узлов строк будет три.
Вкладка Secrets показывает единственный секрет mongodb-<name>-credentials с пятью ключами: username, password, host, port и готовая строка uri. Это учётные данные служебного администратора базы — пользователя databaseAdmin, которого платформа заводит для обслуживания инстанса. Вашего user01 здесь нет, его пароль вы задали сами на шаге 3.
Значения раскрываются кнопкой с иконкой глаза. host и uri ведут на внутренний адрес инстанса, например:
mongodb://databaseAdmin:<пароль>@mongodb-<name>-rs0.tenant-<идентификатор-пространства>.svc.cozy.local:27017/admin?replicaSet=rs0
|

Готовой строки для подключения снаружи в секрете нет: uri всегда ведёт на внутренний адрес инстанса. Чтобы подключиться из интернета, соберите строку сами — из внешних адресов узлов на вкладке Services и учётных данных своего пользователя. Пример такой строки — в разделе «Проверка».
Приложение подключайте под своим пользователем с паролем из шага 3. Рекомендуем передавать учётные данные через хранилище секретов, а не хранить в коде.
ПАРАМЕТРЫ
Основные
|
Параметр
|
Что делает
|
Значение по умолчанию
|
Когда менять
|
|
replicas
|
Число узлов replica set.
|
3
|
Держите нечётным. 1 — только для разработки: без выборов первичного узла нет отказоустойчивости.
|
|
resourcesPreset
|
t1.small
|
Подбирайте по рабочему набору данных и нагрузке.
| |
|
resources.cpu / resources.memory
|
Явные ресурсы вместо пресета.
|
не заданы
|
Когда типовых пресетов не хватает. Явные значения имеют приоритет. Память указывайте с единицами измерения: 512Mi, 2Gi.
|
|
size
|
Размер постоянного диска каждого узла.
|
10Gi
|
Под объём данных с запасом.
|
|
storageClass
|
Класс постоянного хранилища.
|
local — копии тома только на одном сервере
|
При одном экземпляре — replicated, при двух и больше обычно local, потому что ввод-вывод у replicated медленнее. Параметр неизменяемый — смена потребует нового инстанса и переноса данных. Разбор — в подсказке в конце раздела.
|
|
external
|
Публикует сервис наружу: LoadBalancer на порту 27017.
|
false
|
Включайте, только если клиенты работают вне пространства через публичные сети.
|
|
version
|
Мажорная версия MongoDB: v8, v7, v6.
|
v8
|
Под совместимость драйверов приложения.
|
|
users
|
Карта пользователей. password можно не задавать — сгенерируется автоматически.
|
{}
|
Отдельный пользователь на приложение.
|
|
databases
|
Карта баз. roles.admin (readWrite + dbAdmin) и roles.readonly — списки пользователей.
|
{}
|
Выдача и отзыв прав декларативно.
|
Шардирование
|
Параметр
|
Что делает
|
Значение по умолчанию
|
Когда менять
|
|
sharding
|
Включает шардированный режим вместо одиночного replica set.
|
false
|
Когда данные или нагрузка на запись переросли один replica set. До этого replica set проще и дешевле.
|
|
shardingConfig.configServers
|
Число конфиг-серверов кластера.
|
3
|
Обычно менять не нужно.
|
|
shardingConfig.configServerSize
|
Диск каждого конфиг-сервера.
|
3Gi
|
При большом числе коллекций и чанков.
|
|
shardingConfig.mongos
|
Число роутеров mongos — точек входа для клиентов.
|
2
|
Больше — при высокой параллельной нагрузке.
|
|
shardingConfig.shards
|
Список шардов: у каждого name, replicas, size.
|
один шард rs0 (3 реплики, 10Gi)
|
Добавляйте шарды по мере роста данных.
|
Резервное копирование и восстановление
|
Параметр
|
Что делает
|
Значение по умолчанию
|
Когда менять
|
|
backup.enabled
|
Включает регулярные резервные копии.
|
false
|
Включайте для всех долговременных данных.
|
|
backup.schedule
|
Cron-расписание копий.
|
0 2 * * *
|
Под требуемую точку восстановления (RPO).
|
|
backup.retentionPolicy
|
Срок хранения копий, например 30d.
|
30d
|
Под политику хранения.
|
|
backup.destinationPath
|
Путь в хранилище, например s3://bucket/path/.
|
—
|
Отдельный префикс на каждый инстанс.
|
|
backup.endpointURL
|
Адрес S3-совместимого API.
|
—
|
Адрес вашего хранилища.
|
|
backup.s3AccessKey / backup.s3SecretKey
|
Ключи доступа к S3.
|
—
|
Отдельная учётная запись с минимальными правами.
|
|
bootstrap.enabled
|
Создаёт инстанс с восстановлением из резервной копии.
|
false
|
Только при создании инстанса-восстановления.
|
|
bootstrap.backupName
|
Имя копии для восстановления.
|
—
|
Точное имя проверенной копии.
|
|
bootstrap.recoveryTime
|
Момент для point-in-time восстановления. Пусто — последнее состояние.
|
—
|
Когда нужен срез на конкретное время.
|
Как задать расписание. Расписание пишется строкой из пяти значений через пробел: минута, час, день месяца, месяц, день недели. Звёздочка на месте значения означает «любое», то есть «каждую минуту», «каждый день» и так далее. Считать ничего не нужно — чаще всего подходит один из вариантов ниже.
|
Строка
|
Когда снимается копия
|
|
0 2 * * *
|
каждый день в 2 часа ночи
|
|
0 */6 * * *
|
каждые шесть часов
|
|
30 3 * * 0
|
раз в неделю, в воскресенье в 3:30
|
|
0 1 1 * *
|
раз в месяц, первого числа в час ночи
|
Чем чаще копии, тем меньше данных потеряется при сбое, но тем больше места они занимают в хранилище. Ночное время берут, чтобы копирование не накладывалось на дневную нагрузку.
Как выбрать класс хранилища. replicated держит копии тома на нескольких серверах платформы и переживает потерю сервера, но пишет синхронно в несколько мест, поэтому ввод-вывод у него всегда медленнее, чем у local. Критерий выбора — сколько экземпляров у сервиса и реплицирует ли он данные сам между репликами:
-
один экземпляр — берите replicated: другой копии данных нет, и потеря сервера означает потерю тома
-
два и больше — подходит local: копия данных уже есть на других экземплярах, а replicated под таким сервисом только замедлит запись, дублируя то, что и так продублировано
Узлы replica set MongoDB синхронизируются между собой сами, поэтому при replicas: 3 обычный выбор — local. Если оставляете один узел, берите replicated.
Пример конфигурации
Итоговый ресурс, соответствующий шагам выше. Вкладка YAML формы показывает и принимает ту же конфигурацию.
apiVersion: apps.cozystack.io/v1alpha1
kind: MongoDB
metadata:
name: smtest
spec:
# Три узла replica set: выборы первичного большинством голосов.
replicas: 3
# Типовой пресет CPU/памяти каждого узла.
resourcesPreset: t1.small
# Постоянный диск каждого узла.
size: 10Gi
# Неизменяемый параметр: выбирайте отказоустойчивый класс сразу.
storageClass: replicated
# Внешний LoadBalancer на порту 27017.
external: true
# Мажорная версия MongoDB.
version: v8
# Обычный replica set; шардирование выключено.
sharding: false
# Пользователь приложения.
users:
user01:
password: "<пароль>"
# База и права: user01 — администратор базы db01.
databases:
db01:
roles:
admin:
- user01
|
Производные ресурсы получают префикс mongodb-: секреты mongodb-<name>-credentials и mongodb-<name>-user-user01, сервисы mongodb-<name>-rs0 (и его узловые LoadBalancer’ы), mongodb-<name>-mongos.
|
ПРОВЕРКА
Про authSource
В MongoDB пользователь принадлежит той базе, в которой он заведён, и при подключении драйвер ищет его именно там. Платформа заводит всех пользователей в служебной базе admin, а права выдаёт на вашу базу — поэтому в строке подключения нужен параметр authSource=admin. Это параметр на стороне клиента, а не сервиса.
Из того же пространства
Приложению внутри пространства доступен внутренний адрес replica set — он же лежит в ключе host секрета. Драйвер сам найдёт узлы и сам переключится на новый первичный, если текущий выйдет из строя:
mongosh "mongodb://user01:<пароль>@mongodb-<name>-rs0.tenant-<идентификатор-пространства>.svc.cozy.local:27017/db01?replicaSet=rs0&authSource=admin"
|
Снаружи
Снаружи обнаружение узлов по имени replica set не работает. Драйвер подключится к внешнему адресу, спросит состав replica set и получит в ответ внутренние имена узлов, которые из интернета не разрешаются. Подключение падает с getaddrinfo ENOTFOUND mongodb-<name>-rs0-1.…svc.cozy.local ещё до проверки пароля. Поэтому снаружи подключайтесь напрямую к узлу, добавив directConnection=true и не указывая replicaSet.
|
Узнайте, какой узел сейчас первичный. Выполните команду по очереди для каждого внешнего адреса с вкладки Services — первичный ответит true:
mongosh "mongodb://user01:<пароль>@<внешний-IP-узла>:27017/db01?authSource=admin&directConnection=true" --eval 'db.hello().isWritablePrimary'
|
Подключитесь к первичному узлу и проверьте запись и чтение:
mongosh "mongodb://user01:<пароль>@<внешний-IP-первичного>:27017/db01?authSource=admin&directConnection=true" --eval 'db.test.insertOne({ greeting: "hello" }); db.test.findOne()'
|
В ответ придёт вставленный документ с его _id — значит подключение, права и запись работают.
Цена внешнего подключения — отсутствие автоматического переключения: адрес первичного узла зашит в строку, и после смены первичного узла внешний клиент придётся переподключить на новый адрес. Пишите с внешнего клиента только то, что переживёт такую паузу, а приложения, которым нужна отказоустойчивость, держите в том же пространстве и подключайте по внутреннему адресу.
Если что-то не так
|
Ошибка
|
Причина
|
Что делать
|
|
getaddrinfo ENOTFOUND mongodb-…svc.cozy.local
|
В строке указан replicaSet, и драйвер пытается ходить по внутренним именам узлов
|
Для подключения снаружи уберите replicaSet и добавьте directConnection=true
|
|
Authentication failed
|
Нет параметра authSource=admin либо неверные имя или пароль
|
Добавьте authSource=admin. Пароль — тот, что вы задали на шаге 3
|
|
not primary
|
Вы подключились напрямую к вторичному узлу, а он запись не принимает
|
Найдите первичный узел командой db.hello().isWritablePrimary и подключитесь к нему
|
ЧТО ДАЛЬШЕ
Подключение из приложения — передайте драйверу строку подключения. Например, на Python:
from pymongo import MongoClient
client = MongoClient("mongodb://user01:<пароль>@mongodb-<name>-rs0.tenant-<идентификатор-пространства>.svc.cozy.local:27017/db01?replicaSet=rs0&authSource=admin")
db = client.db01
db.test.insert_one({"greeting": "hello"})
print(db.test.find_one())
|
Строка в примере — внутренняя, для приложения из того же пространства: по ней драйвер сам отслеживает смену первичного узла. Для приложения вне пространства строка собирается иначе, см. «Проверка».
-
Шардирование — когда данные перерастут один replica set, включите sharding и опишите шарды в shardingConfig. Клиенты продолжат ходить через mongos
-
Резервное копирование — включите backup.* и регулярно проверяйте восстановление: разверните из копии отдельный инстанс через bootstrap и сверьте данные. Копия, которую ни разу не восстанавливали, не считается рабочей
-
Масштабирование — replicas и пресет ресурсов меняются в той же форме. Диск можно только увеличивать, storageClass неизменяем
-
Обновление версии — смена version обновляет узлы. Перед обновлением проверьте совместимость драйверов и сделайте резервную копию
-
Удаление — удаление инстанса удаляет и его диски с данными. Выгрузите нужные данные заранее
