Updating Kubernetes

Written by

Improved by

Updated at November 18, 2024

List of available Kubernetes versions
Updating a cluster
- Configuring automatic updates when creating or editing a cluster
- Manually updating the cluster version
Updating a node group
- Configuring automatic updates of a node group
- Manually updating a node group version
Updating Kubernetes components without changing the version
- Updating for a cluster with automatic updating disabled
- Updating for a node group with automatic updating disabled

For Managed Service for Kubernetes, both automatic and manual updates are available for clusters and node groups. You can request a manual update of the Managed Service for Kubernetes cluster or its nodes to the latest supported version at any time. Manual updates bypass any configured maintenance windows and maintenance exceptions.

When updating the Kubernetes major version, first update the Managed Service for Kubernetes cluster and then its node group.

Note

You can edit the update policy of Managed Service for Kubernetes clusters and node groups at any time.

For more information, see Release channels.

List of available Kubernetes versions

Management console

CLI

API

To get a list of available versions for a Managed Service for Kubernetes cluster:

Go to the folder page and select Managed Service for Kubernetes.
Click the name of the Managed Service for Kubernetes cluster.
Click Edit in the top-right corner.
View the list of available versions in the Kubernetes version field under Master configuration.

To get a list of available versions for a Managed Service for Kubernetes node group:

Go to the folder page and select Managed Service for Kubernetes.
Click the name of the Managed Service for Kubernetes cluster you need and go to the Nodes manager tab.
Select the Managed Service for Kubernetes node group from the list and click Edit in the top-right corner.
Get a list of available versions in the Kubernetes version field.

If you do not have the Yandex Cloud command line interface yet, install and initialize it.

The folder specified in the CLI profile is used by default. You can specify a different folder using the --folder-name or --folder-id parameter.

To get a list of available versions, run the following command:

yc managed-kubernetes list-versions

To get a list of available versions, use the list.

Updating a cluster

Configuring automatic updates when creating or editing a cluster

Select automatic update mode for your Managed Service for Kubernetes cluster and set the update schedule:

Management console

CLI

Terraform

API

You can specify update settings when creating a Managed Service for Kubernetes cluster or updating its settings.

In the Maintenance frequency / Disable field, select the Managed Service for Kubernetes cluster update policy:

Disabled: Select this option not to use automatic updates.
Anytime: Select this option for Managed Service for Kubernetes to manage the update installation schedule.
Daily: Set the start time and duration of the update.
On selected days: Set the day, start time, and duration of the update. If necessary, select multiple options using the Add day and time button.

Set automatic update parameters when creating or updating the Managed Service for Kubernetes cluster:

yc managed-kubernetes cluster <create_or_update> <cluster_name_or_ID> \
...
  --auto-upgrade <automatic_update_mode> \
  --anytime-maintenance-window \
  --daily-maintenance-window <value> \
  --weekly-maintenance-window <value>

Where:

--auto-upgrade: Automatic Managed Service for Kubernetes cluster update mode. The default value is true (automatic updates are enabled).
--anytime-maintenance-window: Random Managed Service for Kubernetes cluster update time.
--daily-maintenance-window: Daily update mode.

Example of updating a Managed Service for Kubernetes cluster daily at 22:00 UTC, with a duration of up to 10 hours:
```
--daily-maintenance-window 'start=22:00,duration=10h'
```
--weekly-maintenance-window: Automatic update on specified days.

Example of updating a Managed Service for Kubernetes cluster on Mondays and Tuesdays starting at 22:00 UTC, with a duration of up to 10 hours:
```
--weekly-maintenance-window 'days=[monday,tuesday],start=22:00,duration=10h'
```
To set multiple maintenance periods, provide the settings of each one in a separate --weekly-maintenance-window argument.

Note

The --daily-maintenance-window and --weekly-maintenance-window arguments require the --auto-upgrade argument set to true. The update schedule will not be created if you set --auto-upgrade=false.

You can get the Managed Service for Kubernetes cluster ID and name with a list of clusters in the folder.

Open the current configuration file with the Managed Service for Kubernetes cluster description.

For information about how to create this file, see Creating a Managed Service for Kubernetes cluster.

Change automatic update settings in the Managed Service for Kubernetes cluster description.

Note

You can select only one of the update modes — daily or on selected days. Concurrent use of update modes is not permitted.

To enable the daily update mode:

resource "yandex_kubernetes_cluster" "<cluster_name>" {
  name = <cluster_name>
  ...
  maintenance_policy {
    auto_upgrade = true
    maintenance_window {
      start_time = "<update_start_time>"
      duration   = "<update_duration>"
    }
  }
}

Where start_time is the update start time in UTC.

To enable updates on selected days (multiple periods are possible):

resource "yandex_kubernetes_cluster" "<cluster_name>" {
  name = <cluster_name>
  ...
  maintenance_policy {
    auto_upgrade = true
    maintenance_window {
      day        = "<update_start_day,_e.g.,_monday>"
      start_time = "<update_start_time,_UTC>"
      duration   = "<update_duration>"
    }
    maintenance_window {
      day        = "<update_start_day,_e.g.,_monday>"
      start_time = "<update_start_time,_UTC>"
      duration   = "<update_duration>"
    }
  }
}

To enable the random update time mode, do not add the maintenance_policy parameter section to the Managed Service for Kubernetes cluster description. If you omit automatic update settings in the Managed Service for Kubernetes cluster description, updates will take place at a random time.

To disable automatic updates:

resource "yandex_kubernetes_cluster" "<cluster_name>" {
  name = "<cluster_name>"
  ...
  maintenance_policy {
    auto_upgrade = false
  }
}

Make sure the configuration files are correct.
1. Using the command line, navigate to the folder that contains the up-to-date Terraform configuration files with an infrastructure plan.
2. Run the command:
```
terraform validate
```
  If there are errors in the configuration files, Terraform will point to them.
Confirm updating the resources.
1. Run the command to view planned changes:
```
terraform plan
```
  If the resource configuration descriptions are correct, the terminal will display a list of the resources to modify and their parameters. This is a test step. No resources are updated.
2. If you are happy with the planned changes, apply them:
  1. Run the command:
```
terraform apply
```
  2. Confirm the update of resources.
  3. Wait for the operation to complete.

For more information, see the Terraform provider documentation.

Set up automatic updates in the masterSpec.maintenancePolicy section when creating a Managed Service for Kubernetes cluster or updating its settings.

Use the update API method and include the following in the request:

Managed Service for Kubernetes cluster ID in the clusterId parameter. To find out the Managed Service for Kubernetes cluster ID, get a list of clusters in the folder.
Automatic update settings in the masterSpec.maintenancePolicy parameter.
List of settings you are changing in the updateMask parameter.

Warning

The API method will assign default values to all the parameters of the object you are modifying unless you explicitly provide them in your request. To avoid this, list the settings you want to change in the updateMask parameter as a single comma-separated string.

To disable automatic updates, provide the false value in the masterSpec.maintenancePolicy.autoUpgrade parameter.

To enable and configure the update window, provide one of the allowed values of the maintenanceWindow parameter:

For a Managed Service for Kubernetes cluster to be updated at a random time, provide the "anytime": {} value.

To set up daily updates, add the dailyMaintenanceWindow section:

"dailyMaintenanceWindow": {
  "startTime": {
    "hours": "<update_start_hour>",
    "minutes": "<update_start_minute>",
    "seconds": "<update_start_second>",
    "nanos": "<update_start_fraction_of_second>"
  },
  "duration": "<duration_of_update_period>"
}

Where:

hours: Update start hour in UTC.
nanos: Fraction of a second of update start, in nanoseconds.
duration: Duration of update period, hours.

For updates to take place on selected days, add the weeklyMaintenanceWindow section:

"weeklyMaintenanceWindow": {
  "daysOfWeek": [
    {
      "days": [
        "<list_of_days>"
      ],
      "startTime": {
        "hours": "<update_start_hour>",
        "minutes": "<update_start_minute>",
        "seconds": "<update_start_second>",
        "nanos": "<update_start_fraction_of_second>"
      },
      "duration": "<duration_of_update_period>"
    }
  ]
}

Where:

days: List of days, for example: monday, tuesday.
hours: Update start hour in UTC.
nanos: Fraction of a second of update start, in nanoseconds.
duration: Duration of update period, hours.

Manually updating the cluster version

If necessary, update the Managed Service for Kubernetes cluster version manually. You can only update your Managed Service for Kubernetes cluster in a single step to the next minor version from the current one. Updating to newer versions is done in steps, e.g.: 1.19 → 1.20 → 1.21.

Management console

CLI

Terraform

API

Go to the folder page and select Managed Service for Kubernetes.
Click the name of the Managed Service for Kubernetes cluster.
Click Edit in the top-right corner.
In the Kubernetes version field, select the Upgrade to version <version_number> option.
Click Save.

Specify the new Kubernetes version in the --version argument:

yc managed-kubernetes cluster update <cluster_name_or_ID> \
  --version <new_version>

You can get the Managed Service for Kubernetes cluster ID and name with a list of clusters in the folder.

Open the current configuration file with the Managed Service for Kubernetes cluster description.

For more information about creating this file, see Creating a Managed Service for Kubernetes cluster.

Change the version in the Managed Service for Kubernetes cluster description:

resource "yandex_kubernetes_cluster" "<cluster_name>" {
  name = <cluster_name>
  ...
  version = "<new_version>"
}

Make sure the configuration files are correct.
1. Using the command line, navigate to the folder that contains the up-to-date Terraform configuration files with an infrastructure plan.
2. Run the command:
```
terraform validate
```
  If there are errors in the configuration files, Terraform will point to them.
Confirm updating the resources.
1. Run the command to view planned changes:
```
terraform plan
```
  If the resource configuration descriptions are correct, the terminal will display a list of the resources to modify and their parameters. This is a test step. No resources are updated.
2. If you are happy with the planned changes, apply them:
  1. Run the command:
```
terraform apply
```
  2. Confirm the update of resources.
  3. Wait for the operation to complete.

For more information, see the Terraform provider documentation.

Use the update API method and include the following in the request:

Managed Service for Kubernetes cluster ID in the clusterId parameter. To find out the Managed Service for Kubernetes cluster ID, get a list of clusters in the folder.
Required Kubernetes version in the masterSpec.version.version parameter.
List of settings you are changing in the updateMask parameter.

Warning

Updating a node group

Configuring automatic updates of a node group

Select automatic update mode for the Managed Service for Kubernetes node group and set the required update schedule:

Management console

CLI

Terraform

API

You can specify update settings when creating a Managed Service for Kubernetes cluster or updating its settings.

In the Allow when creating and updating field, specify scaling settings of the Managed Service for Kubernetes node group:

Max expansion of group size: Set the maximum number of instances by which you can exceed the size of the Managed Service for Kubernetes node group when updating it.
Max reduction of group size: Set the maximum number of instances by which you can reduce the size of the Managed Service for Kubernetes node group when updating it.

In the Maintenance frequency / Disable field, select the Managed Service for Kubernetes node group update policy:

Disabled: Select this option not to use automatic updates.
Anytime: Select this option for Managed Service for Kubernetes to manage the update installation schedule.
Daily: Set the start time and duration of the update.
On selected days: Set the day, start time, and duration of the update. If necessary, select multiple options using the Add day and time button.

Set automatic update parameters when creating or updating a Managed Service for Kubernetes node group.

yc managed-kubernetes node-group <create_or_update> <node_group_name_or_ID> \
...
  --max-expansion <number_of_VMs> \
  --max-unavailable <number_of_VMs> \
  --auto-upgrade <automatic_update_mode> \
  --auto-repair <recreation_mode> \
  --anytime-maintenance-window \
  --daily-maintenance-window <value> \
  --weekly-maintenance-window <value>

Where:

--max-expansion: Maximum number of instances by which you can exceed the size of the Managed Service for Kubernetes node group when updating it.
--max-unavailable: Maximum number of instances by which you can reduce the size of the Managed Service for Kubernetes node group when updating it.

Note

The --max-expansion and --max-unavailable flags should be used together.
--auto-upgrade: Automatic update mode for the Managed Service for Kubernetes node group. The default value is true (automatic updates are enabled). Possible values: true or false.
--auto-repair: Failed node recreation mode. Possible values: true or false.

--auto-repair is at the Preview stage.
--anytime-maintenance-window: Random update time for the Managed Service for Kubernetes node group.
--daily-maintenance-window: Daily update mode.

Example of updating a Managed Service for Kubernetes node group daily at 22:00 UTC, with a duration of up to 10 hours:
```
--daily-maintenance-window 'start=22:00,duration=10h'
```
--weekly-maintenance-window: Automatic update on specified days.

Example of updating a Managed Service for Kubernetes node group on Mondays and Tuesdays from 22:00 UTC, with a duration of up to 10 hours:
```
--weekly-maintenance-window 'days=[monday,tuesday],start=22:00,duration=10h'
```
To set multiple maintenance periods, provide the settings of each one in a separate --weekly-maintenance-window argument.

Note

The --daily-maintenance-window and --weekly-maintenance-window arguments require the --auto-upgrade argument set to true.

The update schedule will not be created if you set --auto-upgrade=false.

You can get the Managed Service for Kubernetes node group ID and name with a list of the groups in the cluster.

Open the current configuration file describing the Managed Service for Kubernetes node group.

For more information about creating this file, see Creating a node group.

Change automatic update settings in the Managed Service for Kubernetes node group description.

Note

You can select only one of the update modes — daily or on selected days. Concurrent use of update modes is not permitted.

To enable the daily update mode:

resource "yandex_kubernetes_node_group" "<node_group_name>" {
  name = <node_group_name>
  ...
  maintenance_policy {
    auto_upgrade = true
    maintenance_window {
      start_time = "<update_start_time>"
      duration   = "<update_duration>"
    }
  }
}

Where start_time is the update start time in UTC.

To enable updates on selected days (multiple periods are possible):

resource "yandex_kubernetes_node_group" "<node_group_name>" {
  name = <node_group_name>
  ...
  maintenance_policy {
    auto_upgrade = true
    maintenance_window {
      day        = "<update_start_day,_e.g.,_monday>"
      start_time = "<update_start_time,_UTC>"
      duration   = "<update_duration>"
    }
    maintenance_window {
      day        = "<update_start_day,_e.g.,_monday>"
      start_time = "<update_start_time,_UTC>"
      duration   = "<update_duration>"
    }
  }
}

To enable the random update time mode, do not add the maintenance_policy parameter section to the Managed Service for Kubernetes node group description. If you omit automatic update settings in the Managed Service for Kubernetes node group description, updates will take place at a random time.

To configure the Managed Service for Kubernetes node group scaling settings applied at updates:

resource "yandex_kubernetes_node_group" "<node_group_name>" {
  name = <node_group_name>
  ...
  deploy_policy {
    max_expansion   = <maximum_number_of_instances_by_which_you_can_exceed_node_group_size>
    max_unavailable = <maximum_number_of_instances_by_which_you_can_reduce_node_group_size>
  }
}

Note

The max_expansion and max_unavailable parameters should be used together.

To disable automatic updates:

resource "yandex_kubernetes_node_group" "<node_group_name>" {
  name = "<node_group_name>"
  ...
  maintenance_policy {
    auto_upgrade = false
  }
}

Make sure the configuration files are correct.
1. Using the command line, navigate to the folder that contains the up-to-date Terraform configuration files with an infrastructure plan.
2. Run the command:
```
terraform validate
```
  If there are errors in the configuration files, Terraform will point to them.
Confirm updating the resources.
1. Run the command to view planned changes:
```
terraform plan
```
  If the resource configuration descriptions are correct, the terminal will display a list of the resources to modify and their parameters. This is a test step. No resources are updated.
2. If you are happy with the planned changes, apply them:
  1. Run the command:
```
terraform apply
```
  2. Confirm the update of resources.
  3. Wait for the operation to complete.

For more information, see the Terraform provider documentation.

You can set up automatic updates under maintenancePolicy when creating a Managed Service for Kubernetes node group or updating its settings.

Use the update API method and include the following in the request:

Managed Service for Kubernetes node group ID in the nodeGroupId parameter. To find out the Managed Service for Kubernetes node group ID, get a list of groups in the cluster.
Automatic update settings in the maintenancePolicy parameter.
List of settings you are changing in the updateMask parameter.

Warning

To disable automatic updates, provide the false value in the maintenancePolicy.autoUpgrade parameter.

To enable and configure the update window, provide one of the allowed values of the maintenanceWindow parameter:

For a Managed Service for Kubernetes node group to be updated at a random time, provide the "anytime": {} value.

To set up daily updates, add the dailyMaintenanceWindow section:

"dailyMaintenanceWindow": {
  "startTime": {
    "hours": "<update_start_hour>",
    "minutes": "<update_start_minute>",
    "seconds": "<update_start_second>",
    "nanos": "<update_start_fraction_of_second>"
  },
  "duration": "<duration_of_update_period>"
}

Where:

hours: Update start hour in UTC.
nanos: Fraction of a second of update start, in nanoseconds.
duration: Duration of update period, hours.

For updates to take place on selected days, add the weeklyMaintenanceWindow section:

"weeklyMaintenanceWindow": {
  "daysOfWeek": [
    {
      "days": [
        "<list_of_days>"
      ],
      "startTime": {
        "hours": "<update_start_hour>",
        "minutes": "<update_start_minute>",
        "seconds": "<update_start_second>",
        "nanos": "<update_start_fraction_of_second>"
      },
      "duration": "<duration_of_update_period>"
    }
  ]
}

Where:

days: List of days, for example: monday, tuesday.
hours: Update start hour in UTC.
nanos: Fraction of a second of update start, in nanoseconds.
duration: Duration of update period, hours.

To set the scaling of a Managed Service for Kubernetes node group, add the deployPolicy section:

"deployPolicy": {
  "maxUnavailable": "<maximum_number_of_instances>",
  "maxExpansion": "<maximum_number_of_instances>"
}

Where:

maxUnavailable: Maximum number of instances by which you can reduce the size of the node group.
maxExpansion: Maximum number of instances by which you can exceed the size of the node group.

Manually updating a node group version

If necessary, update the Managed Service for Kubernetes node group version manually. You can only update to the next minor version from the current one. Updating to newer versions is done in steps, e.g.: 1.19 → 1.20 → 1.21.

Warning

Update the Managed Service for Kubernetes cluster version before updating the node group.

Management console

CLI

Terraform

API

Go to the folder page and select Managed Service for Kubernetes.
Click the name of the Managed Service for Kubernetes cluster.
Go to the Nodes manager tab.
Select the Managed Service for Kubernetes node group from the list.
Click Edit in the top-right corner.
In the Kubernetes version field, select the Upgrade to version <version_number> option.
Click Save.

Set automatic update parameters:

yc managed-kubernetes node-group update <node_group_ID_or_name> \
...
  --version <new_version>

You can get the Managed Service for Kubernetes node group ID and name with a list of the groups in the cluster.

Open the current configuration file describing the Managed Service for Kubernetes node group.

For more information about creating this file, see Creating a node group.

Change the version in the Managed Service for Kubernetes node group description:

resource "yandex_kubernetes_node_group" "<node_group_name>" {
  name = <node_group_name>
  ...
  version = "<new_version>"
}

Make sure the configuration files are correct.
1. Using the command line, navigate to the folder that contains the up-to-date Terraform configuration files with an infrastructure plan.
2. Run the command:
```
terraform validate
```
  If there are errors in the configuration files, Terraform will point to them.
Confirm updating the resources.
1. Run the command to view planned changes:
```
terraform plan
```
  If the resource configuration descriptions are correct, the terminal will display a list of the resources to modify and their parameters. This is a test step. No resources are updated.
2. If you are happy with the planned changes, apply them:
  1. Run the command:
```
terraform apply
```
  2. Confirm the update of resources.
  3. Wait for the operation to complete.

For more information, see the Terraform provider documentation.

Use the update API method and include the following in the request:

Managed Service for Kubernetes node group ID in the nodeGroupId parameter. To find out the Managed Service for Kubernetes node group ID, get a list of groups in the cluster.
Required Kubernetes version in the version.version parameter.
List of settings you are changing in the updateMask parameter.

Warning