Обновление серверных компонентов YTsaurus

В этой статье описан процесс полного обновления серверных компонентов кластера YTsaurus через Kubernetes-оператор: как подготовиться к обновлению, обновить оператор, изменить спецификацию Ytsaurus, отследить ход обновления и проверить результат.

Что важно знать перед обновлением

Обновляйтесь только на следующую мажорную версию.

Обновляйте кластер по порядку мажорных версий, не пропуская промежуточные: сначала 25.1 → 25.2, затем 25.2 → 25.3. Пропуск версии может нарушить работу кластера. Внутри целевой мажорной версии вы можете выбрать самую свежую минорную и получить последние обновления — например, 25.2.0 → 25.3.2. Доступные версии смотрите в списке релизов.

Обновление нельзя отменить.

После того как мастер-серверы вышли из режима read-only и применили необратимые изменения, откат на предыдущую версию не поддерживается.

Сначала обновляйте оператор, потом кластер.

Перед обновлением кластера обновите оператор. Его версия должна быть совместима с целевой версией кластера. Проверьте совместимость по таблице совместимости.

Во время обновления кластер может быть недоступен.

По умолчанию кластер полностью недоступен на время обновления — все операции и запросы прерываются. Планируйте обновление на период минимальной нагрузки. Если кластер должен оставаться доступным, выберите другую стратегию — смотрите Стратегии обновления.

Обновление кластера

Процесс обновления состоит из четырёх шагов:

1. Подготовьте кластер
2. Обновите оператор
3. Запустите обновление
4. Проверьте результат

1. Подготовьте кластер к обновлению

Перед изменением спецификации Ytsaurus проверьте текущее состояние кластера и убедитесь, что оператор готов начать новый цикл обновления.

1. Узнайте текущую версию кластера:

   $ kubectl get ytsaurus <cluster_name> -n <namespace> -o jsonpath='{.spec.coreImage}'
   
   ghcr.io/ytsaurus/ytsaurus:stable-25.1.0-relwithdebinfo
   

2. Проверьте состояние кластера:

   $ kubectl get ytsaurus <cluster_name> -n <namespace>
   
   NAME       CLUSTERSTATE   UPDATESTATE   UPDATINGCOMPONENTS   BLOCKEDCOMPONENTS
   ytsaurus   Running
   

   Перед обновлением кластер должен находиться в состоянии Running. Если кластер в другом состоянии, сначала устраните проблемы — смотрите раздел Решение проблем.

3. Убедитесь, что оператор готов к обновлению. Для этого проверьте его логи:

   kubectl logs -n <namespace> deployment/ytsaurus-ytop-chart-controller-manager --tail=100
   
   # Если имя deployment отличается, получите его список
   
   kubectl get deployments -n <namespace>
   

   Это важный шаг: оператор не должен быть занят незавершёнными действиями. Переходите к следующему шагу только тогда, когда в логах есть сообщение INFO Ytsaurus is running and happy. Это значит, что оператор считает кластер согласованным и не выполняет незавершённых действий.

   Важно

   Если оператор не пишет running and happy, не начинайте обновление. Это может привести к непредсказуемому поведению кластера.

4. Сохраните резервную копию спецификации:

   Файл необходим для возможности отката до прохождения точки невозврата:

   kubectl get ytsaurus <cluster_name> -n <namespace> -o yaml > ytsaurus-spec-backup.yaml
   

   После того как мастер-серверы вышли из режима read-only и применили необратимые изменения, откат на предыдущую версию не поддерживается.

Если все проверки пройдены, можно приступать к обновлению оператора.

2. Обновите оператор

Оператор следует обновлять первым. Новые версии серверных компонентов могут работать некорректно со старой версией оператора.

Проверьте текущую версию оператора:

helm list -n <namespace>

Список релизов и совместимых версий смотрите на странице релизов и в таблице совместимости.

Обновите оператор:

helm upgrade ytsaurus --install oci://ghcr.io/ytsaurus/ytop-chart --version <new_version>

Проверьте, что оператор обновился:

kubectl get pods -n <namespace>

Сразу после обновления могут быть видны старый и новый pod одновременно:

NAME                                                      READY   STATUS        RESTARTS   AGE
ytsaurus-ytop-chart-controller-manager-6f67fd5d5c-6bbws   2/2     Running       0          21s
ytsaurus-ytop-chart-controller-manager-7478f9b6cb-qr8wd   2/2     Terminating   0          23h

Через некоторое время старый pod удалится:

NAME                                                      READY   STATUS    RESTARTS   AGE
ytsaurus-ytop-chart-controller-manager-6f67fd5d5c-6bbws   2/2     Running   0          25s

3. Запустите обновление

При изменении поля coreImage в спецификации Ytsaurus оператор пересоздаёт pod'ы всех серверных компонентов из этой спецификации, даже если образ конкретного компонента не изменился. Это гарантирует совместимость версий всех серверных компонентов.

Компоненты с собственным релизным циклом — Query Tracker, YQL-агент и другие — при этом не обновляются. Как их обновить, смотрите в разделе Обновление отдельных компонентов. Перед обновлением проверьте совместимость этих компонентов с целевой версией кластера в таблице совместимости.

Сохраните актуальную спецификацию в файл для редактирования:

kubectl get ytsaurus <cluster_name> -n <namespace> -o yaml > ytsaurus-spec-new.yaml

Внесите в файл ytsaurus-spec-new.yaml следующие изменения:

• Задайте поле updatePlan со списком компонентов, которые нужно обновить. Для полного обновления укажите класс Everything — обновятся все серверные компоненты.

• Измените coreImage на следующую версию.

• Целевую версию выбирайте на странице релизов. Откройте нужный релиз и скопируйте тег образа ghcr.io/ytsaurus/ytsaurus.

spec:
  coreImage: ghcr.io/ytsaurus/ytsaurus:stable-25.2.0-relwithdebinfo # Следующая версия
  updatePlan:
    - class: Everything # Полное обновление всех серверных компонентов

По умолчанию оператор использует стратегию BulkUpdate — кластер будет полностью недоступен на время обновления. Если кластер должен оставаться доступным, настройте стратегию RollingUpdate через поле updatePlan в файле ytsaurus-spec-new.yaml до применения изменений. Пример — в разделе Обновление без остановки кластера через RollingUpdate.

Примените изменённую спецификацию:

kubectl apply -f ytsaurus-spec-new.yaml

Ожидаемый вывод:

ytsaurus.cluster.ytsaurus.tech/<cluster_name> configured

Отслеживайте статус в поле UPDATESTATE ресурса Ytsaurus:

kubectl get ytsaurus <cluster_name> -n <namespace>

Во время обновления вывод может выглядеть следующим образом:

NAME       CLUSTERSTATE   UPDATESTATE                    UPDATINGCOMPONENTS
ytsaurus   Updating       WaitingForPodsCreation         {ms hp ds dnd rp end tnd sch ca}

Описание этапов и состояний pod'ов — в справочнике статусов ниже.

Проверяйте состояние pod'ов:

kubectl get pods -n <namespace>

Если обновление идёт слишком долго, проверьте события проблемного pod'а:

kubectl describe pod <pod_name> -n <namespace> | grep -A 10 "Events:"

Если в событиях указана ошибка загрузки образа ImagePullBackOff, проверьте, что тег образа указан правильно и эта версия есть в реестре. Если pod в состоянии Pending, проблема связана с ресурсами — проверьте их доступность в кластере.

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

Обновление завершено при выполнении следующих условий:

• кластер находится в состоянии Running;
• все основные pod'ы находятся в состоянии Running;
• в кластере нет pod'ов в состояниях Init, Pending, ImagePullBackOff и CrashLoopBackOff.

Проверьте итоговое состояние кластера:

kubectl get ytsaurus <cluster_name> -n <namespace>

Ожидаемый вывод:

NAME       CLUSTERSTATE   UPDATESTATE   UPDATINGCOMPONENTS   BLOCKEDCOMPONENTS
ytsaurus   Running

Проверьте состояние pod'ов:

kubectl get pods -n <namespace>

Пример ожидаемого результата:

NAME                                      READY   STATUS     RESTARTS   AGE
ca-0                                      1/1     Running    0          5m
dnd-0                                     1/1     Running    0          5m
dnd-1                                     1/1     Running    0          5m
dnd-2                                     1/1     Running    0          5m
ds-0                                      1/1     Running    0          10m
end-0                                     2/2     Running    0          5m
hp-0                                      1/1     Running    0          5m
ms-0                                      1/1     Running    0          10m
qt-0                                      1/1     Running    15         75d
rp-0                                      1/1     Running    0          5m
sch-0                                     1/1     Running    0          5m
tnd-0                                     1/1     Running    0          10m

Проверьте, что в спецификации указана новая версия:

kubectl get ytsaurus <cluster_name> -n <namespace> -o jsonpath='{.spec.coreImage}'

Ожидаемый вывод:

ghcr.io/ytsaurus/ytsaurus:stable-25.2.0-relwithdebinfo

Убедитесь, что оператор снова пишет в логах Ytsaurus is running and happy:

kubectl logs -n <namespace> deployment/ytsaurus-ytop-chart-controller-manager --tail=100

После успешного обновления очистите поле updatePlan в файле ytsaurus-spec-new.yaml — оставьте его пустым:

spec:
  updatePlan: []

Того же результата можно добиться явным правилом с классом Nothing — оператор не будет обновлять ни один компонент:

spec:
  updatePlan:
    - class: Nothing

Примените изменение:

kubectl apply -f ytsaurus-spec-new.yaml

Оператор не очищает updatePlan автоматически — сбросьте его сами. Пустой updatePlan означает «не обновлять ничего» и защищает от случайного перезапуска компонентов при дальнейших изменениях спецификации. Если оставить - class: Everything, то при следующем изменении coreImage снова запустится полное обновление всех компонентов.

Обновление на следующую версию. Если нужно обновиться ещё на одну версию, повторите все шаги, начиная с раздела Подготовка к обновлению. Каждый раз сохраняйте спецификацию заново через kubectl get ytsaurus — оператор мог изменить её в процессе обновления, и локальный файл с прошлого раза уже не актуален.

Решение проблем при обновлении

Используйте этот раздел, если обновление не запускается, идёт слишком долго, завершается с ошибкой или ведёт себя непредсказуемо.

Error from server (Conflict): error when applying patch: the object has been modified; please apply your changes to the latest version and try again

kubectl get ytsaurus <cluster_name> -n <namespace> -o yaml > ytsaurus-spec-new.yaml

Failed to pull image "ghcr.io/ytsaurus/ytsaurus:stable-X.X.X-relwithdebinfo": not found

kubectl describe pod <pod_name> -n <namespace> | grep -A 10 "Events:"

Events:
  Type    Reason     Age    From               Message
  ----    ------     ----   ----               -------
  Normal  Scheduled  3m10s  default-scheduler  Successfully assigned ytsaurus/ms-0 to docker-desktop
  Normal  Pulling    3m9s   kubelet            Pulling image "ghcr.io/ytsaurus/ytsaurus:stable-25.2.0-relwithdebinfo"

kubectl get ytsaurus <cluster_name> -n <namespace>

kubectl logs -n <namespace> deployment/ytsaurus-ytop-chart-controller-manager --tail=100

kubectl get ytsaurus -n <namespace>

NAME         CLUSTERSTATE   UPDATESTATE           UPDATINGCOMPONENTS
minisaurus   Updating       ImpossibleToStart

kubectl describe ytsaurus -n <namespace>

kubectl describe ytsaurus -n <namespace>
...
  Update Status:
    Conditions:
      Last Transition Time:  2023-09-26T09:18:11Z
      Message:               Tablet cell bundles ([sys default]) aren't in 'good' health
      Reason:                Update
      Status:                True
      Type:                  NoPossibility
    State:                   ImpossibleToStart

Found unrecognized options in dynamic cluster config

Дополнительные сценарии

Обновление отдельных компонентов

В спецификации Ytsaurus можно управлять образами компонентов по отдельности. То, как оператор обрабатывает такие изменения, зависит от типа компонента:

• Компоненты с собственным релизным циклом — Query Tracker, YQL-агент, Strawberry и другие. Подробнее — в разделе Компоненты с собственным релизным циклом.

  Для обновления этих компонентов измените поле image в спецификации Ytsaurus. Это единственный способ обновления этих компонентов. При изменении их образа оператор обновит только их pod'ы, не останавливая работу кластера.

  При полном обновлении кластера через поле coreImage pod'ы этих компонентов перезапустятся, но их образ останется прежним — тем, что задан в поле image.

  Пример: обновление Query Tracker до версии 0.0.7:

  spec:
    queryTrackers:
      image: ghcr.io/ytsaurus/query-tracker:0.0.7
  

  kubectl apply -f ytsaurus-spec-new.yaml
  

  Оператор обновит только pod'ы qt, не затрагивая остальные компоненты.

• Точечное обновление серверных компонентов

  Вы можете переопределить образ для конкретного серверного компонента — например только для tabletNodes, указав для него отдельный image вместо общего coreImage.

  Укажите поле image для нужного компонента в файле ytsaurus-spec-new.yaml и примените изменение:

  kubectl apply -f ytsaurus-spec-new.yaml
  

Обновление статических конфигов

Оператор автоматически генерирует конфигурационные файлы для каждого компонента — мастер-серверов, прокси, нод — на основе спецификации Ytsaurus. Иногда нужно изменить параметры, которые попадают в эти файлы, — например добавить новое место хранения locations или настроить специфичные параметры компонента через configOverrides.

В таких случаях не задавайте поле updatePlan. Достаточно изменить спецификацию и применить её — оператор сам обнаружит, что конфигурация изменилась, и перезапустит только pod'ы затронутых компонентов.

Внесите нужные изменения в ytsaurus-spec-new.yaml и примените:

kubectl apply -f ytsaurus-spec-new.yaml

Во время перезапуска pod'ов кластер перейдёт в состояние Reconfiguration:

kubectl get ytsaurus <cluster_name> -n <namespace>

NAME       CLUSTERSTATE      UPDATESTATE
ytsaurus   Reconfiguration

После того как pod'ы перезапустятся и станут готовы, кластер вернётся в Running.

Автоматическое обновление после обновления оператора

При обновлении оператора его новая версия может автоматически запустить обновление кластера — без изменения coreImage с вашей стороны. Это происходит потому, что разные версии оператора могут генерировать разные конфигурационные файлы для одних и тех же компонентов — например, в новой версии может добавиться поле. Оператор замечает расхождение между текущим состоянием кластера и желаемым и запускает reconciliation.

Если обновление окажется невозможным, кластер останется в состоянии Updating, а UPDATESTATE перейдёт в ImpossibleToStart. В этом случае есть два варианта:

• Откатить оператор до предыдущей версии:

  helm rollback ytsaurus -n <namespace>
  

• Оставить поле updatePlan пустым в спецификации Ytsaurus — оператор отменит обновление и не будет запускать его автоматически:

  spec:
    updatePlan: []
  

  kubectl apply -f ytsaurus-spec-new.yaml
  

  После этого приведите кластер в рабочее состояние и повторите попытку, когда будете готовы, задав в updatePlan нужные компоненты — например - class: Everything.

Обновление без остановки кластера через RollingUpdate

Чтобы кластер оставался доступным во время обновления, настройте стратегию RollingUpdate через поле updatePlan в спецификации Ytsaurus. Оператор обновит pod'ы по одному, сохраняя минимальное количество доступных инстансов.

apiVersion: cluster.ytsaurus.tech/v1
kind: Ytsaurus
metadata:
  name: ytsaurus
spec:
  coreImage: ghcr.io/ytsaurus/ytsaurus:stable-25.2.0-relwithdebinfo
  updatePlan:
    - class: Everything
      strategy:
        rollingUpdate: {}

updatePlan:
  # HTTP Proxies — Rolling Update
  - component:
      type: HttpProxy
    strategy:
      rollingUpdate: {}
      runPreChecks: true

  # RPC Proxies — Rolling Update
  - component:
      type: RpcProxy
    strategy:
      rollingUpdate: {}
      runPreChecks: true

  # Data Nodes — Rolling Update
  - component:
      type: DataNode
    strategy:
      rollingUpdate: {}
      runPreChecks: true

  # Exec Nodes — Rolling Update с drain
  - component:
      type: ExecNode
    strategy:
      rollingUpdate: {}
      runPreChecks: true

  # Остальные компоненты — BulkUpdate
  - class: Everything
    concurrency: 2  # не более 2 instance groups одновременно

apiVersion: cluster.ytsaurus.tech/v1
kind: Ytsaurus
metadata:
  name: ytsaurus
spec:
  coreImage: ghcr.io/ytsaurus/ytsaurus:stable-25.2.0-relwithdebinfo
  clusterFeatures:
    enableImageHeater: true
  updatePlan:
    - class: Everything
      strategy:
        rollingUpdate: {}

Описание всех полей updatePlan — в разделе Настройка поля updatePlan.

Ручное вмешательство

Если автоматическое обновление не может завершиться и нужно выполнить ручные действия, временно отключите управление кластером со стороны оператора. Для этого установите в спецификации Ytsaurus флаг isManaged: false.

После этого оператор перестанет вносить изменения в кластер, и вы сможете выполнить ручные действия.

Этот сценарий может быть полезен, если оператор застрял на проблемном компоненте. Также он поможет, если нужно вручную проверить или восстановить состояние части кластера. Или если вы разбираете нестандартную ошибку, которую нельзя устранить обычным повторным применением спецификации.

Справочник статусов

• Как проверить статус кластера
• UPDATESTATE
• CLUSTERSTATE
• Состояния pod'ов

Как проверить статус кластера

Следить за обновлением можно по статусу ресурса Ytsaurus:

kubectl get ytsaurus -n <namespace>

Во время обновления кластер переходит в состояние Updating, а подробный этап отображается в поле UPDATESTATE. После завершения обновления кластер возвращается в состояние Running:

NAME         CLUSTERSTATE   UPDATESTATE   UPDATINGCOMPONENTS
minisaurus   Running        None

UPDATESTATE

Не все статусы появляются при каждом обновлении — набор зависит от того, какие компоненты затронуты. Например, статусы WaitingForTabletCells появляются только при обновлении tablet-нод, WaitingForOpArchiveUpdate — только при обновлении планировщика.

CLUSTERSTATE

Состояния pod'ов

Справочник компонентов

Компоненты, которые обновятся вместе с кластером

Оператор обновляет эти компоненты одновременно с кластером при изменении поля coreImage в спецификации Ytsaurus. Для каждого компонента можно переопределить образ отдельно через поле image.

Компоненты с собственным релизным циклом

Компоненты имеют собственные релизные циклы, оператор обновляет их независимо через поле image конкретного компонента в спецификации Ytsaurus.