Стек Keycloak — сервер идентификации с базой данных, собранный как модуль
Этот пример компилирует небольшой реальный стек — сервер идентификации с базой
данных — в синтезированные манифесты Kubernetes из одного написанного разработчиком
Aggregate.
Сервер идентификации — не один компонент. Это модуль: переиспользуемый вложенный агрегат, который объединяет два компонента с одной рабочей нагрузкой —
- сервер, который обслуживает консоль учётных записей и эндпоинты токенов на своём HTTP-порту и не хранит локального состояния, и
- бэкенд, PostgreSQL, который хранит realms, клиентов и пользователей сервера и сохраняет их на томе.
Модуль сам задаёт своё внутреннее ребро от сервера к бэкенду и
экспортирует сервер как свой публичный эндпоинт http. Сущность Aggregate верхнего уровня
импортирует модуль по имени и отрисовывает собранный стек; оператор задаёт размеры
внутренних компонентов модуля в сущности Release.
Файлы
| Файл | Роль |
|---|---|
aggregate.yaml | Намерение разработчика: импортирует модуль сервера идентификации (core/keycloak). |
manifest-helm-synth.yaml | Сопоставляет типы сервера и бэкенда с их Recipes synth helm, а сущность Feature учётных данных, которую модуль подключает, — с реализацией, создающей Secret из параметров учётных данных модуля. |
release-helm-synth.yaml | Запись оператора для цели Kubernetes. Задаёт размеры внутренних компонентов модуля по их идентификаторам в области модуля; всё, что оставлено значениям по умолчанию из схемы, рендерится автономно. |
Что демонстрирует пример
- Композиция в виде модуля. Возможность с несколькими рабочими нагрузками — сервер идентификации, который на деле состоит из сервера и базы данных конфигурации, — упакована как вложенный агрегат из двух компонентов с одной рабочей нагрузкой, а не как один монолитный компонент. Модуль импортируется по имени и переиспользуется везде, где нужен сервер идентификации.
- Внутреннее ребро внутри модуля. Сервер объявляет использование
бэкенда; хост, порт, пользователь и база данных из
providesсущности Recipe бэкенда передаются в сервер и собираются в его подключение к базе данных. Компилятор маршрутизирует строки, не интерпретируя их. - Публичный эндпоинт. Модуль экспортирует свой сервер как
http— стабильное публичное имя, к которому подключается потребитель, — независимое от внутренних имён компонентов модуля. - Задание размеров внутренних компонентов оператором. Сущность Release обращается к внутренним
компонентам модуля по их идентификаторам в области модуля (
server.backend,server.server), чтобы задать вычислительные ресурсы, и сущности Aggregate разработчика не нужно повторять физические размеры. - Самомигрирующая схема. Сервер при запуске сам создаёт и мигрирует свою схему в бэкенде, поэтому он стартует с готовой схемой без отдельного шага миграции.
- Общие учётные данные по ссылке. Сервер аутентифицируется в своём
бэкенде PostgreSQL, поэтому у них общий пароль. Модуль принимает его как
параметр
db_passwordи дважды подключает с ним сущность Feature учётных данныхcore/referenced-secret: к собственному слоту учётных данных бэкенда и какcredentialподключения сервера к бэкенду — подключения, в котором сервер его предъявляет. Каждая рабочая нагрузка читает пароль из Secret, а не хранит его inline; пароль начальной учётной записи администратора — второй параметр,admin_password. Поскольку модуль подключает эту сущность Feature, Manifest сопоставляет её. Этот пример оставляет оба параметра со значениями модуля по умолчанию для разработки и сопоставляет Feature сk8s-secret-from-parameter, которая создаёт Secret с каждым значением, так что стек работает автономно. Для сущности Release с реальным трафиком Aggregate объявляет собственные параметры и передаёт их вниз черезaggregates.server.parameters, Release заполняет их, а Manifest сопоставляет Feature сk8s-existing-secret, которая читает каждый параметр как имя Secret, уже существующего в пространстве имён. - Воспроизводимые образы. И сервер, и бэкенд фиксируют явные теги образов, поэтому отрисованные манифесты ссылаются на стабильные образы.
Создание примера
Этот пример можно собрать командами ниже или поручить сборку вашему ИИ-ассистенту.
Запишите пример в новую папку, названную по его имени:
aggrega scaffold --example keycloak-stackЗатем она выводит команды, которые нужно выполнить дальше. Первая переходит в новую папку:
cd keycloak-stackСборка
В этом рабочем пространстве нет .aggrega-config.yaml, поэтому сущности стандартной библиотеки разрешаются из реестра hub, hub.aggrega.ai, и флаг каталога не нужен; --auto-pull во время сборки записывает lock-файл, которого нет в свежем клоне:
aggrega build --release release-helm-synth.yaml --auto-pullОтрисованные артефакты помещаются в dist/. Целевая платформа Kubernetes отрисовывает обычные
манифесты офлайн — загрузка чарта не требуется.
С ИИ-ассистентом
ИИ-ассистент, настроенный с инструментами Aggrega, может сделать то же самое: вставьте в него этот промпт.
Используйте только инструменты Aggrega и не создавайте папки самостоятельно. Если в папке рабочего пространства ещё нет папки `keycloak-stack`, вызовите инструмент `scaffold` один раз, задав для `example` значение `keycloak-stack`, без `dir`: он запишет пример в новую папку `keycloak-stack`. Затем вызовите инструмент `build`, задав для `workspace_root` значение `keycloak-stack`, для `release` — `release-helm-synth.yaml`, для `auto_pull` — true и для `write` — true. Сообщите, какие файлы записала сборка; они находятся в `keycloak-stack/dist/`.Как выглядит собранный стек
Сервер отрисовывается как Deployment без состояния плюс Service типа ClusterIP на HTTP-порту. Его контейнер содержит подключение, собранное из ребра к бэкенду, — имя Service бэкенда внутри кластера, пользователя и базу данных, — а также автономные настройки HTTP, включённые эндпоинты проверки работоспособности, обслуживаемые на порту управления, и начальную учётную запись администратора; оба пароля читаются из Secret:
env: - name: KC_DB_PASSWORD valueFrom: secretKeyRef: name: server-zdserver-db.credential key: db-password - name: KC_BOOTSTRAP_ADMIN_PASSWORD valueFrom: secretKeyRef: name: server-zdserver-admin-password key: admin-password - name: KC_DB value: postgres - name: KC_DB_URL_HOST value: server-zdbackend-default - name: KC_DB_URL_PORT value: "5432" - name: KC_DB_URL_DATABASE value: keycloak - name: KC_DB_USERNAME value: keycloak - name: KC_HTTP_ENABLED value: "true" - name: KC_HOSTNAME_STRICT value: "false" - name: KC_HEALTH_ENABLED value: "true" - name: KC_HTTP_MANAGEMENT_PORT value: "9000" - name: KC_BOOTSTRAP_ADMIN_USERNAME value: adminКонтейнер объявляет порт управления 9000 рядом с HTTP-портом, и
Deployment проверяет сервер на нём: startup-проба на /health/started сдерживает
остальные, пока сервер загружается, readiness-проба на /health/ready
не пускает трафик, пока он не ответит, а liveness-проба на /health/live
перезапускает его, если он перестаёт отвечать. Service по-прежнему перенаправляет только HTTP-порт.
Бэкенд отрисовывается как StatefulSet с постоянным томом, смонтированным в
/var/lib/postgresql/data, плюс Service типа ClusterIP и headless Service. Его
POSTGRES_PASSWORD читает тот же пароль базы данных из собственного Secret,
server-zdbackend-password. Три Secret создаются рядом с рабочими нагрузками,
по одному на каждые учётные данные, которые подключает модуль, и каждый содержит значение модуля
по умолчанию для разработки.