Стек Kong — API-шлюз с базой данных, собранный как модуль
Этот пример компилирует небольшой реальный стек — API-шлюз с базой данных —
в синтезированные манифесты Kubernetes из одного Aggregate, написанного разработчиком.
Шлюз — это не один компонент. Это модуль: повторно используемый вложенный агрегат, который объединяет два компонента с одной рабочей нагрузкой —
- шлюз, который принимает клиентский трафик на своём прокси-порту и не хранит локального состояния, и
- бэкенд, PostgreSQL, который хранит конфигурацию шлюза и сохраняет её на томе.
Модуль сам связывает своё внутреннее ребро от шлюза к бэкенду и
экспортирует шлюз как свою публичную конечную точку proxy. Сущность Aggregate верхнего уровня
импортирует модуль по имени и рендерит собранный стек; оператор задаёт размеры
внутренних компонентов модуля в сущности Release.
Файлы
| Файл | Роль |
|---|---|
aggregate.yaml | Намерение разработчика: импортирует модуль API-шлюза (core/kong). |
manifest-helm-synth.yaml | Сопоставляет типы шлюза и бэкенда с их синтезированными helm-сущностями Recipes. |
release-helm-synth.yaml | Запись оператора для цели Kubernetes. Задаёт размеры внутренних компонентов модуля по их идентификаторам в области модуля; всё, что оставлено значениям по умолчанию из схемы, рендерится автономно. |
Что демонстрирует пример
- Композиция в виде модуля. Возможность из нескольких рабочих нагрузок — API-шлюз, который на деле представляет собой прокси и базу данных конфигурации, — упакована как вложенный агрегат, объединяющий два компонента с одной рабочей нагрузкой, а не как один монолитный компонент. Модуль импортируется по имени и повторно используется везде, где нужен шлюз.
- Внутреннее ребро внутри модуля. Шлюз объявляет использование
бэкенда; хост, порт, пользователь и база данных из
providesсущности Recipe бэкенда передаются в шлюз и составляют его подключение к PostgreSQL. Компилятор маршрутизирует строки, не интерпретируя их. - Публичная конечная точка. Модуль экспортирует свой шлюз как
proxy— стабильное публичное имя, к которому подключается потребитель, — независимо от внутренних имён компонентов модуля. - Задание размеров внутренних компонентов оператором. Сущность Release обращается к внутренним
компонентам модуля по их идентификаторам в области модуля (
gateway.backend,gateway.gateway), чтобы задать вычислительные ресурсы, и сущности Aggregate разработчика не нужно повторять физические размеры. - Шаг миграций, выполняемый до начала обслуживания. Шлюз создаёт схему своей базы данных через init-контейнер, который выполняется до завершения перед запуском основного контейнера шлюза, поэтому шлюз работает с готовой схемой. Начальная настройка идемпотентна, поэтому повторный запуск на уже подготовленной базе данных ничего не делает.
- Общие учётные данные. Шлюз аутентифицируется в своём бэкенде PostgreSQL, поэтому у них один общий пароль. В этом примере используется общее встроенное значение по умолчанию для разработки, поэтому стек работает автономно, без внешнего секрета.
- Воспроизводимые образы. И шлюз, и бэкенд фиксируют явные теги образов, поэтому отрендеренные манифесты ссылаются на стабильные образы.
Создание примера
Этот пример можно собрать командами ниже или поручить сборку вашему ИИ-ассистенту.
Запишите пример в новую папку, названную по его имени:
aggrega scaffold --example kong-stackЗатем она выводит команды, которые нужно выполнить дальше. Первая переходит в новую папку:
cd kong-stackСборка
В этом рабочем пространстве нет .aggrega-config.yaml, поэтому сущности стандартной библиотеки разрешаются из реестра hub, hub.aggrega.ai, и флаг каталога не нужен; --auto-pull во время сборки записывает lock-файл, которого нет в свежем клоне:
aggrega build --release release-helm-synth.yaml --auto-pullОтрисованные артефакты помещаются в dist/. Целевая платформа Kubernetes отрисовывает обычные
манифесты офлайн — загрузка чарта не требуется.
С ИИ-ассистентом
ИИ-ассистент, настроенный с инструментами Aggrega, может сделать то же самое: вставьте в него этот промпт.
Используйте только инструменты Aggrega и не создавайте папки самостоятельно. Если в папке рабочего пространства ещё нет папки `kong-stack`, вызовите инструмент `scaffold` один раз, задав для `example` значение `kong-stack`, без `dir`: он запишет пример в новую папку `kong-stack`. Затем вызовите инструмент `build`, задав для `workspace_root` значение `kong-stack`, для `release` — `release-helm-synth.yaml`, для `auto_pull` — true и для `write` — true. Сообщите, какие файлы записала сборка; они находятся в `kong-stack/dist/`.Как выглядит собранный стек
Шлюз рендерится как Deployment без состояния, а также Service типа ClusterIP на прокси-порту и ConfigMap со списком разрешённых запросов его Status API. Его Pod содержит init-контейнер миграций, который выполняется до основного контейнера; оба получают подключение, составленное из ребра к бэкенду, — внутрикластерное имя Service бэкенда, пользователя и базу данных:
env: - name: KONG_DATABASE value: postgres - name: KONG_PG_HOST value: gateway-zdbackend-default - name: KONG_PG_PORT value: "5432" - name: KONG_PG_USER value: kong - name: KONG_PG_DATABASE value: kong [… omitted: the gateway's own proxy, admin and status listen addresses, and the allowlist file its Status API includes] - name: KONG_PG_PASSWORD value: apppassПробы готовности и работоспособности шлюза обращаются к Status API Kong —
GET /status/ready и GET /status — на порту контейнера status, поэтому этот
слушатель привязан к адресу Pod. Kong включает список разрешённых запросов из
ConfigMap в собственный блок server Status API: с любого адреса, кроме адреса
loopback самого Pod, он отвечает на GET к /status, /status/ready или /metrics и
отклоняет все прочие запросы с кодом 403 — в том числе POST /status/ready, который
иначе перевёл бы шлюз в режим вывода из работы и исключил бы его из его Service до
перезапуска.
Бэкенд рендерится как StatefulSet с постоянным томом, смонтированным в
/var/lib/postgresql/data, а также Service типа ClusterIP и headless Service.