Update strategies for YTsaurus

This article describes the strategies for updating YTsaurus cluster components, their differences, and configuration procedures. Choose a strategy based on your cluster availability requirements during the update.

Overview of strategies

An update strategy determines whether the operator restarts component pods simultaneously or sequentially, one by one. This affects cluster availability during the update.

To select a strategy, define update rules in the updatePlan field. In each rule, you specify which components to update and which strategy to use. A single rule can cover the entire cluster, individual components, or groups of components. For more details, see the Configuring the updatePlan field section.

The operator supports three update strategies:

Configuring the updatePlan field

Add the updatePlan field to the YTsaurus cluster specification. In it, list the rules: in each rule, select components by the class or component field and specify the update strategy in the strategy field. The operator checks the rules from top to bottom and applies the first matching one. Therefore, place specific rules by the component field before general rules by the class field.

Field descriptions

For examples of configuring the updatePlan field for the RollingUpdate strategy, see the Updating without stopping the cluster section.

Image preloading

By default, the operator downloads the new image during the update, when the pod is already stopped. This makes the component unavailable for a longer period. To download images in advance, enable preloading — the operator will download the required images before the update starts, and pod switching will be faster.

Enable preloading for all components using the enableImageHeater flag in the clusterFeatures block:

spec:
  clusterFeatures:
    enableImageHeater: true

Preloading is especially useful with the RollingUpdate strategy when minimal downtime is important. For a combined configuration example, see the Updating without stopping the cluster section.

The preloading progress is reflected in the WaitingForImageHeater status of the UPDATESTATE field.

Migrating from enableFullUpdate to updatePlan

Starting from operator version 0.32.0, the updatePlan field replaces the enableFullUpdate flag, so this flag is no longer valid. For information about operator releases, see the Releases page.

The enableFullUpdate flag only enabled or disabled a full update. The updatePlan field specifies a list of rules: in each rule, you select components and their update strategy.

Direct correspondence between the old flag and the new field:

# Operator 0.31.0 and earlier
spec:
  enableFullUpdate: true

# Operator 0.32.0 and later
spec:
  updatePlan:
    - class: Everything

In addition to the direct correspondence, updatePlan provides capabilities that enableFullUpdate didn’t have:

• Component set selection. A rule with class: Stateless updates all stateless components, except master servers, Data nodes, and Tablet nodes. You can also select an individual component by type using the component field.
• Update strategy selection. In the strategy field of each rule, specify the RollingUpdate or OnDelete strategy. For more details, see the Configuring the updatePlan field section.

# Operator 0.32.0 and later
spec:
  updatePlan:
    - component:
        type: HttpProxy

The operator only updates components explicitly listed in updatePlan. It leaves other components unchanged, even if their image has changed: such a component enters the UpdateBlocked state and waits for you to add it to the plan.

If updatePlan is empty or not specified, the operator doesn’t perform any updates. If coreImage changes, the cluster enters the UpdateBlocked state — the update is prepared but blocked.

Default strategy: BulkUpdate

If you don’t specify the updatePlan field or specify it without the strategy field, the operator applies the BulkUpdate strategy. The update proceeds in three phases:

Preparation.

The operator enables safe mode and disables writing to the cluster, saves and deletes tablet cells — dynamic tables become unavailable. Then the operator creates snapshots of master servers and puts them in read‑only mode.

Pod replacement.

The operator simultaneously deletes pods of all components — at this stage, the cluster is completely unavailable. After that, the operator recreates pods with the new image.

Recovery.

The operator waits for master servers to exit read‑only mode, restores tablet cells, and disables safe mode.

The cluster is completely unavailable from the start of preparation to the end of recovery. The duration depends on the cluster size — from several minutes to tens of minutes.

Strategy: RollingUpdate

With the RollingUpdate strategy, the operator updates pods one by one or in groups and guarantees a minimum number of available instances.

Component availability with RollingUpdate

Recommended number of instances

For examples of configuring RollingUpdate for a cluster, see the Additional scenarios section of the update guide.

Configuring pod availability

By default, with the RollingUpdate strategy, the operator updates one pod at a time. To specify a different number, use the minReadyInstanceCount field:

spec:
  httpProxies:
    - instanceCount: 5
      minReadyInstanceCount: 3  # always at least 3 pods are available
      role: default

The operator calculates the number of pods updated simultaneously using the formula:

maxUnavailable = max(1, instanceCount - minReadyInstanceCount)

In the example above, the operator updates up to 2 pods simultaneously, while 3 pods always serve requests: maxUnavailable = max(1, 5 - 3) = 2.