Перейти к содержимому
AggregaAggrega
Выберите язык: Русский
Эта страница переведена машинным способом. Читать оригинал на английском.

Стек 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, поэтому у них один общий пароль. В этом примере используется общее встроенное значение по умолчанию для разработки, поэтому стек работает автономно, без внешнего секрета.
  • Воспроизводимые образы. И шлюз, и бэкенд фиксируют явные теги образов, поэтому отрендеренные манифесты ссылаются на стабильные образы.

Создание примера

Этот пример можно собрать командами ниже или поручить сборку вашему ИИ-ассистенту.

Запишите пример в новую папку, названную по его имени:

Terminal window
aggrega scaffold --example kong-stack

Затем она выводит команды, которые нужно выполнить дальше. Первая переходит в новую папку:

Terminal window
cd kong-stack

Сборка

В этом рабочем пространстве нет .aggrega-config.yaml, поэтому сущности стандартной библиотеки разрешаются из реестра hub, hub.aggrega.ai, и флаг каталога не нужен; --auto-pull во время сборки записывает lock-файл, которого нет в свежем клоне:

Terminal window
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.