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

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

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

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

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

Terminal window
aggrega scaffold --example keycloak-stack

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

Terminal window
cd keycloak-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 и не создавайте папки самостоятельно. Если в папке рабочего пространства ещё нет папки `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 создаются рядом с рабочими нагрузками, по одному на каждые учётные данные, которые подключает модуль, и каждый содержит значение модуля по умолчанию для разработки.