# 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 работает в облаке: добавлен плеер учебных
материалов, пароли и ключи уехали в Secret, повторяющиеся куски шаблонов
заменены одним хелпером, а неполная конфигурация теперь останавливает
установку с понятным сообщением.

### 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`, ресурсы `resources.nanabushPlayer`
- переменные `NANABUSH_PLAYER_*` в HRBox и `PLAYER_*` в самом плеере

В on-premise выделенного поддомена нет, поэтому плеер стоит на основном
домене по пути. Отсюда два ограничения, они описаны в README: cookie HRBox
доступны содержимому курсов, и нужны синхронизированные часы — тикет живёт
5 минут.

Для быстрого отката оставлены три переключателя: `enabled`,
`ingress.enabled`, `deployment.enabled`. Маршрут без пода или включённый
плеер без маршрута чарт не пропустит.

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

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

#### Secret приложения

- `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` и коллектор OpenTelemetry рядом с `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 или Secret приложения
- образы, порты и таймауты вынесены из шаблонов в 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` было
  значение по умолчанию, зашитое в чарт: все, кто его не заполнил, работали
  на одном и том же секрете межсервисной аутентификации. Теперь значение
  обязательное.
- **`cluster.domain` не использовался.** Маршруты кластера NATS были зашиты
  на `cluster.local`, хотя параметр в 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