Справочник по конфигурации

auth (data plane) и central (control plane) при старте читают по одному HOCON-файлу и несколько переменных окружения. Эта страница перечисляет и то и другое по блокам и говорит, какие блоки нужны в продакшене. У edge свой список блоков — см. Конфигурацию edge.

Обычно эти файлы вручную не пишут. versola configure (и Helm chart) генерирует их с помощью versola-tools для разворачиваемого релиза, а секреты оставляет плейсхолдерами ${VAR}. Файлы пересоздаются при каждом configure, поэтому на таргете vps ручная правка теряется; поддерживаемого способа менять отдельные настройки там пока нет. Считайте эту страницу справочником по содержимому сгенерированных файлов.

Как загружается конфигурация

• Сервис читает HOCON-файл по пути из CONFIG_PATH (в контейнере по умолчанию /app/config/env.conf; образ передаёт его в JVM как -Denv.path). Вместо файла всю конфигурацию можно передать строкой в переменной окружения ENV_CONFIG.
• Ключи пишутся в kebab-case (maximum-pool-size). Длительности — HOCON-длительности ("60 seconds", 5 minutes).
• Работает стандартная подстановка HOCON, поэтому ${VAR} и ${?VAR} берут значения из переменных окружения. Сгенерированные файлы используют это для секретов: versola configure разрешает каждый секрет из OpenBao в файлы <service>.secrets.env, которые Compose передаёт контейнеру как окружение, а в файле конфигурации остаётся только плейсхолдер. В Kubernetes те же ключи приходят из Secret (Kubernetes).
• Синтаксическая ошибка останавливает сервис при старте. HOCON не читает UTF-16: правьте файлы в UTF-8.
• env обязателен. Значение prod означает продакшен; любое другое считается тестовой средой. Продакшен местами строже (например, TLS для Postgres) — об этом ниже.

Переменные окружения

Сгенерированная конфигурация читает и несколько переменных, которые за вас задаёт chart или Compose-файл (например, издателя сертификатов в Kubernetes). Всё остальное, включая секреты, лежит в HOCON-файле и хранилище секретов.

Блоки, общие для всех сервисов

Верхний уровень

postgres

Все ключи, кроме notifications-url, ssl-root-cert и pool-metrics-interval, обязательны и значений по умолчанию не имеют: так бюджет соединений всех экземпляров можно спланировать относительно max_connections Postgres. Ниже — значения, которые генерирует versola-tools.

TLS для Postgres

Каждое соединение с Postgres открывается с sslmode=verify-full, если в URL не задан свой sslmode: сертификат должен вести к доверенному CA и совпадать с именем хоста. Это относится и к пулу, и к соединению notifications-url.

• Чтобы доверять приватному CA, смонтируйте его bundle в контейнер и задайте ssl-root-cert; на таргете vps передайте --postgres-ca <file> в versola configure, и CLI сделает и то и другое. Уже заданный в URL sslrootcert имеет приоритет.
• URL, который не проверяет сертификат (sslmode=disable, allow, prefer или require, либо ssl=false), пишет предупреждение при старте. При env = "prod" сервис отказывается запускаться.
• Хосты localhost, 127.0.0.1 и [::1] освобождены от обоих правил. versola-tools пишет sslmode=disable для встроенного локального Postgres и для vps, у которого --postgres-host — loopback; удалённый хост vps остаётся на проверяющем режиме по умолчанию.
• sslfactory в URL, который может пропускать проверку, считается слабостью так же.

За пулером соединений

central и edge держат соединение, припаркованное на LISTEN: так изменение конфигурации доходит до каждой реплики, а отозванный токен перестаёт приниматься до истечения срока. Пулер в transaction-режиме LISTEN пронести не может. Если url указывает на пулер, задайте notifications-url прямым URL Postgres:

postgres {
  url               = "jdbc:postgresql://pgbouncer:6432/auth?currentSchema=edge"
  notifications-url = "jdbc:postgresql://postgres:5432/auth?currentSchema=edge"
}

При старте сервис проверяет, что получает собственное уведомление, и если нет — отказывается запускаться, называя эту настройку.

auth

Обязательны в продакшене: env, configuration-cache-refresh-interval, security, jwt, central, postgres. Необязательны: bootstrap, par, dpop, argon2, mutual-tls, otp-provider, smtp, cleanup. Сгенерированный файл включает bootstrap, par, argon2, mutual-tls и cleanup.

security

Одиннадцать секретов, все обязательны. Каждый — значение в base64url; сгенерированные плейсхолдеры и длина после декодирования:

Часть из них защищает хранимые данные и ни в коем случае не должна пересоздаваться; см. Секреты.

jwt

central

par

Необязателен. Pushed authorization requests (RFC 9126).

dpop

Необязателен. Если блока нет, действуют значения по умолчанию.

Нужен ли nonce — настройка тенанта в админ-консоли, а не конфигурации. См. токены с привязкой к отправителю.

mutual-tls

Необязателен. Запускает второй listener на MPORT, который требует клиентский сертификат и обслуживает /token, /introspect, /revoke, /par и /userinfo, а discovery начинает объявлять mtls_endpoint_aliases (RFC 8705 §5). Без блока клиентский сертификат доходит до auth только заголовком, который пробрасывает прокси тенанта.

Таргеты vps и Kubernetes генерируют этот блок и стоящие за ним сертификаты (сервис mtls-init на базе step-ca или cert-manager). См. клиентские сертификаты edge.

argon2

Необязателен. Хеширование паролей Argon2id.

otp-provider

Необязателен, в сгенерированном файле закомментирован. HTTP-эндпоинт, доставляющий OTP-коды (например, SMS).

smtp

Необязателен, в сгенерированном файле закомментирован. Используется для e-mail OTP и доставки паролей.

Без SMTP и OTP-провайдера у продакшен-деплоя нет канала доставки временного пароля; в prod пароль можно только доставить, но не показать на экране.

bootstrap

Необязателен. При первом старте создаёт пользователя-администратора.

cleanup

Периодическое удаление просроченных строк. Сгенерированный файл перечисляет эти таблицы с размером пачки и интервалом:

Неудавшаяся пачка больше не останавливает очистку этой таблицы до перезапуска (исправлено в 0.7.0). Сервис публикует метрики cleanup_*, по которым видно, успевает ли удаление; см. Наблюдаемость.

central

Обязательны в продакшене: env, configuration-cache-refresh-interval, secret-key, client-secrets-secret, auth, user-outbox, postgres. Необязательны: bootstrap, client-certificates, client-certificate-authority.

bootstrap

В коде необязателен; сгенерированный файл всегда его включает. Он заполняет базу central один раз, при первом старте на пустой базе. Последующие изменения конфигурации ничего не меняют: правьте объекты в админ-консоли.

client-certificates

Необязателен. Как central выпускает и продлевает сертификаты клиентов, стоящих за edge. В этом режиме ключа CA у central нет. Настраивается ровно один бэкенд; пока бэкенд не назван, блок считается отсутствующим.

client-certificate-authority

Необязателен, только для локальной разработки: ключ CA хранит сам central. certificate и private-key — PEM-пути (ключ — незашифрованный PKCS#8); validity-days при необходимости ограничивает срок. Без него регистрация клиента, которая просит central выпустить сертификат, отклоняется. Везде, кроме локальной разработки, используйте client-certificates.

Порядок запуска

auth и edge при старте синхронизируют конфигурацию с central. Если central ещё не слушает, они ждут до двух минут. Само по себе ожидание заканчивается успехом только с HTTP_CLIENT_POOL_KIND=dynamic. С пулом fixed по умолчанию первый запрос открывает все соединения пула, central их отклоняет, и пул хранит по одному неудавшемуся соединению на слот (по умолчанию 128), так что каждая повторная попытка тратит одно из них, и ожидание не может завершиться успехом, даже когда central уже поднялся. Через две минуты сервис завершается с кодом 1 и полагается на политику перезапуска (restart: unless-stopped в Compose-бандлах, restartPolicy: Always в Kubernetes); перезапущенный процесс строит новый пул и стартует нормально. Ожидайте один перезапуск при холодной установке, где central стартует не первым. versola up запускает central первым и этого избегает. Пока сервис ждёт, /liveness отвечает 200, а /readiness — 503. central, который отвечает и отклоняет запрос (неверный URL, неверный ключ), приводит к ошибке старта за секунды.

Пул исходящего HTTP-клиента

auth, central и edge используют один исходящий HTTP-клиент: вызовы между сервисами и вызовы edge к бэкендам, которые он проксирует. Пул ведётся на цель (схема, хост и порт), поэтому у каждого бэкенда свой пул заданного размера. Выбранный пул один раз логируется при старте (outbound HTTP client pool: ...).

HTTP/1.1-соединение обслуживает один запрос за раз, поэтому пул ограничивает пропускную способность пода к одному бэкенду примерно величиной size / задержка бэкенда. Ни один вид пула не падает при исчерпании: запрос ждёт свободное соединение без собственного таймаута, поэтому слишком маленький пул проявляется задержкой, а не ошибками. http_client_active_requests считает исходящие запросы в работе, включая стоящие в очереди, и растёт первым. Размер выбирайте как пиковые запросы в секунду на под, умноженные на p99 задержки бэкенда, с запасом. Пул fixed на 128 открывает 128 соединений к каждому бэкенду, с которым работает под; при многих бэкендах dynamic с малым MIN занимает меньше сокетов, но платит установкой соединения, когда приходит всплеск.

Таблицы состояния входа UNLOGGED

Это один из осознанных компромиссов Versola; полный список таблиц UNLOGGED, цену сбоя и способ вернуть журналирование см. в Компромиссах.

С 0.7.0 таблицы auth_conversations, authorization_codes и pushed_authorization_requests — UNLOGGED: они не пишутся в журнал предзаписи (WAL). В них лежит только состояние входа возрастом в минуты, а их журналирование заставляло базу ждать фиксации WAL. Что за это платится:

• Штатный перезапуск Postgres сохраняет их строки.
• Сбой Postgres (kill -9, отказ хоста, потеря питания) их опустошает. Standby их никогда не получает, поэтому после failover они пусты, а восстановление из бэкапа возвращает их пустыми.
• Теряется только состояние в процессе: пользователи посреди многошагового входа начинают заново, а ещё не использованный код авторизации или отправленный запрос отклоняется, и клиент повторяет попытку. Сессии, токены, согласия и пользователи не затрагиваются.
• Миграция выполняет ALTER TABLE ... SET UNLOGGED, берёт эксклюзивную блокировку и перезаписывает каждую таблицу. Таблицы небольшие, но запускайте versola migrate при низком трафике: входы на ещё работающей старой версии ждут, пока она идёт.

Время жизни refresh-токена

Время жизни refresh-токена фиксируется при выдаче и больше не продлевается использованием (с 0.7.0). Это не настройка файла конфигурации: у каждого клиента своё refreshTokenTtl в секундах, оно задаётся при регистрации клиента через Central API или админ-консоль. Если не указано, по умолчанию 15552000 (180 дней); релизы до 0.7.0 брали 90 дней и продлевали при каждом использовании.

Заголовки безопасности

Все прикладные listener’ы auth, central и edge (основной, дополнительный, mutual-TLS; но не порт диагностики) добавляют эти заголовки ответа, если обработчик не выставил их сам:

Политики default-src в Content-Security-Policy и form-action нет: они сломали бы логотипы и шрифты тенантов и редиректы на redirect_uri клиента. Ваш прокси, терминирующий TLS, должен пробрасывать X-Forwarded-Proto, иначе HSTS не будет отправляться; includeSubDomains предполагает, что все хосты под доменом работают только по https.

Настройки JVM по умолчанию

Образы auth, central и edge задают JAVA_OPTS с профилем фиксированного размера на Temurin 25, поэтому расход памяти не зависит от того, сколько её у хоста:

-XX:+UseG1GC -Xms512m -Xmx512m -XX:MaxDirectMemorySize=64m -XX:MaxMetaspaceSize=128m
-XX:ReservedCodeCacheSize=64m -Xss512k -XX:NativeMemoryTracking=summary
-XX:+UseCompactObjectHeaders -XX:+HeapDumpOnOutOfMemoryError
-XX:HeapDumpPath=/diagnostics/heap.hprof -XX:+ExitOnOutOfMemoryError
-Xlog:gc*:file=/diagnostics/gc.log:time,uptime,level,tags:filecount=5,filesize=20M
--enable-native-access=ALL-UNNAMED

У edge MaxDirectMemorySize=96m; у auth и central — 64m. Куча — 512 МиБ, фиксированная (-Xms равен -Xmx). Закладывайте около 850 МиБ резидентной памяти на сервис: из этого рассчитан лимит памяти 1 ГиБ в chart. При OutOfMemoryError JVM пишет один дамп кучи (при каждом падении он перезаписывается), завершается, чтобы супервизор её перезапустил, и оставляет ротируемый GC-лог в /diagnostics; оба деплоя монтируют туда том. См. Наблюдаемость.

JAVA_OPTS заменяет строку целиком, поэтому повторите все флаги, которые хотите сохранить. Прежнего значения -XX:MaxRAMPercentage=75.0 больше нет: на таргете vps память контейнеров ничем не ограничена, и процент считался бы от всего сервера для каждой из трёх JVM.

Дальше

• Секреты: что защищает каждый секрет и как его ротировать.
• Наблюдаемость: health-эндпоинты, метрики, логи и диагностика.
• Конфигурация edge: такой же справочник для edge.