chart 3.0

2026-09-05 19:07:31 +06:00
parent efc506e5de
commit 67786a0160
31 changed files with 348 additions and 773 deletions
@@ -1,9 +1,9 @@
 # HRBox Helm Chart

-Helm-чарт для развёртывания HRBox в собственном Kubernetes-кластере.
+Чарт для установки HRBox в свой Kubernetes-кластер.

-Чарт лежит в каталоге [`.helm`](.helm), настройки — в [`.helm/values.yaml`](.helm/values.yaml).
-Каждый параметр там прокомментирован; ниже — только то, что нужно сделать руками.
+Сам чарт лежит в [`.helm`](.helm), настройки — в [`.helm/values.yaml`](.helm/values.yaml).
+Каждый параметр там подписан, ниже — только то, что нужно сделать руками.

 ---

@@ -11,32 +11,32 @@ Helm-чарт для развёртывания HRBox в собственном

 | Компонент | Что делает | Порт |
 |---|---|---|
-| `web` | PHP-FPM + nginx: веб-интерфейс и API | 80 |
+| `web` | PHP-FPM и nginx: веб-интерфейс и API | 80 |
 | `worker` | фоновые задачи: файлы, почта, отчёты | — |
-| `conductor` | планировщик задач по расписанию (строго 1 реплика) | 8080 |
-| `chatbox` | вебсокеты чата и real-time уведомлений | 80 → 9797 |
-| `nanabush-player` | проигрыватель курсов: SCORM, cmi5, xAPI, нативные материалы | 8094 |
-| `goworker` | мессенджеры, push, синхронизация оргструктуры с 1С | 8686 |
+| `conductor` | задачи по расписанию, всегда 1 под | 8080 |
+| `chatbox` | вебсокеты чата и уведомлений | 80 → 9797 |
+| `nanabush-player` | плеер курсов: SCORM, cmi5, xAPI, нативные материалы | 8094 |
+| `goworker` | мессенджеры, пуши, синхронизация оргструктуры с 1С | 8686 |
 | `kedoca` | электронная подпись: КЭДО, МЧД | 8558 |
 | `geonames` | справочник городов, стран, часовых поясов | 8181 |
 | `file-processor` | конвертация документов и изображений | — |
-| `file-processor-video` | конвертация видео, выключена по умолчанию | — |
+| `file-processor-video` | конвертация видео, по умолчанию выключен | — |
 | `dragonfly` | Redis-совместимый кеш и сессии | 6379 |
 | `nats` | брокер сообщений JetStream | 4222 |

-Все три публичных маршрута живут на одном домене: `/` — приложение,
+Публичных маршрутов три, и все на одном домене: `/` — приложение,
 `/chatbox/` — вебсокеты, `/nanabush-player` — плеер курсов.

-## Что нужно от вас
+## Что нужно подготовить

 - Kubernetes 1.21+ и ingress-контроллер (nginx или traefik);
- PostgreSQL 14+ (с расширением Citus, если планируется шардирование);
+- PostgreSQL 14+ (с Citus, если планируется шардирование);
 - S3-совместимое хранилище: AWS S3, MinIO, Yandex Object Storage, VK Cloud;
 - SMTP-сервер;
- доступ к Docker-реестру HRBox и токен HRBox Hub — выдают сотрудники HRBox.
+- доступ к реестру образов HRBox и токен HRBox Hub — выдают сотрудники HRBox.

-PostgreSQL и S3 чарт не разворачивает: это состояние, которое переживает
-установку и требует собственного резервного копирования.
+Базу и хранилище чарт не разворачивает: это данные, которые живут дольше
+установки и требуют своего резервного копирования.

 ---

@@ -52,13 +52,13 @@ kubectl create secret docker-registry regsecret \
  --docker-email=not@used.com
 ```

-### 2. TLS-сертификат домена
+### 2. TLS-сертификат

 ```bash
 kubectl create secret tls hrbox-tls --cert=cert.pem --key=key.pem
 ```

-Или выпустите сертификат через cert-manager и укажите его Secret
+Либо выпустите сертификат через cert-manager и укажите его Secret
 в `ingress.tls.secretName`.

 ### 3. Ключи
@@ -72,15 +72,15 @@ openssl rand -hex 16
 openssl rand -base64 48
 ```

-`secrets.encryptionKey` — единственный ключ, потеря которого необратима:
-им зашифрованы пароли интеграций в базе. Сохраните его отдельно от кластера.
+`secrets.encryptionKey` теряется безвозвратно: им зашифрованы пароли
+интеграций в базе. Сохраните копию отдельно от кластера.

-Ключи плеера `ticketHs256` и `sessionHs256` должны отличаться друг от друга —
-это ключи разных контуров, и чарт откажется ставить одинаковые.
+Ключи плеера `ticketHs256` и `sessionHs256` должны быть разными, одинаковые
+чарт не примет.

 ### 4. Заполните `values.yaml`

-Обязательный минимум:
+Минимум:

 ```yaml
 ingress:
@@ -121,7 +121,7 @@ secrets:
  servicesInternalSecret: "..."
 ```

-Всё остальное имеет рабочие значения по умолчанию.
+У остальных параметров есть рабочие значения по умолчанию.

 Проверить конфигурацию, ничего не устанавливая:

@@ -129,8 +129,7 @@ secrets:
 helm template hrbox .helm -f values.yaml > /dev/null
 ```

-Если чего-то не хватает, чарт скажет об этом текстом, а не оставит
-неработающие поды в кластере.
+Если чего-то не хватает, команда остановится и напишет, что заполнить.

 ### 5. Установка

@@ -144,7 +143,7 @@ helm upgrade --install hrbox .helm -n hrbox --create-namespace -f values.yaml
 kubectl -n hrbox wait --for=condition=complete --timeout=30m job -l app=jobs
 ```

-### 7. Первый администратор
+### 7. Создайте администратора

 ```bash
 kubectl -n hrbox exec -it deploy/hrbox-worker -- \
@@ -155,14 +154,13 @@ kubectl -n hrbox exec -it deploy/hrbox-worker -- \

 ## Секреты

-Чувствительные значения из `values.yaml` чарт складывает в один Secret
-`hrbox-secrets` и монтирует контейнерам через `secretKeyRef` — в спеке
-Deployment паролей нет.
+Пароли и ключи из `values.yaml` чарт кладёт в один Secret `hrbox-secrets`,
+поды читают их оттуда. В спеке Deployment паролей нет.

 Если секретами управляет внешний инструмент, создайте Secret сами и укажите
-его имя в `secrets.existingSecret`. Ключи должны называться так:
+имя в `secrets.existingSecret`. Ключи должны называться так:

-| Ключ | Откуда берётся при `existingSecret: ""` |
+| Ключ | Что кладут |
 |---|---|
 | `cookie-validation-key` | `secrets.cookieValidationKey` |
 | `encryption-key` | `secrets.encryptionKey` |
@@ -180,63 +178,63 @@ Deployment паролей нет.
 | `slack-client-secret` | `app.slack.clientSecret` |
 | `slack-verification-token` | `app.slack.verificationToken` |

-Ключи плеера лежат в отдельном Secret `hrbox-nanabush-player` — им управляет
-`app.nanabushPlayer.deployment.existingSecret`.
+Ключи плеера лежат в отдельном Secret `hrbox-nanabush-player`, за него
+отвечает `app.nanabushPlayer.deployment.existingSecret`.

 ---

 ## Nanabush Player

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

-В облаке HRBox плеер живёт на отдельном поддомене. В on-premise выделенного
-поддомена нет, поэтому плеер монтируется на основной домен под путём
-`/nanabush-player`. Что из этого следует:
+В облаке HRBox плеер стоит на отдельном поддомене. В on-premise поддомена
+нет, поэтому плеер живёт на основном домене по пути `/nanabush-player`.
+Из этого следуют две вещи:

- **Изоляции cookie нет.** Плеер и HRBox делят один origin, поэтому cookie
-  сессии HRBox отправляются браузером и на запросы к содержимому курсов,
-  включая сторонние SCORM-пакеты. Если нужна настоящая изоляция —
-  запрашивайте у HRBox схему с отдельным поддоменом.
- **Часы должны быть синхронизированы.** Launch-тикет живёт 5 минут, сессия
-  проверяется с допуском 2 минуты. Настройте NTP на нодах и сервере БД;
-  если это невозможно, выключите плеер (`app.nanabushPlayer.enabled: false`).
+- **Cookie общие.** Плеер и HRBox на одном домене, поэтому cookie сессии
+  HRBox уходят и в запросы к содержимому курсов, включая сторонние
+  SCORM-пакеты. Если такая изоляция нужна, запросите у HRBox схему
+  с отдельным поддоменом.
+- **Часы должны быть синхронны.** Launch-тикет живёт 5 минут, у сессии
+  допуск 2 минуты. Настройте NTP на нодах и сервере базы. Если это
+  невозможно, выключите плеер: `app.nanabushPlayer.enabled: false`.

 Порядок первого включения:

-1. Убедитесь, что миграции применились: плееру нужны таблицы проекций.
-2. Дождитесь, пока **все** поды `web` перейдут на новую ревизию. Смешанный
-   выкат при `rollout.percent > 0` может создать вторую активную попытку по
-   одному назначению.
-3. Проверьте, что плеер отвечает сам, а не HRBox через общий маршрут:
+1. Убедитесь, что миграции применились: плееру нужны свои таблицы.
+2. Дождитесь, пока **все** поды `web` перейдут на новую версию. Пока часть
+   подов старая, при `rollout.percent > 0` по одному назначению может
+   открыться вторая попытка.
+3. Проверьте, что отвечает именно плеер, а не HRBox через общий маршрут:

   ```bash
   kubectl -n hrbox exec deploy/hrbox-worker -- \
     curl -s http://hrbox-nanabush-player:8094/readyz
   ```

-   Настоящий плеер вернёт JSON. HTML означает, что запрос ушёл в HRBox.
+   Плеер вернёт JSON. HTML означает, что запрос ушёл в HRBox.

-4. Проверьте публичный путь: `https://<домен>/nanabush-player/start`,
-   статику и API плеера под этим путём.
+4. Откройте `https://<домен>/nanabush-player/start` и проверьте статику
+   и API плеера по этому пути.

-Служебные пути (`/healthz`, `/readyz`, метрики) живут в корне и не зависят
-от `basePath`. Порт метрик наружу не публикуется намеренно.
+`/healthz`, `/readyz` и метрики отвечают в корне и от `basePath` не зависят.
+Порт метрик наружу не публикуется.

-Аварийное отключение — три независимых переключателя:
+Быстро выключить плеер можно тремя переключателями:

 ```yaml
 app:
  nanabushPlayer:
-    enabled: false            # пользователи возвращаются на старый проигрыватель
+    enabled: false            # пользователи вернутся на старый проигрыватель
    ingress:
      enabled: false          # маршрут снимается
    deployment:
      enabled: false          # под останавливается
 ```

-Выключать нужно сверху вниз: чарт не даст оставить включённым маршрут
-без пода или раскатку без маршрута.
+Выключать нужно сверху вниз: чарт не даст оставить маршрут без пода
+или включённый плеер без маршрута.

 Подробности контракта — `docs/nanabush-player-deployment.md` в репозитории HRBox.

@@ -250,9 +248,9 @@ app:
 helm upgrade hrbox .helm -n hrbox -f values.yaml
 ```

-Миграции и обновление кластера запускаются автоматически как хуки
-`post-upgrade` и выполняются строго по порядку. Имя джобы содержит номер
-ревизии релиза, поэтому в `kubectl get jobs` видно, какой выкат её запускал.
+Миграции и обновление кластера запускаются сами как хуки `post-upgrade`,
+строго по очереди. В имени джобы есть номер ревизии релиза, поэтому
+в `kubectl get jobs` видно, к какому выкату она относится.

 ### Масштабирование

@@ -264,16 +262,16 @@ app:
    chatbox: 4    # по числу открытых вкладок
 ```

-`conductor` всегда в одном экземпляре: второй планировщик запустил бы
-каждую задачу дважды.
+`conductor` всегда в одном экземпляре: два планировщика запустят каждую
+задачу дважды.

-Для `web` при двух и более репликах создаётся PodDisruptionBudget
-(`minAvailable: 75%`), чтобы drain ноды не уронил приложение целиком.
+Для `web` от двух реплик создаётся PodDisruptionBudget (`minAvailable: 75%`),
+чтобы вывод ноды из обслуживания не уронил приложение целиком.

 ### Конвертация видео

-Выключена по умолчанию: профиль ресурсов у неё на порядок тяжелее обычной
-обработки файлов. Включение:
+Выключена по умолчанию, потому что требует заметно больше ресурсов, чем
+остальная обработка файлов. Включение:

 ```yaml
 app:
@@ -297,7 +295,7 @@ app:
    tempoUrl: "http://tempo.monitoring:4317"
 ```

-Рядом с `web` поднимется коллектор OpenTelemetry, PHP начнёт слать трейсы.
+Рядом с `web` появится коллектор OpenTelemetry, PHP начнёт слать трейсы.

 ### Внешние Redis и NATS

@@ -323,18 +321,18 @@ kubectl -n hrbox logs -l app=nanabush-player --tail=200
 kubectl -n hrbox get jobs
 ```

-| Симптом | Куда смотреть |
+| Что видно | Куда смотреть |
 |---|---|
 | Поды `web` не готовы | пробы `/healthz` и `/health-check`, логи контейнера `fpm` |
-| Джоба миграций висит | init-контейнер `wait-postgres`: доступность и права в БД |
-| Курс не открывается | логи `nanabush-player`, совпадение домена в `ingress.host` и `app.defaultTenantHostname` |
+| Джоба миграций висит | init-контейнер `wait-postgres`: доступность базы и права |
+| Курс не открывается | логи `nanabush-player`, совпадают ли `ingress.host` и `app.defaultTenantHostname` |
 | Не приходят уведомления | логи `goworker`, очереди NATS, `app.launchpad.topics` |
-| Пользователей разлогинивает | перезапуски `dragonfly`: сессии живут в памяти |
+| Пользователей разлогинивает | перезапуски `dragonfly`: сессии хранятся в памяти |

 ---

-## Миграция с версии 2.x
+## Обновление с версии 2.x

-Часть ключей `values.yaml` переехала. Чарт проверяет старые имена и
-останавливает установку с подсказкой, поэтому незамеченным ничего не
-останется. Полный список изменений и порядок перехода — в [CHANGELOG.md](CHANGELOG.md).
+Часть ключей `values.yaml` переехала. Старые имена чарт узнаёт и
+останавливает установку с подсказкой, поэтому ничего не потеряется.
+Список изменений и порядок перехода — в [CHANGELOG.md](CHANGELOG.md).