Configuring updates

Deckhouse Platform (DP) supports a flexible update mechanism, allowing you to select release channels and configure the update mode. Release channels help you balance stability with the speed of receiving new features.

The update mode configuration lets you choose between automatic or manual updates and define update windows during which new versions can be installed. Together, these features help you avoid updates at inconvenient times and control migration to new releases.

Checking the current release channel

To check which release channel is used in your cluster, run the following command:

d8 k get mc deckhouse -o yaml | grep releaseChannel

Example output:

    releaseChannel: Stable

Switching release channels

To switch the release channel, specify the new channel in the settings.releaseChannel parameter of the deckhouse module.

Example configuration using the Stable channel:

apiVersion: deckhouse.io/v1alpha1
kind: ModuleConfig
metadata:
  name: deckhouse
spec:
  version: 1
  settings:
    releaseChannel: Stable

Update modes

DP supports two update modes that determine how new versions are applied:

• Automatic mode — the cluster updates as soon as a new version appears on the selected release channel. Two configuration options are available:
  • AutoPatch — only patch version updates within the current minor version are applied;
  • Auto — both patch and minor versions are applied automatically.
• Manual mode (Manual) — both patch and minor versions are applied only after manual approval.

For automatic mode, update windows settings are available — allowed updates are applied taking update.windows into account, if windows are configured. If no windows are set, the update is applied as soon as the version appears on the release channel.

Patch versions only within the current minor (AutoPatch)

To keep DP updates within the current minor version (apply patch versions only), use the AutoPatch mode.

For example, if version v1.70.1 is installed, DP can automatically update to v1.70.2, but will not move to v1.71.* without manual approval.

This is the default value. To set the AutoPatch mode explicitly, run the following command:

d8 k patch mc deckhouse --type=merge -p='{"spec":{"settings":{"update":{"mode":"AutoPatch"}}}}'

To approve a minor version update, run the following command, replacing <DECKHOUSE-VERSION> with the target DP version:

d8 k patch DeckhouseRelease <DECKHOUSE-VERSION> --type=merge -p='{"approved": true}'

Automatic updates for all versions (Auto)

In the Auto mode, DP automatically applies both patch and minor versions, taking update windows into account if they are configured.

To enable the Auto mode, the following command:

d8 k patch mc deckhouse --type=merge -p='{"spec":{"settings":{"update":{"mode":"Auto"}}}}'

Manual mode (Manual)

In the Manual mode, DP receives information about new versions in the cluster, but applying both patch and minor versions requires manual approval.

To enable the Manual mode, the following command:

d8 k patch mc deckhouse --type=merge -p='{"spec":{"settings":{"update":{"mode":"Manual"}}}}'

Checking the current update mode

To determine the current update mode used in the cluster, inspect the configuration of the deckhouse module with the following command:

d8 k get mc deckhouse -o yaml

Example output:

spec:
  settings:
    releaseChannel: Stable
    update:
      mode: AutoPatch
      windows:
      - days:
        - Mon
        from: "19:00"
        to: "20:00"

How automatic updates are applied

Automatic update mode is enabled when the releaseChannel parameter is specified in the deckhouse module configuration. When this condition is met:

1. DP checks the release channel every minute for new releases.
2. When a new release appears, DP downloads it into the cluster and creates a DeckhouseRelease custom resource.
3. Once the DeckhouseRelease resource appears in the cluster, DP applies the corresponding update according to the configured update settings (by default — automatically, at any time).

To view the list and status of all releases in the cluster, run the following command:

d8 k get deckhousereleases

Release pinning

Release pinning refers to fully or partially disabling automatic updates.

There are three ways to restrict automatic updates in Deckhouse:

• Enable manual update approval mode.

  In this mode, DP will receive updates into the cluster, but applying patch and minor versions will require manual approval.

  To enable manual update approval mode, set the settings.update.mode parameter to Manual in the deckhouse module configuration using the following command:

  d8 k patch mc deckhouse --type=merge -p='{"spec":{"settings":{"update":{"mode":"Manual"}}}}'
  

  To approve an update, run the following command, replacing <DECKHOUSE-VERSION> with the target DP version:

  d8 k patch DeckhouseRelease <DECKHOUSE-VERSION> --type=merge -p='{"approved": true}'
  

• Enable automatic updates for patch versions only.

  In this mode, DP will receive updates into the cluster, but applying minor versions will require manual approval. Patch versions within the current minor version will be applied automatically, taking update windows into account if they are configured.

  For example, if you have DP version v1.70.1 installed, after enabling this mode, Deckhouse can automatically update to v1.70.2, but it will not update to v1.71.* without manual approval.

  To enable automatic updates for patch versions only, set the settings.update.mode parameter to AutoPatch in the deckhouse module configuration using the following command:

  d8 k patch mc deckhouse --type=merge -p='{"spec":{"settings":{"update":{"mode":"AutoPatch"}}}}'
  

  To approve a minor version update, run the following command, replacing <DECKHOUSE-VERSION> with the target DP version:

  d8 k patch DeckhouseRelease <DECKHOUSE-VERSION> --type=merge -p='{"approved": true}'
  

• Manually set the target DP version tag for the deckhouse Deployment and remove the releaseChannel parameter from the deckhouse module configuration.

In this case, DP will remain at the specified version, and no information about newer available versions (DeckhouseRelease objects) will appear in the cluster.

Important. This mode blocks the installation of patch releases, which may include critical security or bug fixes. If you need to receive patches within the current minor version, use the AutoPatch mode instead of hard pinning.

Example of pinning version v1.66.3 for DP EE and removing the releaseChannel parameter from the deckhouse module configuration:

d8 k -ti -n d8-system exec svc/deckhouse-leader -c deckhouse -- kubectl set image deployment/deckhouse deckhouse=registry.deckhouse.io/deckhouse/ee:v1.66.3

d8 k patch mc deckhouse --type=json -p='[{"op": "remove", "path": "/spec/settings/releaseChannel"}]'

Manual update approval

Manual approval of DP updates is required in the following cases:

• The DP update confirmation mode is enabled.

  This means the settings.update.mode parameter of the deckhouse module is set to either Manual (confirmation required for both patch and minor updates) or AutoPatch (confirmation required only for minor updates).

  To approve an update, run the following command, replacing <DECKHOUSE-VERSION> with the target version:

  d8 k patch DeckhouseRelease <DECKHOUSE-VERSION> --type=merge -p='{"approved": true}'
  

• Automatic update approval is disabled for a NodeGroup, for updates that might cause temporary downtime of system components.

  This means the spec.disruptions.approvalMode parameter of the corresponding NodeGroup resource is set to Manual.

  To apply the update, set the update.node.deckhouse.io/disruption-approved= annotation on each node in the group:

  Example:

  d8 k annotate node ${NODE_1} update.node.deckhouse.io/disruption-approved=
  

Update windows

DP allows you to define update windows, which are specific time intervals during which automatic updates are allowed. Using update windows ensures that updates won’t be installed at inconvenient times or during periods of high cluster load.

Applying updates when update windows are configured

• If update windows are configured, DP installs new versions only during the specified windows.
• If no update windows are configured, the update is applied as soon as a new version appears on the configured release channel.

Configuring update windows

You can manage DP update windows in the following ways:

• To control general updates, use the update.windows parameter in the deckhouse module configuration;
• To control updates that may lead to short-term downtime of system components, use the disruptions.automatic.windows and disruptions.rollingUpdate.windows parameters in the NodeGroup resource.

Configuration examples

• Two daily update windows: from 08:00 to 10:00 and from 20:00 to 22:00 (UTC):

  apiVersion: deckhouse.io/v1alpha1
  kind: ModuleConfig
  metadata:
    name: deckhouse
  spec:
    version: 1
    settings:
      releaseChannel: EarlyAccess
      update:
        windows: 
          - from: "8:00"
            to: "10:00"
          - from: "20:00"
            to: "22:00"
  

• Update windows on Tuesdays and Saturdays from 18:00 to 19:30 (UTC):

  apiVersion: deckhouse.io/v1alpha1
  kind: ModuleConfig
  metadata:
    name: deckhouse
  spec:
    version: 1
    settings:
      releaseChannel: Stable
      update:
        windows: 
          - from: "18:00"
            to: "19:30"
            days:
              - Tue
              - Sat
  

Updating virtualization

If virtualization is enabled in the cluster, its components fall into two categories that are updated differently:

• the components that manage virtualization resources (the control layer);
• the components that run virtual machines (the “firmware”).

Updating the control layer doesn’t affect the virtual machines that are already running, but it drops open VNC and serial console connections while the component restarts.

Updating the “firmware” may require migrating virtual machines to the new version. DKP migrates a machine once, and if the migration fails, the machine owner has to move or restart it manually. To pick a suitable time for such an update, use update windows and the manual mode.

Additional resources

• Global custom resources
• Module deckhouse documentation
• Module node-manager custom resources