hrbox-helm-chart/CHANGELOG.md

# Changelog

All notable changes to the HRBox Helm chart will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [3.0.0] - 2026-09-02

Синхронизация с продовым окружением HRBox и приведение чарта в порядок:
добавлен плеер учебных материалов, секреты перестали лежать открытым текстом
в спеках подов, вместо девяти одинаковых блоков ресурсов — один хелпер,
а неполная конфигурация теперь останавливает установку с внятным текстом.

### Added

#### Nanabush Player

Проигрыватель учебных материалов: SCORM 1.2 и 2004, cmi5, xAPI, нативные
курсы, тесты и эссе.

- `09-nanabush-player.yaml` — Deployment и Service, образ `nanabush-player:1.0.11`
- `00-nanabush-player-secret.yaml` — ключи launch-тикета и сессии
- маршрут `/nanabush-player` на основном Ingress
- настройки: `app.nanabushPlayer` в values.yaml, ресурсы — `resources.nanabushPlayer`
- переменные `NANABUSH_PLAYER_*` в HRBox и `PLAYER_*` в самом плеере

On-premise-топология отличается от облачной: выделенного поддомена нет,
плеер монтируется на основной домен под путём. Отсюда два ограничения,
описанные в README: нет изоляции cookie между HRBox и содержимым курсов,
и нужны синхронизированные часы (тикет живёт 5 минут).

Три независимых переключателя (`enabled`, `ingress.enabled`,
`deployment.enabled`) сохранены для аварийного отката; чарт не даёт оставить
маршрут без пода или раскатку без маршрута.

#### Проверка конфигурации

- `00-validate.yaml` — объектов не создаёт, но останавливает рендер, если
  не заполнены обязательные значения, использованы ключи из версии 2.x или
  нарушены инварианты плеера. Сообщения на русском, с указанием, что править.

#### Секрет приложения

- `00-app-secret.yaml` — единый Secret с паролями и ключами. Контейнеры
  читают его через `secretKeyRef`, поэтому `kubectl get deploy -o yaml`
  больше не показывает пароль базы и ключ шифрования.
- `secrets.existingSecret` — подстановка Secret, созданного вне чарта.

#### Новые компоненты и возможности

- `09-file-processor-video.yaml` — отдельный пул конвертации видео с
  собственным профилем ресурсов, `nodeSelector` и `tolerations`
  (`app.videoConverter.enabled`, по умолчанию выключен)
- `02-web-pdb.yaml` — PodDisruptionBudget для `web`, создаётся начиная с
  двух реплик
- `01-otel-configmap.yaml` и sidecar-коллектор в поде `web`
  (`app.tracing.enabled`)
- `01-nginx-assetlinks.yaml` — привязка мобильных приложений к домену
  (`app.mobileApps`)
- `templates/NOTES.txt` — что делать после установки, с готовыми командами
  и предупреждениями о небезопасных настройках

#### Новые переменные окружения

- `NATS_STREAM_REPLICAS` — число реплик JetStream-стримов по размеру кластера
- `TELEGRAM_API_URL`, `AUTH_GOOGLE_ENABLED`
- `LIVEKIT_URL`, `LIVEKIT_API_KEY`, `LIVEKIT_API_SECRET` — видеозвонки
- `APP_INTERNAL_URL` — внутренний адрес HRBox для конвертера
- `VIDEO_CONVERTER_ENABLED` — отдельно для каждого пула
- `SENDER_ENV`, `IMAGE_RESIZE_MAX_PARALLEL`, `OTEL_*`

### Changed

#### Структура values.yaml

- все образы собраны в блок `image` — обновление версии сервиса стало
  правкой одной строки
- `imagePullSecrets` вынесен в настройки, `regsecret` больше не захардкожен
- ключи приведены к camelCase: `file_processor` → `fileProcessor`,
  `custom_policy` → `customPolicy`
- `resources` дополнен компонентами `fileProcessor`, `fileProcessorVideo`,
  `nanabushPlayer`, `dragonfly`, `nats`
- адреса внутренних сервисов (`app.geonames.url`, `app.goworker.url`,
  `app.kedoca.url`, `app.redis.host`, `app.nats.url`) по умолчанию пустые и
  выводятся из имён, которые создаёт сам чарт. Раньше это были захардкоженные
  строки `hrbox-*`, которые молча ломались при `nameOverride`. Явно заданное
  значение по-прежнему используется как есть, поэтому старые values работают
  без правок. Выключение `dragonfly` или `nats` без указания внешнего адреса
  теперь останавливает установку

#### Шаблоны

- `_resources.tpl`: девять почти одинаковых define заменены одним
  `hrbox.resources`; незаданные поля не рендерятся
- `_helpers.tpl`: убрано около сотни строк мёртвого кода (хелперы `nats.*`,
  которыми ничего не пользовалось и которые ссылались на несуществующий
  `nats.k8sClusterDomain`); добавлены `hrbox.component`, `hrbox.labels`,
  `hrbox.selectorLabels`, `hrbox.secretEnv` и хелперы плеера
- у всех объектов появились стандартные лейблы `app.kubernetes.io/*`;
  лейбл `app` сохранён, привычные `kubectl get pods -l app=worker` работают
- селекторы Deployment не менялись — обновление 2.x → 3.0 не пересоздаёт
  объекты
- аннотации `checksum/*` перезапускают поды при изменении конфигурации nginx
  или секрета приложения
- образы, порты и таймауты вынесены из шаблонов в values.yaml

#### nginx

Набор `location` синхронизирован с продовым:

- `/healthz` и `/health-check` — под них настроены пробы пода `web`
  (раньше проверялся только TCP-порт)
- `/api/v1/integration/commit` — потоковая загрузка оргструктуры из 1С без
  буферизации тела, лимит 500 МБ
- `/ai/` — увеличенные таймауты
- `/.well-known/assetlinks.json` и `/.well-known/apple-app-site-association`
- `/frontend/sw.js` — корректные заголовки service worker
- кеширование шрифтов
- убран TLSv1 и TLSv1.1

#### Версии образов

| Компонент | Было | Стало |
|---|---|---|
| chatbox | 3.0 | 5.18 |
| goworker | 2.7 | 3.21.2 |
| kedoca | 0.8 | 1.0.6 |
| geonames | 3.1 | 3.3 |
| file-processor | 1.0 | 1.4.6 |
| nanabush-player | — | 1.0.11 |

#### Джобы

- имя содержит номер ревизии релиза: в `kubectl get jobs` видно, какой выкат
  запускал миграции, а повторный `upgrade` не спотыкается об уже существующий
  объект
- `ttlSecondsAfterFinished` — час у обеих джоб (было 100 секунд у миграций и
  ничего у обновления кластера): логи упавшей джобы успевают дожить до того,
  как их посмотрят

#### Переименования файлов

- `03-websocket.yaml` → `03-chatbox.yaml` (содержимое было chatbox с версии 2.0)
- `09-geonames.yml` → `09-geonames.yaml`
- `99-update-cluser-job.yaml` → `99-update-cluster-job.yaml`

### Fixed

- **Общий секрет в коде чарта.** `SERVICES_INTERNAL_SECRET` имел захардкоженное
  значение по умолчанию, то есть все установки, где его не заполнили, работали
  на одном и том же секрете межсервисной аутентификации. Теперь значение
  обязательно.
- **Домен кластера игнорировался.** Маршруты кластера NATS были захардкожены
  на `cluster.local`, хотя `cluster.domain` присутствовал в values и
  использовался в соседней переменной. На кластере с нестандартным доменом
  ноды не находили друг друга.
- **`CLUSTER_ADVERTISE` без сегмента `svc`.** Имя не резолвилось, и ноды NATS
  объявляли соседям недостижимый адрес.
- **Рассинхрон реплик NATS.** `nats.replicas` и `nats.cluster.replicas`
  задавались независимо; при расхождении часть нод не входила в кластер.
  Теперь чарт требует их совпадения.
- **Пробы `web` не проверяли приложение.** Проверялся TCP-порт 9000, поэтому
  под с неработающим PHP считался готовым. Теперь readiness ходит в
  `/health-check` через FPM.
- Пароли и ключи больше не видны в спеках Deployment.
- `imagePullPolicy` у части сервисов был `Always` на закреплённых тегах —
  лишние обращения к реестру при каждом рестарте пода.

### Removed

- `secrets` больше не имеет значений по умолчанию — пустые ключи
  останавливают установку вместо тихого запуска на предсказуемых секретах
- убраны неиспользуемые хелперы `nats.name`, `nats.fullname`, `nats.chart`,
  `nats.labels`, `nats.selectorLabels`, `nats.clusterAdvertise`,
  `nats.clusterRoutes`, `nats.extraRoutes`, `nats.tlsConfig`, `tplvalues.render`
- `SENDGRID_API_KEY` — не используется в on-premise

### Migration Guide

#### Переход с 2.x на 3.0

Все переехавшие ключи чарт распознаёт и сообщает, куда именно они переехали,
поэтому надёжнее всего запустить `helm template` и править по сообщениям.

**Шаг 1. Перенесите образы в блок `image`**

```yaml
# было
app:
  image: "cr.yandex/.../hrbox:latest"
  chatbox:
    image: "cr.yandex/.../hrbox-chatbox:3.0"
  goworker:
    image: "cr.yandex/.../hrbox-goworker:2.7"
  kedoca:
    image: "cr.yandex/.../hrbox-kedoca:0.8"
  file_processor:
    image: "cr.yandex/.../hrbox-file-processor:1.0"
    replicas: 1

# стало
image:
  hrbox: "cr.yandex/.../hrbox:latest"
  chatbox: "cr.yandex/.../hrbox-chatbox:5.18"
  goworker: "cr.yandex/.../hrbox-goworker:3.21.2"
  kedoca: "cr.yandex/.../hrbox-kedoca:1.0.6"
  fileProcessor: "cr.yandex/.../hrbox-file-processor:1.4.6"
app:
  replicas:
    fileProcessor: 1
```

**Шаг 2. Переименуйте ключи**

| Было | Стало |
|---|---|
| `app.file_processor` | `app.fileProcessor` |
| `app.custom_policy` | `app.customPolicy` |
| `app.custom_policy.privacy_url` | `app.customPolicy.privacyUrl` |
| `app.custom_policy.terms_url` | `app.customPolicy.termsUrl` |
| `app.goworker.replicas` | `app.replicas.goworker` |
| `app.kedoca.replicas` | `app.replicas.kedoca` |
| `app.goworker.sentryDsn` | `app.sentry.goworkerDsn` |
| `app.chatbox.sentryDsn` | `app.sentry.chatboxDsn` |
| `nats.image` | `image.nats` |

**Шаг 3. Заполните ключи плеера**

```bash
openssl rand -base64 48   # app.nanabushPlayer.keys.ticketHs256
openssl rand -base64 48   # app.nanabushPlayer.keys.sessionHs256
```

Ключи должны отличаться друг от друга.

**Шаг 4. Проверьте `secrets.servicesInternalSecret`**

Если поле было пустым, установка работала на общем значении по умолчанию.
Сгенерируйте своё: `openssl rand -base64 48`. После обновления перезапустятся
все сервисы, обменивающиеся внутренними вызовами, — это ожидаемо.

**Шаг 5. Проверьте рендер и обновитесь**

```bash
helm template hrbox .helm -f values.yaml > /dev/null
helm upgrade hrbox .helm -n hrbox -f values.yaml
```

**Шаг 6. Включите плеер**

Порядок первого включения и проверки — в README, раздел «Nanabush Player».

#### Breaking Changes

1. **Ключи `values.yaml` переехали.** Установка останавливается с подсказкой,
   молча ничего не игнорируется.
2. **`secrets.*` стали обязательными.** Установка без них не пройдёт.
3. **Появился Nanabush Player.** Это дополнительный под, Service, Secret и
   маршрут; учтите ресурсы кластера. Плеер требует синхронизированного времени
   на нодах.
4. **Пробы `web` стали строже.** Под, где PHP-FPM не отвечает по HTTP, теперь
   не проходит readiness. Если приложение отдаёт `/health-check` иначе,
   проверьте это до обновления.
5. **`app.replicas` расширился** полями `goworker`, `kedoca`, `fileProcessor`,
   `fileProcessorVideo`; соответствующие `replicas` внутри сервисов удалены.

---

## [2.0.0] - 2026-01-30

Масштабная актуализация чарта на основе продового окружения hrbox. Синхронизированы версии компонентов, добавлены новые микросервисы, обновлены переменные окружения.

### Added

#### Новые микросервисы

- **Goworker** (`09-goworker.yaml`) - Сервис интеграций с мессенджерами
  - Образ: `hrbox-goworker:2.7`
  - Prometheus metrics на порту 8686
  - Настройки: `app.goworker` в values.yaml
  - Переменные: `GOWORKER_URL`, `GOWORKER_PUSH_MIN_INTERVAL`, `GOWORKER_SENTRY_DSN`

- **Kedoca** (`09-kedoca.yaml`) - Сервис электронной подписи
  - Образ: `hrbox-kedoca:0.8`
  - Поддержка ГОСТ и OpenSSL
  - Монтирование Kubernetes Secret с CA сертификатами
  - Настройки: `app.kedoca` в values.yaml
  - Переменные: `KEDOCA_URL`, `TSP_URL`, `ROOT_CA_PASS`, `KEDO_ENGINE`, `KEDO_ALGORITHM`, `KEDO_PKEYOPT`

- **File Processor** (`09-file-processor.yaml`) - Обработка файлов (конвертация, ресайз изображений)
  - Образ: `hrbox-file-processor:1.0`
  - Настройки: `app.file_processor` в values.yaml
  - `VIDEO_CONVERTER_ENABLED` захардкожен в `false` (видео-конвертация отключена)

#### Новые переменные окружения

- `SERVICES_INTERNAL_SECRET` - Секрет для межсервисной коммуникации
- `AI_DOCS_INDEX_ENABLED` - Включение индексации документов через AI
- `AI_SEMANTIC_INDEX_ENABLED` - Семантическое индексирование
- `AI_SEMANTIC_INDEX_USE_BATCH` - Пакетная обработка при индексации
- `CHATBOX_SENTRY_DSN` - Sentry DSN для Chatbox
- `CHATBOX_WRAPPING_KEY` - часть ключа для шифрования чатов
- `SINGLE_TENANT` - Режим single-tenant для on-premise установок
- `TSP_URL` - URL службы временных меток (http://qs.cryptopro.ru/tsp/tsp.srf)

#### Новые секреты

- `secrets.servicesInternalSecret` - Секрет для защиты внутренних API между микросервисами
  - Генерация: `openssl rand -base64 48`

#### Resource definitions

Добавлены resource limits/requests для новых сервисов:
- `resources.goworker` - CPU: 0.1-0.3, Memory: 196Mi-256Mi
- `resources.kedoca` - CPU: 0.1-0.5, Memory: 196Mi-256Mi
- `resources.chatbox` - CPU: 0.3, Memory: 96Mi-192Mi

### Changed

#### Обновление версий

- **Chart version**: `1.2.0` → `2.0.0`
- **App version**: `2.0.0` → `3.0.0`

#### Chatbox (ранее WebSocket)

- **Образ обновлен**: `hrbox-websocket:2.1` → `hrbox-chatbox:3.0`
- **Переименован deployment**: `{chart}-websocket` → `{chart}-chatbox`
- **Переименован service**: `{chart}-websocket` → `{chart}-chatbox`
- **Переименована конфигурация**:
  - `app.replicas.websocket` → `app.replicas.chatbox`
  - Файл остался `03-websocket.yaml` но содержимое обновлено на chatbox

#### Архитектура

- Все микросервисы теперь **обязательны** (не опциональны)
  - Удалены условия `{{- if .Values.app.goworker }}` из templates
  - Удалены `| default` значения для обязательных параметров
  - Goworker, Kedoca, File Processor, Chatbox всегда деплоятся

#### Templates

- `_envs.tpl`:
  - Упрощена логика переменных окружения
  - Удалены условия для обязательных сервисов
  - Добавлен блок `envs_kedoca` для настроек криптографии

- `_resources.tpl`:
  - Добавлены определения: `goworker_resources`, `kedoca_resources`, `chatbox_resources`

- `_helpers.tpl`:
  - Без изменений, сохранена совместимость

### Removed

#### Устаревшие компоненты

- **WebSocket сервис** - Полностью заменен на Chatbox 3.0
  - Удалено: `app.replicas.websocket` из values.yaml
  - Удалено: `resources.websocket` из values.yaml

#### Устаревшие интеграции

- **OpenAI** - Интеграция удалена, используйте HRBox Hub
  - Удален блок: `app.ai.openai` с полями `apiKey`, `proxyKey`, `baseUri`
  - Удалены переменные: `OPENAI_API_KEY`, `OPENAI_PROXY_KEY`, `OPENAI_BASE_URI`

### Migration Guide

#### Миграция с версии 1.x на 2.0

**Шаг 1: Обновите values.yaml**

```yaml
# 1. Переименуйте websocket в chatbox
app:
  replicas:
    # websocket: 2  # УДАЛИТЬ
    chatbox: 2      # ДОБАВИТЬ

# 2. Добавьте новые сервисы
app:
  goworker:
    url: "http://hrbox-goworker:8686"
    image: "cr.yandex/crphnph9c2s776j32sjd/hrbox-goworker:2.7"
    replicas: 2
    pushMinInterval: "5m"
    sentryDsn: ""

  kedoca:
    url: "http://hrbox-kedoca:8558"
    image: "cr.yandex/crphnph9c2s776j32sjd/hrbox-kedoca:0.8"
    replicas: 1
    rootCaPass: "hrbox"
    engine: "gost"
    algorithm: "gost2012_256"
    pkeyopt: "paramset:A"
    secretName: ""

  file_processor:
    image: "cr.yandex/crphnph9c2s776j32sjd/hrbox-file-processor:1.0"
    replicas: 1

  chatbox:
    image: "cr.yandex/crphnph9c2s776j32sjd/hrbox-chatbox:3.0"
    sentryDsn: ""

# 3. Добавьте новый секрет
secrets:
  servicesInternalSecret: ""  # Сгенерируйте: openssl rand -base64 48

# 4. Удалите OpenAI (если был настроен)
app:
  ai:
    # openai:  # УДАЛИТЬ весь блок
    #   apiKey: ""
    #   proxyKey: ""
    #   baseUri: ""
```

**Шаг 2: Сгенерируйте новый секрет**

```bash
# Генерация servicesInternalSecret
openssl rand -base64 48
```

**Шаг 3: Обновите Chart**

```bash
helm upgrade hrbox .helm/ \
  --namespace hrbox \
  --values your-values.yaml
```

**Шаг 4: Проверьте новые поды**

```bash
# Проверка новых сервисов
kubectl get pods -n hrbox -l app=goworker
kubectl get pods -n hrbox -l app=kedoca
kubectl get pods -n hrbox -l app=file-processor
kubectl get pods -n hrbox -l app=chatbox

# Убедитесь что старый websocket удален
kubectl get pods -n hrbox -l app=websocket  # Должно быть пусто
```

### Breaking Changes

⚠️ **Критические изменения, требующие действий:**

1. **WebSocket → Chatbox**: Обязательное переименование конфигурации
   - Service name изменился с `{chart}-websocket` на `{chart}-chatbox`
   - Если есть зависимости от старого имени сервиса - обновите их

2. **Новые обязательные сервисы**: Goworker, Kedoca, File Processor, Chatbox всегда деплоятся
   - Требуются дополнительные ресурсы кластера
   - Проверьте доступность ресурсов перед обновлением

3. **Новый секрет**: `secrets.servicesInternalSecret` обязателен
   - Приложение не запустится без этого секрета
   - Сгенерируйте перед деплоем

4. **OpenAI удален**: Используйте HRBox Hub для AI интеграций
   - Миграция на Hub API требуется если использовали OpenAI

### Notes

- Все образы сервисов используют registry: `cr.yandex/crphnph9c2s776j32sjd/`
- Для работы Kedoca с сертификатами создайте Kubernetes Secret и укажите в `kedoca.secretName`
- Goworker экспортирует метрики Prometheus на `/metrics` (порт 8686)
- File Processor деплоится с `VIDEO_CONVERTER_ENABLED=false` (видео-конвертация отключена)

---

## [1.2.0] - Previous version

Упрощенный Helm chart для on-premise установок HRBox.

### Initial Features

- Базовые компоненты: web, worker, websocket, geonames, conductor
- PostgreSQL, Redis, NATS JetStream
- Ingress с TLS
- ConfigMaps и resource limits
- Migration и update jobs

---

[3.0.0]: #300---2026-09-02
[2.0.0]: #200---2026-01-30
[1.2.0]: #120---previous-version