Версия: 2.0.x

Внешние PostgreSQL и Keycloak (consume-only)

Глава описывает подключение baremetal-инсталляции к уже существующим PostgreSQL и/или Keycloak.

Модель: оператор самостоятельно готовит БД/роли и realm/клиентов. Инсталлятор их не создаёт, а инсталляция получает настройки через extraEnv в deploy.yaml.
Готовые примеры: examples/external-services.deploy.yaml, examples/external-secrets.env, examples/external-keycloak-realm.json.

Как работает: extraEnv.<svc>.vars рендерится в <svc>.extra.env при каждом install/upgrade и подключается юнитом после основного env;
файлы из extraEnv.<svc>.files подключаются после extra.env (последний имеет приоритет).
Поэтому переопределения декларативны, сохраняются при обновлениях, а секреты хранятся в отдельном файле, который инсталлятор не трогает.

Поддерживаемые сценарии: только внешний PG, только внешний Keycloak, оба (пример ниже).

Подготовка внешнего PostgreSQL

Locale - обязательное требование (lakekeeper требует ICU-collation):
либо кластер инициализирован с --encoding=UTF8 --locale=C.utf8 (как в initdb бандла),
либо каждая БД создаётся с явными ENCODING 'UTF8' LC_COLLATE 'C.utf8' LC_CTYPE 'C.utf8' TEMPLATE template0.

Выполнить под суперъюзером:

CREATE ROLE selena_cm LOGIN PASSWORD 'CHANGE_ME';  
CREATE ROLE selena_ide LOGIN PASSWORD 'CHANGE_ME'; -- если components.ide=true  
CREATE ROLE selena_ai LOGIN PASSWORD 'CHANGE_ME'; -- если components.ai=true  
CREATE ROLE lakekeeper LOGIN PASSWORD 'CHANGE_ME'; -- если components.lakekeeper=true  
CREATE ROLE keycloak LOGIN PASSWORD 'CHANGE_ME'; -- ТОЛЬКО если Keycloak остаётся бандленным  
-- Если кластер УЖЕ инициализирован с --locale=C.utf8 - обычный CREATE DATABASE ... OWNER  
-- для остальных БД достаточен. Если локаль кластера иная - локаль нужно указать явно  
-- КАЖДОЙ БД (см. lakekeeper ниже), иначе lakekeeper упадёт на ICU-collation.  
CREATE DATABASE selena_cm OWNER selena_cm;  
CREATE DATABASE selena_ide OWNER selena_ide;  
CREATE DATABASE selena_ai OWNER selena_ai;  
CREATE DATABASE lakekeeper OWNER lakekeeper  
ENCODING 'UTF8' LC_COLLATE 'C.utf8' LC_CTYPE 'C.utf8' TEMPLATE template0;  
CREATE DATABASE keycloak OWNER keycloak; -- только при бандленном Keycloak

Расширения: lakekeeper при первой миграции выполняет CREATE EXTENSION "uuid-ossp". Файлы расширения должны быть установлены на сервере PG (пакет postgresql16-contrib или аналог). В PG бандла он уже есть, при отсутствии расширения запуск lakekeeper завершится с ошибкой: «extension "uuid-ossp" is not available».

Для ролей, используемых при установке, необходимо настроить сетевой доступ (pg_hba) с хоста, где выполняется инсталляция. Создавать схемы не требуется: инсталлятор самостоятельно выполнит миграции IDE и AI через alembic; а CM, Keycloak и lakekeeper применят миграции при первом запуске.

Подготовка внешнего Keycloak

Вариант А (одной операцией): импортировать examples/external-keycloak-realm.json, предварительно заменив CHANGE_ME_*-секреты и 203.0.113.10 на ваш publicHost.

Шаблон не тестировался на работающем внешнем Keycloak (импорт service-account-юзеров version-dependent). После импорта проверьте чек-лист:

У service-account клиента selena-cluster-manager-api назначены 4 клиентские роли в realm-management: query-groups, query-users, view-realm, view-users.
Bootstrap-юзер добавлен в группы /cm/admins и /selena/writers.
Группа cm/security-admins существует.

Вариант Б (вручную) - завести в realm:

Клиент	Тип	Обязательное
selena-engine	confidential	directAccessGrants; audience-маппер selena-engine; groups-маппер groups (full path); redirect URIs `http://<publicHost>:8088/` и `http://<publicHost>:10001/`
selena-cluster-manager-api	service account	клиентские роли realm-management: query-groups, query-users, view-realm, view-users
selena-ide	confidential	audience-маппер selena-engine; redirect `http://<publicHost>:10001/*`
selena-ide-service	service account	audience-маппер selena-engine
selena-ai	confidential	redirect `http://<publicHost>:8411/, :8412/`
selena-ai-service	service account	audience-маппер selena-engine

Браузерным клиентам (selena-engine, selena-ide, selena-ai) необходимо также заполнить webOrigins: в realm бандла - *; в проде - по вашей CORS-политике.

Группы: cm/{admins,role-admins,security-admins,viewers}, selena/{readers,writers}. Права пользователей Selena определяются членством в этих группах (claim groups, full path). Для автоматического Engine bootstrap требуется УЗ в /cm/admins с разрешённым password grant (см. раздел 7.5).

deploy.yaml

В качестве основы используется файл examples/external-services.deploy.yaml. В нём необходимо отключить установку встроенных PostgreSQL и Keycloak:

components:  
postgres: false # не ставить бандленный PG  
keycloak: false # не ставить бандленный KC

Параметры подключения, не содержащие секретов (URL, имена БД), передаются через extraEnv.<svc>.vars в deploy.yaml.

Пароли и токены размещаются в файле /etc/selena/external/secrets.env, который подключается к сервисам через extraEnv.<svc>.files.

Переменные для сервисов:

Таблица 7.1. PostgreSQL

Сервис	vars (несекретно)	secrets.env
Keycloak (если бандленный)	KC_DB_URL	KC_DB_USERNAME, KC_DB_PASSWORD
cm	CM_DB_URL, CM_DB_USER	CM_DB_PASSWORD
ide	-	DATABASE_CONN (conn-string целиком)
ai-backend	-	AI_BACKEND_DATABASE_URL
lakekeeper	-	LAKEKEEPER__PG_DATABASE_URL_READ, LAKEKEEPER__PG_DATABASE_URL_WRITE

Таблица 7.2. Keycloak (база = https://<kc-host>/realms/<realm>)

Сервис	vars (несекретно)	secrets.env
cm	CM_KEYCLOAK_TOKEN_URI, CM_KEYCLOAK_LOGOUT_URI, CM_KEYCLOAK_JWKS_URI, CM_KEYCLOAK_ISSUER_URI, CM_KEYCLOAK_ADMIN_TOKEN_URI, CM_KEYCLOAK_ADMIN_BASE_URI	CM_KEYCLOAK_LOGIN_CLIENT_SECRET, CM_KEYCLOAK_ADMIN_CLIENT_SECRET
ide	IDE_KEYCLOAK_ISSUER_URL, IDE_KEYCLOAK_AUTHORIZATION_URL, IDE_KEYCLOAK_TOKEN_URL, IDE_KEYCLOAK_JWKS_URL, IDE_KEYCLOAK_LOGOUT_URL, IDE_SERVICE_TOKEN_URL	IDE_KEYCLOAK_CLIENT_SECRET, IDE_SERVICE_CLIENT_SECRET
ai-backend	AI_BACKEND_AUTH_ISSUER_URL, AI_BACKEND_AUTH_AUTHORIZATION_URL, AI_BACKEND_AUTH_TOKEN_URL, AI_BACKEND_AUTH_LOGOUT_URL, AI_BACKEND_AUTH_JWKS_URL	AI_BACKEND_AUTH_CLIENT_SECRET
mcp	MCP_KEYCLOAK_JWKS_URL, MCP_KEYCLOAK_ISSUER	-

При внешнем Keycloak внутренний (127.0.0.1) и публичный URL объединяются в один базовый URL.

Секрет-файл

Создайте каталог и разместите в нём файл с секретами:

sudo install -d -m0755 /etc/selena/external  
sudo install -m0600 -o root -g root examples/external-secrets.env /etc/selena/external/secrets.env  
sudoedit /etc/selena/external/secrets.env # заменить все CHANGE_ME

Формат - systemd EnvironmentFile: KEY=значение до конца строки (без кавычек). Один файл может содержать секреты для всех сервисов (имена переменных имеют префиксы).

Файл должен существовать до запуска install.sh, иначе установка завершится ошибкой (fail fast).

Установка и Engine bootstrap

Далее следуйте шагам разделов 4 «Установка Selena (online)» или 5 «Установка Selena (offline)».

На этапе preflight инсталлятор выдаст предупреждение о том, что встроенные PostgreSQL и Keycloak отключены. Это ожидаемое поведение, ошибкой не является.

Миграции IDE и AI будут выполнены инсталлятором во внешний PostgreSQL через alembic. Переопределение параметров подключения действует как при установке (install.sh), так и при обновлении (upgrade.sh).

Для автоматической настройки Engine при использовании внешнего Keycloak в файле secrets.env необходимо указать CM_BOOTSTRAP_KC_USERNAME и CM_BOOTSTRAP_KC_PASSWORD. Учетная запись должна состоять в группе /cm/admins и иметь разрешенный password grant (для клиента selena-engine включена опция Direct Access Grants).

Если password grant запрещен политикой Keycloak, фаза engine_bootstrap пропускается (выдается предупреждение). В этом случае Engine добавляется вручную через Cluster Manager UI с использованием той же учетной записи.

Для сценария «Инфра + Control Plane» (например, examples/online.deploy.yaml) фаза engine_bootstrap также пропускается. Переменные CM_BOOTSTRAP_KC_USERNAME и CM_BOOTSTRAP_KC_PASSWORD требуются только в сценариях, предусматривающих установку Engine.

Ограничения

TLS внешнего Keycloak. Сертификат должен быть доверенным для системного хранилища хоста. Для самоподписанного сертификата необходимо добавить корневой сертификат (CA) в доверенные до запуска install.sh.
Апгрейды (upgrade.sh). Все настройки из vars обновляются из deploy.yaml. Файл с секретами (secrets.env) не изменяется.
Файл credentials.txt. Не содержит данных о внешних сервисах. Пароли от внешних PostgreSQL и Keycloak известны только администратору.
Vault. Секрет-файл может рендерить Vault Agent:
template → /etc/selena/external/secrets.env + systemctl try-restart затронутых юнитов, - для инсталлятора это прозрачно.
Ротация значений в /etc/selena/external/secrets.env не отслеживается upgrade.sh. После правки файла вручную перезапустите затронутые юниты: systemctl, try-restart, selena-cm, selena-ide-web, selena-ide-worker, selena-ide-scheduler, selena-ai-backend, selena-lakekeeper.
Не редактируйте examples/external-secrets.env в чекауте репозитория - копируйте в /etc/selena/external и правьте копию (риск закоммитить реальные секреты).
Комбинация «встроенный Keycloak + внешний PostgreSQL» поддерживается, но БД keycloak должна существовать до старта Keycloak.

Подготовка внешнего PostgreSQL​

Подготовка внешнего Keycloak​

deploy.yaml​

Секрет-файл​

Установка и Engine bootstrap​

Ограничения​