Стек FerretDB — документная база данных, собранная как модуль
Этот пример компилирует небольшой реальный стек — документную базу данных, предоставляющую
протокол MongoDB wire, — в синтезированные манифесты Kubernetes из одного
Aggregate, написанного разработчиком.
Документная база данных — это не один компонент. Это модуль: переиспользуемый подагрегат, который объединяет два компонента с одной рабочей нагрузкой каждый:
- прокси, который работает по протоколу MongoDB wire и не хранит локального состояния, и
- бэкенд — PostgreSQL 17 с расширением DocumentDB, который хранит данные на томе.
Модуль сам связывает внутреннее ребро от прокси к бэкенду и экспортирует
прокси как свою публичную конечную точку mongo. Сущность Aggregate верхнего уровня импортирует
модуль по имени и рендерит собранный стек; оператор задаёт размеры внутренних
компонентов модуля в сущности Release.
Файлы
| Файл | Роль |
|---|---|
aggregate.yaml | Намерение разработчика: импортирует модуль документной базы данных (core/ferretdb). |
manifest-helm-synth.yaml | Сопоставляет типы прокси и бэкенда с их синтезированными helm-сущностями Recipes. |
release-helm-synth.yaml | Запись оператора для цели Kubernetes. Задаёт размеры внутренних компонентов модуля по их идентификаторам в области модуля; всё, что оставлено значениям по умолчанию из схемы, рендерится автономно. |
Что демонстрирует пример
- Композиция в виде модуля. Возможность с несколькими рабочими нагрузками — документная база данных, которая на деле представляет собой прокси и бэкенд хранения, — упакована как подагрегат, объединяющий два компонента с одной рабочей нагрузкой, а не как один монолитный компонент. Модуль импортируется по имени и переиспользуется везде, где нужна документная база данных.
- Внутреннее ребро внутри модуля. Прокси объявляет использование бэкенда;
хост, порт, пользователь и база данных из
providesсущности Recipe бэкенда передаются в прокси и собираются в его подключение к PostgreSQL. Компилятор маршрутизирует строки, не интерпретируя их. - Публичная конечная точка. Модуль экспортирует свой прокси как
mongo— стабильное публичное имя, к которому подключается потребитель документной базы данных, не зависящее от внутренних имён компонентов модуля. - Задание размеров внутренних компонентов оператором. Сущность Release обращается к внутренним компонентам модуля по их идентификаторам в области модуля (
database.backend,database.proxy), чтобы задать вычислительные ресурсы, и сущности Aggregate разработчика не нужно повторять физические размеры. - Общие учётные данные. Прокси делегирует аутентификацию своему бэкенду PostgreSQL, поэтому у них один общий пароль. В этом примере используется общее встроенное значение по умолчанию для разработки, поэтому стек работает автономно, без внешнего секрета.
- Строка подключения без пароля. URL подключения прокси к PostgreSQL
рендерится без встроенного пароля; пароль передаётся отдельно через
стандартную переменную окружения libpq
PGPASSWORD, которую драйвер объединяет с подключением. Так учётные данные не попадают в строку подключения в отрендеренном манифесте. - Воспроизводимые образы. И прокси, и бэкенд фиксируют явные теги образов, поэтому отрендеренные манифесты ссылаются на стабильные образы.
Создание примера
Этот пример можно собрать командами ниже или поручить сборку вашему ИИ-ассистенту.
Запишите пример в новую папку, названную по его имени:
aggrega scaffold --example ferretdb-stackЗатем она выводит команды, которые нужно выполнить дальше. Первая переходит в новую папку:
cd ferretdb-stackСборка
В этом рабочем пространстве нет .aggrega-config.yaml, поэтому сущности стандартной библиотеки разрешаются из реестра hub, hub.aggrega.ai, и флаг каталога не нужен; --auto-pull во время сборки записывает lock-файл, которого нет в свежем клоне:
aggrega build --release release-helm-synth.yaml --auto-pullОтрисованные артефакты помещаются в dist/. Целевая платформа Kubernetes отрисовывает обычные
манифесты офлайн — загрузка чарта не требуется.
С ИИ-ассистентом
ИИ-ассистент, настроенный с инструментами Aggrega, может сделать то же самое: вставьте в него этот промпт.
Используйте только инструменты Aggrega и не создавайте папки самостоятельно. Если в папке рабочей области ещё нет папки `ferretdb-stack`, вызовите инструмент `scaffold` один раз, задав `example` равным `ferretdb-stack` и не указывая `dir`: он запишет пример в новую папку `ferretdb-stack`. Затем вызовите инструмент `build`, задав `workspace_root` равным `ferretdb-stack`, `release` равным `release-helm-synth.yaml`, `auto_pull` равным true и `write` равным true. Сообщите мне, какие файлы записала сборка; они находятся в `ferretdb-stack/dist/`.Как выглядит собранный стек
Прокси рендерится как Deployment без состояния и Service типа ClusterIP на порту протокола. Окружение его контейнера содержит подключение, собранное из ребра к бэкенду, — имя внутрикластерного Service бэкенда, пользователя и базу данных, без пароля в URL, — и оставляет отладочный слушатель FerretDB на loopback-адресе пода, где до него не может добраться ни один другой под:
env: - name: FERRETDB_LISTEN_ADDR value: :27017 - name: FERRETDB_DEBUG_ADDR value: 127.0.0.1:8088 - name: FERRETDB_POSTGRESQL_URL value: postgres://postgres@database-zdbackend-default:5432/postgres - name: PGPASSWORD value: apppassНи одной из проб этот слушатель не нужен. Проба готовности запускает ferretdb ping
внутри контейнера; эта команда опрашивает порт протокола и тем самым подтверждает и подключение
к бэкенду; проба живости проверяет только, что порт протокола принимает
подключения, поэтому сбой бэкенда выводит прокси из его Service, не
перезапуская его:
livenessProbe: tcpSocket: port: 27017readinessProbe: exec: command: - /ferretdb - pingБэкенд рендерится как StatefulSet с постоянным томом, смонтированным в
/var/lib/postgresql/data, а также Service типа ClusterIP и headless Service.