Обновление платформы в Kubernetes

Платформа в Kubernetes состоит из двух независимых Helm-чартов, которые устанавливаются отдельными релизами в одно пространство имён (Namespace):

Чарт	Релиз	Назначение

Чарт	Релиз	Назначение
`visiology`	`visiology`	Платформа Visiology и инфраструктурные субчарты (Keycloak, PostgreSQL, MinIO, ClickHouse)
`visiology-monitoring`	`visiology-monitoring`	Стек мониторинга (kube-prometheus-stack, Loki, Tempo, Grafana Alloy)

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

Обозначения:

<NS> — namespace платформы;
settings.yaml — конфигурационный файл, который использовался при установке предыдущего релиза.

Изменения в версии 3.18

По сравнению с 3.17 в чартах Kubernetes произошли следующие изменения:

Миграция данных БД не требуется. Версии PostgreSQL-субчартов не меняются (Keycloak — 16.3, остальные — 15.7), ClickHouse остаётся на томе 10Gi. Существующие тома data-* переиспользуются как есть — wipe/dump/restore не нужны. (Это отличие от обновления 3.16 → 3.17, где миграция была обязательна.)
Grafana: учётные данные администратора вынесены в секрет visiology-auth (ключи GRAFANA_ADMIN_USER / GRAFANA_ADMIN_PASSWORD). Мониторинг читает их из секрета — поэтому основной чарт обязательно обновляется до установки мониторинга.
Стек мониторинга переработан: субчарты заменены (loki-stack → loki + alloy-logs, opentelemetry-collector → alloy-otlp, добавлен tempo). In-place helm upgrade мониторинга невозможен — старый релиз удаляется и ставится новый с нуля.

Предварительные требования

Установлены helm (3.x или 4.x) и kubectl; выбран нужный кластер: kubectl config current-context.
Все образы версии 3.18 загружены в реестр cr.yandex/.... Это критично: post-upgrade Job тянет образ из реестра, и при его отсутствии обновление завершится ошибкой ImagePullBackOff. В Yandex Cloud pull идёт через Service Account узла — отдельный secret не нужен.
Релиз visiology уже установлен и работает (мониторинг использует его секрет visiology-auth).
Снят бэкап БД (Postgres/ClickHouse) — на случай отката.

Выполнение обновления

Шаг 1. Скачвание Helm-чартов 3.18

Получите токен на портале дистрибутивов https://distrib.visiology.su (вкладка «YCR токен»).
Войдите в реестр:
sh helm registry login cr.yandex -u iam -p <TOKEN>
Скачайте оба чарта версии 3.18.0:
sh helm pull oci://cr.yandex/crpe1mi33uplrq7coc9d/visiology/visiology --version 3.18.0 helm pull oci://cr.yandex/crpe1mi33uplrq7coc9d/visiology/visiology-monitoring --version 3.18.0

Дальше в командах вместо visiology-3.18.0.tgz / visiology-monitoring-3.18.0.tgz можно подставлять распакованные каталоги visiology/ и visiology-monitoring/ (флаг -d|--dev у скрипта миграции).

Шаг 2. Обновление с помощью скрипта миграции (рекомендуется)

Скрипт выполняет обновление обоих релизов автоматически:

./migrate-3.17-to-3.18.sh -n <NS> -f settings.yaml \
  -r visiology --monitoring-release visiology-monitoring

Флаги скрипта:

Флаг	По умолчанию	Назначение

Флаг	По умолчанию	Назначение
`-n, --namespace`	— (обязателен)	namespace платформы
`-f, --settings`	— (обязателен)	путь к `settings.yaml`
`-r, --release`	`visiology`	имя основного релиза
`--monitoring-release`	`visiology-monitoring`	имя релиза мониторинга
`-d, --dev`	—	использовать распакованные каталоги `visiology/` и `visiology-monitoring/` вместо `.tgz`

Что делает скрипт

Обновляет основной чарт visiology (helm upgrade), транзиентно включая одноразовый Keycloak-Job для регистрации MCP server:
sh helm upgrade visiology visiology-3.18.0.tgz -n <NS> -f settings.yaml \ --set k8sUpdate.83605_mcp_server.enabled=true
Гейт k8sUpdate.83605_mcp_server в values.yaml остаётся false — выключать вручную не нужно.
Обновляет CRD prometheus-operator из комплекта чарта (server-side, доступ в интернет не нужен). Без этого шага установка мониторинга падает с ошибкой field not declared in schema.
Переустанавливает мониторинг (с подтверждения): удаляет старый релиз, чистит его тома (PVC) и ставит новый. Данные основного чарта (Postgres/ClickHouse) при этом не затрагиваются — мониторинг это отдельный релиз.

Скрипт запрашивает подтверждение на удаление релиза мониторинга и его PVC — данные мониторинга (метрики/логи/трейсы) при этом теряются, метрики платформы это не затрагивает.

Шаг 3. Ручное обновление (альтернатива скрипту)

Если нужно выполнить шаги вручную (например, для контроля каждого этапа), полный пошаговый алгоритм приведён в файле update-notes.md из комплекта чарта. Кратко:

Основной чарт:
sh helm upgrade visiology visiology/ -n <NS> -f settings.yaml \ --set k8sUpdate.83605_mcp_server.enabled=true
Обновите CRD мониторинга (обязательно, до удаления старого релиза):
sh kubectl apply --server-side --force-conflicts \ -f visiology-monitoring/charts/kube-prometheus-stack/charts/crds/crds/
Для архива .tgz — сначала распакуйте: tar -xzf visiology-monitoring-3.18.0.tgz -C /tmp и примените из /tmp/visiology-monitoring/charts/kube-prometheus-stack/charts/crds/crds/.
Удалите старый релиз мониторинга: helm uninstall visiology-monitoring -n <NS>
Удалите старые тома (PVC) мониторинга (иначе loki-0/tempo-0/Prometheus зависнут в CrashLoopBackOff):
sh kubectl delete pvc -n <NS> -l app.kubernetes.io/instance=visiology-monitoring --ignore-not-found
Проверьте, не остались ли тома без этого label:
kubectl get pvc -n <NS> | grep -iE ‘grafana|loki|tempo|prometheus|promtail|alertmanager’
Установите мониторинг 3.18:
sh helm install visiology-monitoring visiology-monitoring/ -n <NS> -f settings.yaml

Шаг 4. Проверка результата

helm list -n <NS>                              # оба релиза STATUS=deployed
kubectl get pods -n <NS>                        # все поды Running/Completed
kubectl get pod -n <NS> | grep alertmanager     # alertmanager-...-0  2/2 Running

Grafana открывается по адресу https://<домен платформы>/<подпуть>/grafana (вход через Keycloak).

Обновление завершено.

Если что-то пошло не так

Мониторинг в статусе failed, в ошибке hostNetwork: field not declared in schema — не были обновлены CRD (Шаг 3.2). Примените CRD, затем удалите и переустановите мониторинг:
sh kubectl apply --server-side --force-conflicts \ -f visiology-monitoring/charts/kube-prometheus-stack/charts/crds/crds/ helm uninstall visiology-monitoring -n <NS> helm install visiology-monitoring visiology-monitoring/ -n <NS> -f settings.yaml
cannot re-use a name that is still in use при установке мониторинга — старый релиз не удалён. Выполните helm uninstall visiology-monitoring -n <NS> и повторите установку.
ключ 'GRAFANA_ADMIN_...' отсутствует или пуст (или KEYCLOAK_GRAFANA_CLIENT_SECRET) — основной чарт visiology не обновлён на 3.18. Выполните Шаг 2/3.1 и повторите установку мониторинга.
loki-0 / tempo-0 / Prometheus в CrashLoopBackOff — не удалены старые тома. Удалите PVC мониторинга и пересоздайте поды:
sh kubectl delete pvc -n <NS> -l app.kubernetes.io/instance=visiology-monitoring --ignore-not-found kubectl delete pod -n <NS> -l app.kubernetes.io/instance=visiology-monitoring
Поды в ImagePullBackOff / ErrImagePull — образ не найден в реестре или нет доступа к реестру с узла. Убедитесь, что все образы 3.18 загружены в cr.yandex/....
Откат к 3.17 — основной чарт: helm rollback visiology <ревизия> -n <NS> (данные БД совместимы). Мониторинг откатывается переустановкой версии 3.17 и её CRD; данные мониторинга теряются.

Нужна дополнительная помощь?

Свяжитесь с технической поддержкой.