# KUMA: история работ

Дата: 2026-08-26

## Цель

Создать сервис KUMA для алертов по whitelist:

- https://whitelist.nodejsk8s.services.ngcloud.ru/

Первый этап: stateless-хранилище. В дальнейшем планируется MariaDB.

## Git

Локальный каталог проекта:

- `/home/naeel/nubes/kuma`

Удалённый Git-репозиторий:

- `https://gitea.services.ngcloud.ru/forcloud/kuma.git`

Репозиторий был пустым, затем клонирован в локальный каталог. Remote `origin` настроен на указанный адрес.

## Реализация

Создан минимальный Flask HTTP-сервис:

- `GET /` возвращает JSON с параметрами сервиса и MariaDB.
- `GET /health` возвращает состояние сервиса.
- `GET /mariadb` возвращает параметры MariaDB.
- Пароль MariaDB не возвращается; выводится только `passwordConfigured`.
- Конфигурация задаётся переменными окружения.

Файлы:

- `Dockerfile`
- `app.py`
- `requirements.txt`

## Docker

Локальный образ:

- `kuma:0.1.0`

Опубликованный образ:

- `gitea.services.ngcloud.ru/forcloud/kuma:0.1.0`

Digest опубликованного образа:

- `sha256:15e7ef5c9e125c81222cffe1c8c4c278c9c148fc432368f01662b4cdbd772f4e`

Сборка образа и проверка endpoint `/mariadb` выполнены успешно.

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

```json
{
  "MARIADB_DATABASE": "db-kuma",
  "MARIADB_HOST": "mariadb",
  "MARIADB_PORT": "3306",
  "MARIADB_USER": "userkuma",
  "MARIADB_VERSION": "9.4.0",
  "PORT": "5000"
}
```

`MARIADB_PASSWORD` должен передаваться как секрет окружения и не храниться в истории, документации или Docker-образе.

## Ответ сервиса

```json
{
  "mariadb": {
    "database": "db-kuma",
    "host": "mariadb",
    "passwordConfigured": true,
    "port": 3306,
    "user": "userkuma",
    "version": "9.4.0"
  },
  "service": "kuma",
  "state": "stateless",
  "target": "https://whitelist.nodejsk8s.services.ngcloud.ru/",
  "version": "0.1.0"
}
```

## Gitea Container Registry

Registry endpoint:

- `https://gitea.services.ngcloud.ru/v2/`

Проверка без корректного токена возвращала `401 Unauthorized`. С действительным токеном Registry вернул `HTTP 200`. Образ успешно опубликован и манифест проверен.

## Ограничения текущего этапа

- Сервис пока не подключается к MariaDB.
- Состояние не сохраняется.
- Логика получения и отправки алертов whitelist ещё не реализована.

## Проверка whitelist API

Endpoint `https://whitelist.nodejsk8s.services.ngcloud.ru/v2/app` без авторизации отвечает:

```text
HTTP 302
Location: /v2/login
Found. Redirecting to /v2/login
```

В KUMA добавлен stateless endpoint `GET /check`, который запрашивает whitelist без автоматического перехода по redirect и возвращает статус, `Location` и тело ответа.

Для авторизации предусмотрена переменная `WHITELIST_TOKEN`; при её наличии KUMA передаёт заголовок `Authorization: Bearer <token>`.

Добавлены переменные:

```text
WHITELIST_URL=https://whitelist.nodejsk8s.services.ngcloud.ru/v2/app
WHITELIST_TIMEOUT=10
```

## Версионирование

Версия KUMA установлена в `0.0.3`. В дальнейшем увеличивается только третья позиция: `0.0.*`.

## SMTP-алерты

После включения IMAP в настройках Яндекс Почты SMTP-аутентификация успешно прошла для адресов аккаунта через `smtp.yandex.ru:465` с SSL.

В KUMA добавлен `POST /alert`: он получает ответ whitelist и отправляет его по SMTP на `SMTP_TO`. Пароль SMTP хранится только в `.env`.

Добавлена переменная:

```text
SMTP_TO=tazet@narod.ru
SMTP_SUBJECT_PREFIX=[KUMA]
```

Для сортировки почты добавлен префикс темы `[KUMA]`. `SMTP_FROM` остаётся реальным адресом SMTP-аккаунта; несуществующий адрес отправителя не используется.

Добавлен UI на `/` для ручной проверки whitelist и отправки алерта. Whitelist URL предустановлен: `https://whitelist.nodejsk8s.services.ngcloud.ru/v2/app`.

`POST /alert` больше не отправляет HTML страницы Keycloak. При редиректе отправляется краткое сообщение со статусом и URL авторизации; обычный ответ ограничен 4000 символами.