Секреты

Versola нужно около тридцати секретов: ключи шифрования и MAC, пары ключей подписи, пароль Postgres и bootstrap-пароль администратора. Эта страница объясняет, где они лежат, что versola configure делает с каждым из них и какие из них можно безопасно заменить. Прочитайте её, прежде чем восстанавливать сервер, переезжать на новый OpenBao или ротировать значение.

Где лежат секреты

• Таргеты local и vps. В OpenBao (Vault-совместимое хранилище секретов, KV v2, смонтированное в secret), по пути secret/versola/<target>/<path>, где <path> — одно из auth, central, edge и utils. versola configure запускает OpenBao, читает эти пути, определяет, чего не хватает, записывает новые значения и затем разрешает все плейсхолдеры ${VAR} сгенерированной конфигурации в файлы <service>.secrets.env (права 600) в бандле деплоя. Сервисы во время работы с OpenBao не общаются; он должен быть запущен только на время configure.
• Kubernetes. В Kubernetes Secret, которые создаёте вы; chart не генерирует секреты и не требует конкретного бэкенда. См. Kubernetes.

Делайте бэкап данных OpenBao, а также root token и ключа распечатки из ~/.versola/openbao/vps-admin.json. Секрет, защищающий хранимые данные, пересоздать нельзя: если он потерян, эти данные нечитаемы.

Секреты

Это секреты из схемы vps. «При отсутствии» — политика, объясняемая ниже.

В Kubernetes пароль Postgres и пароль администратора задаёт оператор (external), и у каждого сервиса свой POSTGRES_PASSWORD.

Схема

versola-tools пишет secrets.schema.json рядом со сгенерированной конфигурацией. Это единый декларативный список, по которому versola-cli строит план; в нём имена и правила, но не значения.

Значения onMissing:

По since и записанной ревизии деплоя CLI отличает секрет, новый в релизе (его нет в хранилище, потому что туда ещё нечему было попасть: сгенерировать), от потерянного (остановиться). Ревизию схемы, применённую в последний раз, CLI записывает в state.json; деплой без записи считается ревизией 1.

Что configure делает с каждым секретом

Существующее значение в OpenBao всегда побеждает. Политика решает только то, что делать, когда значения нет. Сначала configure определяет состояние деплоя по записи этой машины (~/.versola/active/state.json) и по тому, что хранится в OpenBao:

Для каждого секрета результат — одно из:

Проблема останавливает запуск, ничего не записав:

POSTGRES_PASSWORD на vps должен быть одинаковым у auth, central и edge; configure отказывается продолжать, если значения различаются.

Как читать план

versola secrets plan <target> <version> печатает те же решения, ничего не записывая, и завершается с ненулевым кодом, если есть проблемы.

versola secrets plan vps <version>

Secrets plan: vps, Versola <version>
Schema revision 2, deployed revision 1 — upgrade (a deployment record exists, OpenBao holds secrets)

  auth     ACCESS_TOKENS_SECRET   keep
  auth     PASSWORDS_SECRET       keep
  edge     EDGE_NATIVE_BLOB_KEY   create (generated, new in this revision)

Result: OK

(Сокращено: в настоящем выводе по строке на каждый секрет.) С --json тот же отчёт печатается одним объектом. Значения секретов не появляются ни в одном формате.

{
  "version": "<version>",
  "ok": false,
  "target": "vps",
  "state": "upgrade",
  "schemaRevision": 2,
  "deployedRevision": 1,
  "actions": [
    { "service": "auth", "name": "ACCESS_TOKENS_SECRET", "action": "keep" },
    { "service": "edge", "name": "EDGE_NATIVE_BLOB_KEY", "action": "create", "source": "generated", "reason": "new-in-revision" }
  ],
  "problems": [
    { "kind": "lost", "name": "PASSWORDS_SECRET", "services": ["auth"] }
  ]
}

reason — одно из first-install, new-in-revision, policy-generate, forced-by-flag, fill-shared, local-throwaway или restart-install. source — generated или stored.

Генерация того, что план отклоняет

Когда план останавливается, потому что секрет выглядит потерянным, правильный выход — восстановить его из бэкапа. Если вы знаете, что ничего из сохранённого от него не зависит, подтвердите генерацию по имени:

versola configure vps <version> --auth-url https://id.example.com --postgres-host 127.0.0.1:5432 --generate-missing EDGE_NATIVE_BLOB_KEY

• Флаг принимает имена через запятую. Он никогда сам не делает группу ключей полной: группа генерируется, только если названы все её члены.
• Генерация секрета, к которому привязаны данные (PASSWORDS_SECRET, REFRESH_TOKENS_SECRET, CLIENT_SECRETS_SECRET, EDGE_TOKEN_ENC_KEY), делает нечитаемым всё, что он защищает: перестают работать все входы, либо все refresh-токены, либо все сохранённые секреты клиентов.
• --allow-legacy-secrets — для релиза, чей образ tools не пишет схему. Тогда CLI не отличает новое от потерянного и на vps отказывается, если только OpenBao не пуст и деплой не записан. С флагом применяется старое правило: всё, чего нет, генерируется, потеряно оно или нет.

Ротация секрета

Существующее значение всегда побеждает, поэтому ротация — это запись нового значения в OpenBao и повторный configure. Используйте bao kv patch, потому что kv put заменяет весь путь:

docker exec -it -e BAO_ADDR=http://127.0.0.1:8200 -e BAO_TOKEN=<root token> versola-openbao-vps \
  bao kv patch -mount=secret versola/vps/auth SESSIONS_SECRET='<new value>'

Затем выполните versola configure vps <current-version> с вашими обычными флагами и versola up. Сначала посмотрите результат через versola secrets plan.

Что можно заменить, зависит от секрета:

Пара ключей utils

central регистрирует конфиденциального клиента utils для инструментов вроде loadgen provision и versola-cli; он аутентифицируется через private_key_jwt и DPoP. Его пара ключей разделена: публичная половина (UTILITY_CLIENT_PUBLIC_JWK) попадает в конфигурацию central, а приватная хранится в secret/versola/<target>/utils (поле UTILITY_CLIENT_PRIVATE_JWK) и записывается в utils.private-key.jwk в бандле.

central применяет публичную половину при каждом запуске, поэтому пересозданный приватный ключ не совпал бы с ней и заблокировал бы всё, что аутентифицируется как utils. Поэтому CLI обрабатывает эту группу сам (skip-utils в плане): приватный ключ, уже лежащий в OpenBao, побеждает, а публичная половина для central выводится из него. Чтобы использовать существующий ключ, сохраните его по пути utils до первого configure либо, с генератором в Kubernetes, передайте его переменной окружения UTILS_PRIVATE_KEY_JWK (содержимое utils.private-key.jwk). Ключ должен быть приватным JWK типа EC P-256.

Клиент utils, который старый релиз создал с client_secret, нельзя переключить на ключ: метод аутентификации клиента фиксируется при создании. Удалите клиент utils, чтобы следующий запуск зарегистрировал его заново, либо сохраните старый bootstrap.utility-client.

Bootstrap-значения применяются один раз

Значения блока bootstrap у central заполняют базу при первом запуске на пустой базе: клиент и пресет central-admin, edge, набор JWK, документ метаданных, секрет ресурса central и клиент utils. Последующие изменения конфигурации не меняют сохранённое. Меняйте эти объекты в админ-консоли, а для секретов выше следуйте таблице в разделе Ротация секрета.

Первый вход администратора — отдельная история: auth создаёт пользователя admin с временным ADMIN_BOOTSTRAP_PASSWORD, действующим 24 часа. Перезапуск auth после истечения устанавливает новый.

Дальше

• Деплой на VPS: настройте OpenBao сами и сохраните учётные данные AppRole.
• Справочник CLI: флаги secrets login, test и plan.
• Конфигурация: где каждый секрет попадает в файлы конфигурации.