Перенесены секреты из .env в SM
This commit is contained in:
mi
@@ -0,0 +1,206 @@
|
||||
# Selectel Secrets Manager для HAN Chat
|
||||
|
||||
## Модель
|
||||
|
||||
`han-secrets` читает только `SECRETS_SOURCE=selectel|file` из обычного `.env`,
|
||||
выбирает соответствующую root-only JSON-карту и вызывает `secrets_loader.py`.
|
||||
Загрузчик получает project-scoped IAM token, читает объявленные секреты и
|
||||
создаёт в `/run/han-chat/secrets`:
|
||||
|
||||
- отдельные файлы с каноническими именами для Compose secrets;
|
||||
- узкие service dotenv-файлы для диагностики состава без вывода значений;
|
||||
- `manifest` вида `NAME=/absolute/path`, используемый валидатором.
|
||||
|
||||
Каталог `/run` находится в tmpfs и имеет режим `0700`. Канонические файлы имеют
|
||||
`0444`: локальные пользователи не могут пройти через root-only каталог, а
|
||||
не-root UID контейнера может прочитать только явно смонтированный Compose
|
||||
secret. Значения не передаются через Docker Config.Env, argv, общий `.env` или
|
||||
логи. После полного root/docker-компромисса runtime-значения извлекаемы — это
|
||||
ограничение модели, а не гарантия Secret Manager.
|
||||
|
||||
Сбой Selectel никогда автоматически не включает file fallback. Уже работающие
|
||||
контейнеры продолжают использовать текущие значения; новый sync завершается
|
||||
fail-closed.
|
||||
|
||||
## 1. Ресурсы Selectel
|
||||
|
||||
1. Создайте отдельный проект `han-chat-secrets-prod`.
|
||||
2. Создайте сервисного пользователя `han-chat-secrets-reader`.
|
||||
3. Назначьте ему `member` только в этом проекте. Не выдавайте account scope,
|
||||
`iam.admin` и доступ к другим production-ресурсам. Если Selectel добавит
|
||||
отдельную read-only роль Secrets Manager, замените `member` на неё.
|
||||
4. Ограничьте обращения к `api.selectel.ru` исходящим IP ВМ, если функция
|
||||
доступна в аккаунте.
|
||||
5. Включите экспорт audit logs. Контролируйте события `secrets.secret*` и
|
||||
`secrets.secret_version*`; alert на delete, смену current version вне окна,
|
||||
массовые чтения и обращения не от штатного пользователя/IP.
|
||||
6. Выполните canary и убедитесь, что provider audit содержит metadata операции,
|
||||
но не value, Base64 payload, IAM token или response body.
|
||||
|
||||
Secrets Manager принимает project-scoped IAM token в `X-Auth-Token`. Token
|
||||
живёт до 24 часов, но загрузчик использует его только в памяти одного запуска.
|
||||
TLS и redirect policy отключать нельзя.
|
||||
|
||||
## 2. Каталог секретов
|
||||
|
||||
Скопируйте `config.example.json` в
|
||||
`/etc/han/secrets/production-like.selectel.json` и замените account, username,
|
||||
project, region и `remote`. Каноническое имя слева обязано совпадать с
|
||||
Compose/validator; `remote` — неизменяемый ключ в Selectel.
|
||||
|
||||
Используйте консервативные provider keys с дефисами, например:
|
||||
|
||||
- `han-chat-prod-pg-han-app-dsn`, `han-chat-prod-pg-bitrix-local-dsn`,
|
||||
`han-chat-prod-pg-bitrix-sync-dsn`, `han-chat-prod-pg-sms-dsn`,
|
||||
`han-chat-prod-pg-keycloak-password`, `han-chat-prod-pg-backup-dsn`;
|
||||
- `han-chat-prod-redis-api-password`, `han-chat-prod-redis-safety-password`,
|
||||
`han-chat-prod-redis-health-password`, а также три credential-bearing URL;
|
||||
- `han-chat-prod-message-safety-token`, `han-chat-prod-bitrix-internal-token`,
|
||||
`han-chat-prod-bitrix-forward-token`, `han-chat-prod-bitrix-sync-token`,
|
||||
`han-chat-prod-keycloak-settings-token`, `han-chat-prod-sms-service-token`;
|
||||
- Keycloak bootstrap password, OTP HMAC и mock code только для среды, где mock
|
||||
действительно включён;
|
||||
- Bitrix client secret, application token и token encryption key;
|
||||
- пары S3 app access/secret key;
|
||||
- i-Digital API key и callback username/password.
|
||||
|
||||
Одинаковые пары env (`BITRIX_LOCAL_APP_INTERNAL_TOKEN` /
|
||||
`BITRIX_INTERNAL_API_TOKEN`, `BITRIX_API_FORWARD_TOKEN` /
|
||||
`BITRIX_API_INBOX_TOKEN`, `SMS_SERVICE_TOKEN` /
|
||||
`KEYCLOAK_SMS_SERVICE_TOKEN`) должны ссылаться на один `remote`.
|
||||
|
||||
`literal: ""` разрешён только для заведомо пустого optional-параметра, например
|
||||
OTLP auth при self-hosted SigNoz или выключенного CAPTCHA server key. Секреты
|
||||
не записывайте в JSON. Не заводите planned/unused Message Safety DB, quarantine
|
||||
S3 и Bitrix sync credentials до появления потребляющего кода.
|
||||
|
||||
Загружайте значения в Selectel через скрытый prompt/stdin. Не передавайте value
|
||||
позиционным аргументом CLI и не включайте `set -x`/`curl -v`.
|
||||
|
||||
## 3. Установка на ВМ
|
||||
|
||||
Повторный запуск `deployment/scripts/setup-vm.sh` после копирования проекта
|
||||
устанавливает loader, launcher, systemd template и этот runbook. Вручную:
|
||||
|
||||
```sh
|
||||
sudo install -d -m 0700 /etc/han/secrets /etc/han/credentials
|
||||
sudo install -d -m 0755 /usr/local/lib/han-secrets
|
||||
sudo install -m 0750 secrets_loader.py han-secrets /usr/local/lib/han-secrets/
|
||||
sudo install -m 0750 han-compose /usr/local/bin/han-compose
|
||||
sudo install -m 0644 han-secrets@.service /etc/systemd/system/
|
||||
sudo install -m 0600 config.example.json \
|
||||
/etc/han/secrets/production-like.selectel.json
|
||||
```
|
||||
|
||||
Обычный `/opt/han-chat/backend/.env` содержит только несекретные параметры.
|
||||
Штатный режим:
|
||||
|
||||
```dotenv
|
||||
SECRETS_SOURCE=selectel
|
||||
APP_ENV=production-like
|
||||
```
|
||||
|
||||
## 4. Bootstrap credential
|
||||
|
||||
Не храните пароль service user в `.env` или JSON. На целевой ВМ:
|
||||
|
||||
```sh
|
||||
sudo systemd-creds encrypt --name=selectel-service-user-password - \
|
||||
/etc/han/credentials/production.selectel-password.cred
|
||||
sudo chmod 0600 /etc/han/credentials/production.selectel-password.cred
|
||||
```
|
||||
|
||||
Введите пароль через интерактивный stdin. Unit передаёт расшифрованный файл
|
||||
через приватный `$CREDENTIALS_DIRECTORY`. Root всё равно может его извлечь;
|
||||
после инцидента credential и все доступные ему секреты необходимо ротировать.
|
||||
|
||||
## 5. Проверка и запуск
|
||||
|
||||
Все команды, которым нужны Compose secrets, запускайте от root через wrapper:
|
||||
|
||||
```sh
|
||||
cd /opt/han-chat/backend
|
||||
sudo ./scripts/validate-env .env
|
||||
sudo systemctl daemon-reload
|
||||
sudo systemctl enable han-secrets@production.service
|
||||
sudo systemctl restart han-secrets@production.service
|
||||
sudo ./scripts/validate-env .env \
|
||||
--runtime-manifest /run/han-chat/secrets/manifest
|
||||
sudo deployment/secrets/han-compose config --quiet
|
||||
sudo deployment/secrets/han-compose up -d --wait
|
||||
```
|
||||
|
||||
Selectel sync запускается именно unit-файлом: только он предоставляет
|
||||
расшифрованный bootstrap credential через `$CREDENTIALS_DIRECTORY`.
|
||||
`han-compose` и ops-скрипты используют уже синхронизированный manifest и
|
||||
отказываются работать, если `SECRETS_SOURCE`/loader config не совпадают с
|
||||
runtime state. После смены source, provider version или JSON-карты сначала
|
||||
выполняйте `systemctl restart han-secrets@production.service`.
|
||||
|
||||
Не используйте `docker compose config` без `--quiet`, `docker inspect` для
|
||||
поиска конфигурации, `env`, `strace`, core dump или debug HTTP proxy. Проверка
|
||||
приёмки должна подтвердить отсутствие canary value в `docker inspect`, stdout,
|
||||
json logs, traces и shell history.
|
||||
|
||||
На выделенной только под HAN Chat ВМ после canary и проверки file fallback
|
||||
установите fail-closed ordering:
|
||||
|
||||
```sh
|
||||
sudo install -d -m 0755 /etc/systemd/system/docker.service.d
|
||||
sudo install -m 0644 \
|
||||
deployment/secrets/docker-han-secrets.conf.example \
|
||||
/etc/systemd/system/docker.service.d/han-secrets.conf
|
||||
sudo systemctl daemon-reload
|
||||
sudo systemctl restart docker
|
||||
```
|
||||
|
||||
После этого проведите reboot rehearsal: materializer должен завершиться до
|
||||
autorestart контейнеров. Ошибка Selectel намеренно блокирует Docker. На ВМ с
|
||||
другими workloads такой глобальный `Requires=` запрещён: нужен отдельный Docker
|
||||
daemon/VM, иначе fail-closed HAN остановит несвязанные системы.
|
||||
|
||||
## 6. Явный file fallback
|
||||
|
||||
Подготовьте отдельную карту
|
||||
`/etc/han/secrets/production-like.file.json`: скопируйте Selectel-карту,
|
||||
установите `"mode": "file"`, удалите `selectel` и `http`, добавьте:
|
||||
|
||||
```json
|
||||
"file": {
|
||||
"path": "/etc/han/break-glass/secrets.env",
|
||||
"max_bytes": 1048576
|
||||
}
|
||||
```
|
||||
|
||||
`secrets` map остаётся тем же. Для записей с `literal: ""` строка в fallback
|
||||
не нужна; остальные канонические ключи обязательны. Fallback parser не исполняет
|
||||
shell: запрещены `export`, substitutions, multiline, неизвестные и дублирующиеся
|
||||
ключи. Файл — `root:root 0600`.
|
||||
|
||||
При инциденте доставьте recovery-файл из защищённой офлайн-копии и только затем
|
||||
явно измените `.env`:
|
||||
|
||||
```dotenv
|
||||
SECRETS_SOURCE=file
|
||||
```
|
||||
|
||||
Перезапустите `han-secrets@production.service`, затем выполните
|
||||
validate/recreate через wrappers. После восстановления Selectel верните
|
||||
`SECRETS_SOURCE=selectel`, снова перезапустите unit, повторите проверки и
|
||||
удалите recovery-файл.
|
||||
Не храните его постоянно на ВМ: это вернуло бы исходный риск монолитного `.env`.
|
||||
|
||||
## 7. Ротация и rollback
|
||||
|
||||
1. Добавьте новую версию секрета, не меняя имя.
|
||||
2. Для canary при необходимости временно pin числовой `version` в JSON-карте.
|
||||
3. Выполните sync, validation и smoke без вывода конфигурации.
|
||||
4. Сделайте версию current, удалите pin, снова sync и пересоздайте только
|
||||
потребителей.
|
||||
5. Для rollback активируйте предыдущую provider version; не храните snapshot
|
||||
старого `.env`.
|
||||
|
||||
Selectel не позволяет удалить отдельную версию — только секрет целиком. Старые
|
||||
значения должны быть отозваны в PostgreSQL/S3/Bitrix/i-Digital после окна
|
||||
rollback. Все значения из прежнего `.env` считайте раскрытыми и ротируйте после
|
||||
перехода.
|
||||
Reference in New Issue
Block a user