Update Kubernetes: launch, modes and transitions between versions

Where to run the update

The cluster update (including the Kubernetes version) is launched in the GUI on the cluster dashboard - management cluster or client cluster, or using commands in the CLI.

Where to see available versions

In the GUI, the “Update” block on the cluster dashboard. It displays all stable versions available for upgrading from the current version.

Full map - Update version map.

Screenshot: managing updates on the dashboard

Cluster update block

Click Manage to select the version and configure update schedules.

Start cluster update

In the CLI, available versions can be viewed in the ShturvalUpdateChannel resource.

Recommendations before updating

  1. Review the release notes of the target version - there may be breaking changes and migration steps.
  2. Create a backup of the management cluster before upgrading.
  3. Check the version map - make sure forward navigation is supported. If not, plan to upgrade via an intermediate version.

Update client clusters only after upgrading the management cluster!

Update modes

    The update is launched manually - through the GUI or kubectl.

      1. Select a cluster in the left menu.
      2. On the dashboard, find the “Update” block (next to the current version of the cluster).
      3. Click Manage.
      4. In the modal window, select a version from the list of available ones.
      5. Click Update.

      If “No updates” is displayed, you have the latest available version for the current channel.

      Screenshot: window for selecting a version for cluster update

      Version selection window for cluster update

      Specify the target version in the ShturvalUpdate resource:

      kubectl -n shturval-update-system patch su shturval-update --type=merge -p '{"spec":{"version":"X.Y.Z"}}'

      Replace X.Y.Z with the desired version.

      Example - update to version 2.14.0:

      kubectl -n shturval-update-system patch su shturval-update --type=merge -p '{"spec":{"version":"2.14.0"}}'

      Deferred update lets you configure one or more schedules. The system starts an update automatically when a new version is available.

        1. Cluster dashboard → “Update” block → Manage.
        2. Click + next to Deferred update settings.
        3. Specify:
          • Schedule - in cron format (values separated by spaces);
          • Update window duration - how much time can be used for updating (default 24 hours, minimum 30 minutes);
          • Behavior when the window is exceeded: stop (UpdatePaused) or continue;
          • Allow minor versions - if not, only patch versions are automatically updated.
        4. Click Add.
        Screenshot: window for creating a schedule for cluster update

        Window for creating a cluster update schedule

        Create a manifest and apply it:

        apiVersion: update.shturval.tech/v1beta1
kind: ShturvalUpdateSchedule
metadata:
  name: update-schedule
  namespace: shturval-update-system
spec:
  allowMinorVersion: true
  pauseIfUpdatePeriodExceed: false
  schedule: "0 8 26 9 *"
  updatePeriod: "10h0m0s"
        ParameterDescription
        scheduleSchedule in cron format
        updatePeriodUpdate window duration (e.g. 24h0m0s)
        pauseIfUpdatePeriodExceedStop updating when exceeding window (true) or continue (false)
        allowMinorVersionAllow automatic upgrade to minor versions

        To run a scheduled update, specify the name ShturvalUpdateSchedule in ShturvalUpdate:

        kubectl -n shturval-update-system patch su shturval-update --type=merge -p '{"spec":{"followSchedule":"update-schedule"}}'

        Changing and deleting a schedule

        • Change - select a schedule in the modal window and configure again. If an update is already in progress, the new schedule applies.
        • Delete - only possible if the update according to this schedule has not yet started.

        Upgrade steps

        After launch, the update goes through the following stages (displayed on the dashboard):

        1. Updating the shturval-update module - updating the update module itself.
        2. Forced removal of outdated services - this step can be skipped if such services are not available.
        3. Updating shturval-node-config - module for managing node configurations.
        4. Updating the Kubernetes version — updates Kubernetes components in the cluster.
        5. Updating system services — updates platform services (monitoring, logging, and others).

        Stage statuses

        Color indication on the dashboard:

        • Green — the stage has been successfully completed;
        • Yellow — the stage is being executed;
        • Gray — the stage is not initialized.

        When using deferred update: If the update does not complete within the specified window and the “pause” behavior is configured, the status UpdatePaused is displayed. To resume, click Continue outside schedule.

        Custom resources

        ResourcePurpose
        ShturvalUpdateSets the update version, displays the status
        ShturvalUpdateChannelUpdate channel (only stable is available in the platform)
        ShturvalUpdateScheduleScheduled deferred update options

        A general overview of these and other custom platform resources is provided on the page “Custom resources in the platform”.

        Special steps for individual transitions

        Some transitions require additional steps. If manual action is required, this is indicated in the release notes of the target version.

        Updating cluster nodes

        During an update, the Kubernetes version changes only on nodes already in the cluster. New nodes still use the version from InfraMachineTemplate. After the upgrade, create a new VM template in the infrastructure provider and replace InfraMachineTemplate in node groups. See VM nodes and templates.

        ← Node scaling
        VM nodes and templates →