×

Создание инстанса 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
Типовой пресет CPU и памяти каждого узла (справочник пресетов).
 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
Типовой пресет CPU и памяти каждого узла (справочник пресетов).
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 обновляет узлы. Перед обновлением проверьте совместимость драйверов и сделайте резервную копию
  • Удаление — удаление инстанса удаляет и его диски с данными. Выгрузите нужные данные заранее