Yandex Cloud
Documentation
PresentationContact UsTry it for free
© 2026 Direct Cursus Technology L.L.C.
Tutorials
    • All tutorials
    • Setting up a Managed Service for PostgreSQL connection from Serverless Containers
    • Creating a VM from a Container Optimized Image
    • Creating a VM from a Container Optimized Image with an additional volume for a Docker container
    • Creating an instance group from a Container Optimized Image with multiple Docker containers
    • Creating an instance group from a Container Optimized Image
    • Creating a VM from a Container Optimized Image with multiple Docker containers
    • Updating a Container Optimized Image VM
    • Configuring data output from a Docker container to a serial port
    • Running a Docker image on a VM using Cloud Registry
      • Creating a new Kubernetes project
      • Creating a Kubernetes cluster with no internet access
      • Creating a Kubernetes cluster using the Yandex Cloud provider for the Kubernetes Cluster API
      • Running workloads with GPUs
      • Using node groups with GPUs and no pre-installed drivers
      • Setting up time-slicing GPUs
      • Migrating resources to a different availability zone
      • Encrypting secrets
      • Connecting a BareMetal server as an external node to a Managed Service for Kubernetes cluster

In this article:

  • Getting started
  • Required paid resources
  • Migrate the master to a different availability zone
  • Migrating a highly-available master
  • Restore Cilium webhook availability
  • Migrate the node group and pod workload to a different availability zone
  • Getting started
  • Migrating stateless workloads
  • Migrating stateful workloads
  • Gradually migrating stateless and stateful workloads
  1. Container infrastructure
  2. Managed Service for Kubernetes
  3. Migrating resources to a different availability zone

Migrating Yandex Managed Service for Kubernetes resources to a different availability zone

Written by
Yandex Cloud
Updated at November 12, 2026
View in Markdown
  • Getting started
  • Required paid resources
  • Migrate the master to a different availability zone
    • Migrating a highly-available master
    • Restore Cilium webhook availability
  • Migrate the node group and pod workload to a different availability zone
    • Getting started
    • Migrating stateless workloads
    • Migrating stateful workloads
    • Gradually migrating stateless and stateful workloads

In a Managed Service for Kubernetes cluster, you can migrate a highly available master, as well as a node group and pod workload from one availability zone to another.

Getting startedGetting started

If you do not have the Yandex Cloud CLI yet, install and initialize it.

The folder used by default is the one specified when creating the CLI profile. To change the default folder, use the yc config set folder-id <folder_ID> command. You can also specify a different folder for any command using --folder-name or --folder-id.

If you access a resource by its name, the search will be limited to the default folder. If you access a resource by its ID, the search will be global, i.e., through all folders based on access permissions.

If you have already installed the CLI, update to its latest version:

yc components update

Required paid resourcesRequired paid resources

  • Managed Service for Kubernetes master (see Managed Service for Kubernetes pricing).
  • Managed Service for Kubernetes cluster nodes: use of computing resources and storage (see Yandex Compute Cloud pricing).
  • Public IP addresses for the Managed Service for Kubernetes cluster's master and nodes with public access enabled (see Yandex Virtual Private Cloud pricing).

Migrate the master to a different availability zoneMigrate the master to a different availability zone

This section describes migrating a highly available master from zone ru-central1-b to zone ru-central1-e. Hosting in ru-central1-a and ru-central1-d remains in effect.

Warning

In clusters using Cilium, webhooks may become unavailable after you migrate the master. For troubleshooting, see Restore Cilium webhook availability.

Migrating a highly-available masterMigrating a highly-available master

A highly available master is deployed across three subnets in different availability zones. For the migration, specify all the three subnets with their zones: two existing ones and your new one. The new subnet must reside in the same cloud network as the cluster.

To migrate a highly-available master to a different combination of availability zones:

CLI
Terraform

If you do not have the Yandex Cloud CLI yet, install and initialize it.

The folder used by default is the one specified when creating the CLI profile. To change the default folder, use the yc config set folder-id <folder_ID> command. You can also specify a different folder for any command using --folder-name or --folder-id.

If you access a resource by its name, the search will be limited to the default folder. If you access a resource by its ID, the search will be global, i.e., through all folders based on access permissions.

  1. View the description of the following cluster modification command:

    yc managed-kubernetes cluster update --help
    
  2. Create a subnet in the ru-central1-e availability zone:

    yc vpc subnet create \
       --folder-id <folder_ID> \
       --name <subnet_name> \
       --zone ru-central1-e \
       --network-id <network_ID> \
       --range <subnet_CIDR>
    

    In the command, specify the following subnet settings:

    • --folder-id: Folder ID.
    • --name: Subnet name.
    • --zone: Availability zone.
    • --network-id: ID of the network that contains the new subnet.
    • --range: List of IPv4 addresses for incoming or outgoing traffic, e.g., 10.0.0.0/22 or 192.168.0.0/16. Make sure the addresses are unique within the network. The minimum subnet size is /28, while the maximum subnet size is /16. Only IPv4 is supported.
  3. Migrate the master to a different combination of availability zones:

    yc managed-kubernetes cluster update \
       --folder-id <folder_ID> \
       --id <cluster_ID> \
       --master-location subnet-id=<subnet_a_ID>,zone=ru-central1-a \
       --master-location subnet-id=<subnet_d_ID>,zone=ru-central1-d \
       --master-location subnet-id=<new_subnet_ID>,zone=ru-central1-e
    

    Where:

    • --folder-id: Folder ID. Treat this parameter as optional if the folder is specified in the CLI profile.

    • --id: Cluster ID. This is a required setting.

    • --master-location: Master hosting parameters. Specify this three times, one for each zone:

      • subnet-id: Subnet ID.
      • zone: Availability zone.

      For ru-central1-a and ru-central1-d, specify the current subnets; and for ru-central1-e, your new one.

If you do not have Terraform yet, install it and configure the Yandex Cloud provider.

To manage infrastructure using Terraform under a service account or user accounts (a Yandex account, a federated account, or a local user), authenticate using the appropriate method.

Alert

To make sure your cluster and any of its node groups are not recreated (unless it is your intention to do so), analyze the output of the terraform plan and terraform apply commands before applying the configuration.

You can only migrate a master host to a different availability zone without recreating the cluster if the configuration file contains the master_location section.

  1. If the cluster configuration includes a regional block, replace it with three master_location blocks, while retaining the current zone and subnet values. If the master_location blocks are already in use, proceed to creating a new subnet.

    Configuration snippets are shown below. Keep the resource name in the configuration, and leave the rest yandex_kubernetes_cluster resource parameters unchanged.

    Old format:

    resource "yandex_kubernetes_cluster" "k8s-cluster" {
       ...
       master {
          ...
          regional {
             region = "ru-central1"
             location {
                subnet_id = yandex_vpc_subnet.my-subnet-a.id
                zone      = yandex_vpc_subnet.my-subnet-a.zone
             }
             location {
                subnet_id = yandex_vpc_subnet.my-subnet-d.id
                zone      = yandex_vpc_subnet.my-subnet-d.zone
             }
             location {
                subnet_id = yandex_vpc_subnet.my-subnet-b.id
                zone      = yandex_vpc_subnet.my-subnet-b.zone
             }
          }
       }
       ...
    }
    

    New format:

    resource "yandex_kubernetes_cluster" "k8s-cluster" {
       ...
       master {
          ...
          master_location {
             subnet_id = yandex_vpc_subnet.my-subnet-a.id
             zone      = yandex_vpc_subnet.my-subnet-a.zone
          }
          master_location {
             subnet_id = yandex_vpc_subnet.my-subnet-d.id
             zone      = yandex_vpc_subnet.my-subnet-d.zone
          }
          master_location {
             subnet_id = yandex_vpc_subnet.my-subnet-b.id
             zone      = yandex_vpc_subnet.my-subnet-b.zone
          }
       }
       ...
    }
    
  2. Make sure no changes have been found in the Terraform resource settings:

    terraform plan
    

    If Terraform detects changes, validate all cluster parameter values: they should match the current state.

  3. Add the new subnet's manifest to the cluster configuration file and update the cluster location:

    resource "yandex_vpc_subnet" "my-subnet-e" {
       name           = "<subnet_name>"
       zone           = "ru-central1-e"
       network_id     = yandex_vpc_network.k8s-network.id
       v4_cidr_blocks = ["<subnet_CIDR>"]
    }
    
    ...
    
    resource "yandex_kubernetes_cluster" "k8s-cluster" {
       ...
       master {
          ...
          master_location {
             subnet_id = yandex_vpc_subnet.my-subnet-a.id
             zone      = yandex_vpc_subnet.my-subnet-a.zone
          }
          master_location {
             subnet_id = yandex_vpc_subnet.my-subnet-d.id
             zone      = yandex_vpc_subnet.my-subnet-d.zone
          }
          master_location {
             subnet_id = yandex_vpc_subnet.my-subnet-e.id
             zone      = yandex_vpc_subnet.my-subnet-e.zone
          }
          ...
       }
    ...
    }
    

    This will replace cluster's my-subnet-b with my-subnet-e with these settings:

    • name: Subnet name.
    • zone: Availability zone.
    • network_id: ID of the network that contains the new subnet.
    • v4_cidr_blocks: List of IPv4 addresses for incoming or outgoing traffic, e.g., 10.0.0.0/22 or 192.168.0.0/16. Make sure the addresses are unique within the network. The minimum subnet size is /28, while the maximum subnet size is /16. Only IPv4 is supported.
  4. Make sure the configuration file is correct.

    1. In the command line, navigate to the directory that contains the current Terraform configuration files defining the infrastructure.

    2. Run this command:

      terraform validate
      

      Terraform will show any errors found in your configuration files.

  5. Confirm resource changes. Before applying, make sure the plan does not provide for deleting or re-creating your cluster and its node groups.

    1. Run this command to view the intended changes:

      terraform plan
      

      If you described the configuration correctly, the terminal will display a list of the resources to update and their parameters. This is a verification step that does not apply changes to your resources.

    2. If everything looks correct, apply the changes:

      1. Run this command:

        terraform apply
        
      2. Confirm updating the resources.

      3. Wait for the operation to complete.

For details on the properties of the yandex_kubernetes_cluster resource, see this provider guide.

Restore Cilium webhook availabilityRestore Cilium webhook availability

Once the master migrates, in clusters using Cilium, mutating and validating webhooks associated with the migrated master may become unavailable.

If you encounter this issue:

  1. Connect to the cluster using the Kubernetes CLI (kubectl).

  2. Get a list of CiliumNode objects:

    kubectl get ciliumnodes
    
  3. Locate the old master object from the original availability zone. For example, when migrating from ru-central1-b, its name is formatted like mk8s-master-<ID>-b.

  4. Delete only the CiliumNode object that refers to the old master:

    kubectl delete ciliumnode <old_master_object_name>
    
  5. Check whether your webhooks are available again. If the issue persists, contact support.

Migrate the node group and pod workload to a different availability zoneMigrate the node group and pod workload to a different availability zone

Set up the node group and proceed with migration using one of the following methods:

  • Migrating a node group directly to the new availability zone. It depends on the type of workload in the pods:

    • Stateless workload: Application functioning in pods during migration depends on how workload is distributed between cluster nodes. If the pods reside both in the node group you are migrating and the groups for which the availability zone remains unchanged, the applications keep running. If the pods only reside in the group you are migrating, both the pods and the applications in them must be briefly stopped.

      Stateless workload examples include the web server, Yandex Application Load Balancer ingress controller, and REST API apps.

    • Stateful workloads: Pods and applications must be briefly stopped, regardless of how workload is distributed between cluster nodes.

      Stateful workload examples include databases and storages.

  • Gradually migrating stateless and stateful workloads to a new node group: It involves creating a new node group in the new availability zone and gradually discontinuing the old nodes. This enables you to manage workload transfer.

Getting startedGetting started

  1. Check if the nodeSelector, affinity, or topology spread constraints strategies are used to assign the pods to the group's nodes. For more information on strategies, see this Kubernetes article and this section. To check a pod's assignment to nodes and remove it:

    Management console
    1. In the management console, select the folder with your Managed Service for Kubernetes cluster.

    2. Navigate to Managed Service for Kubernetes.

    3. Select the Managed Service for Kubernetes cluster.

    4. Navigate to the Workload tab, then to Pods.

    5. Select the pod and navigate to the YAML tab.

    6. Check if the pod manifest contains the following parameters and Kubernetes labels in them:

      • Parameters:

        • spec.nodeSelector
        • spec.affinity
        • spec.topologySpreadConstraints
      • Kubernetes labels set in the parameters:

        • failure-domain.beta.kubernetes.io/zone: <availability_zone>
        • topology.kubernetes.io/zone: <availability_zone>

      When the configuration includes at least one of these parameters containing at least one of the listed Kubernetes labels, node group and workload migration will not proceed.

    7. Check the pod manifest for dependencies on the following entities:

      • Availability zone you are migrating your resources from.
      • Specific nodes within the group.
    8. If you find any of the parameters, assignments, or dependencies listed above, remove them from the pod configuration:

      1. Copy the YAML configuration from the management console.

      2. Create a local YAML file and paste the copied configuration into it.

      3. Remove any availability zone assignments from the configuration. For example, if the spec.affinity parameter includes the failure-domain.beta.kubernetes.io/zone Kubernetes label, remove it.

      4. Apply the new configuration:

        kubectl apply -f <YAML_file_path>
        
      5. Make sure the pod status changed to Running:

        kubectl get pods
        
    9. Repeat these steps for each pod to check and update its configuration.

  2. Transfer persistent data, such as databases, message queues, monitoring servers, and log servers, to the new availability zone.

Migrating stateless workloadsMigrating stateless workloads

  1. Create a subnet in the new availability zone and migrate the node group:

    CLI
    Terraform
    1. Create a subnet:

      yc vpc subnet create \
         --name <subnet_name> \
         --zone <availability_zone> \
         --network-id <network_ID> \
         --range <subnet_CIDR>
      

      Where:

      • --name: Subnet name.
      • --zone: Availability zone, ru-central1-a, ru-central1-b, or ru-central1-d.
      • --network-id: ID of the network that contains the new subnet.
      • --range: List of IPv4 addresses for incoming or outgoing traffic, e.g., 10.0.0.0/22 or 192.168.0.0/16. Make sure the addresses are unique within the network. The minimum subnet size is /28, while the maximum subnet size is /16. Only IPv4 is supported.
    2. Migrate the node group to the new availability zone. The example below shows a command for migrating a group placed in a single zone:

      yc managed-kubernetes node-group update \
         --id <node_group_ID> \
         --location zone=<availability_zone>,subnet-id=<subnet_ID> \
         --network-interface subnets=<subnet_ID>,`
              `ipv4-address=nat,`
              `security-group-ids=[<security_group_IDs>]
      

      Where:

      • id: ID of the node group you want to migrate to a different availability zone.
      • zone: Availability zone you want to migrate your node group to, ru-central1-a, ru-central1-b, or ru-central1-d.
      • subnet_id and subnets: ID of the new subnet you created earlier.
      • ipv4-address: IPv4 address assignment method. The nat value allows assigning public and internal IP addresses to nodes.
      • security-group-ids: List of security group IDs.

      Warning

      If you want to keep the values of other network parameters for the node group, specify them in the network-interface parameter as well. Otherwise, the group may be recreated with default values. For more information, see Updating a Managed Service for Kubernetes node group.

      Make sure to provide the ipv4-address and security-group-ids parameters in the command: this will allow assigning public IP addresses to the node group and keeping security groups within it.

      This command recreates the nodes within their group in the specified availability zone and subnet. When recreating, the deployment settings are considered: the maximum number of nodes by which you can increase or decrease the group size against the initial number of nodes.

      How to migrate a node group placed in different availability zones

      In this case, use the following command:

      yc managed-kubernetes node-group update \
         --id <node_group_ID> \
         --location zone=<availability_zone>,subnet-id=<subnet_ID> \
         ...
         --location zone=<availability_zone>,subnet-id=<subnet_ID> \
         --network-interface subnets=[<subnet_IDs>],`
              `ipv4-address=nat,`
              `security-group-ids=[<security_group_IDs>]
      

      Where:

      • id: ID of the node group you want to migrate to a different availability zone.
      • zone: Availability zone, ru-central1-a, ru-central1-b, or ru-central1-d. Specify the location parameters for each availability zone that will host the node group.
      • subnet-id and subnets: IDs of the subnets for the specified availability zones.
      • ipv4-address: IPv4 address assignment method. The nat value allows assigning public and internal IP addresses to nodes.
      • security-group-ids: List of security group IDs.

    Alert

    To make sure your node group is not recreated (unless it is your intention to do so), analyze the output of the terraform plan and terraform apply commands before applying the configuration.

    You can migrate a node group to a different availability zone without recreating it only if the configuration file contains the allocation_policy section.

    1. Edit the configuration file as follows:

      • Add a new subnet manifest (the yandex_vpc_subnet resource) in the availability zone to which you want to migrate the node group.
      • Change the node group location parameters (the yandex_kubernetes_node_group resource):
        • allocation_policy.location.subnet_id: Remove this parameter from the manifest.
        • allocation_policy.location.zone: Specify the availability zone you want to migrate the node group to.
        • instance_template.network_interface.subnet_ids: Specify the new subnet ID. Add this parameter to the manifest if missing.
      resource "yandex_vpc_subnet" "my-new-subnet" {
         name           = "<subnet_name>"
         zone           = "<availability_zone>"
         network_id     = "<network_ID>"
         v4_cidr_blocks = ["<subnet_CIDR>"]
      }
      ...
      resource "yandex_kubernetes_node_group" "k8s-node-group" {
         allocation_policy {
            location {
               zone = "<availability_zone>"
            }
         }
         ...
         instance_template {
            network_interface {
               subnet_ids = [yandex_vpc_subnet.my-new-subnet.id]
               ...
            }
            ...
         }
         ...
      }
      

      Where:

      • name: Subnet name.
      • zone: Availability zone you want to migrate your node group to, ru-central1-a, ru-central1-b, or ru-central1-d.
      • network_id: ID of the network that contains the new subnet.
      • v4_cidr_blocks: List of IPv4 addresses for incoming or outgoing traffic, e.g., 10.0.0.0/22 or 192.168.0.0/16. Make sure the addresses are unique within the network. The minimum subnet size is /28, while the maximum subnet size is /16. Only IPv4 is supported.
      • subnet_ids: New subnet ID.
    2. Make sure the configuration file is correct.

      1. In the command line, navigate to the directory that contains the current Terraform configuration files defining the infrastructure.

      2. Run this command:

        terraform validate
        

        Terraform will show any errors found in your configuration files.

    3. Confirm updating the resources.

      1. Run this command to view the intended changes:

        terraform plan
        

        If you described the configuration correctly, the terminal will display a list of the resources to update and their parameters. This is a verification step that does not apply changes to your resources.

      2. If everything looks correct, apply the changes:

        1. Run this command:

          terraform apply
          
        2. Confirm updating the resources.

        3. Wait for the operation to complete.

    The group nodes will be recreated in the specified availability zone and subnet. When recreating, the deployment settings are considered: the maximum number of nodes by which you can increase or decrease the group size against the initial number of nodes.

  2. Make sure the pods are running in the migrated node group:

    kubectl get po --output wide
    

    The output of this command shows the nodes on which your pods are currently running.

Migrating stateful workloadsMigrating stateful workloads

The migration is based on scaling the StatefulSet controller. To migrate stateful workloads:

  1. Get a list of StatefulSet controllers to find the name of the one you need:

    kubectl get statefulsets
    
  2. Get the number of pods managed by the controller:

    kubectl get statefulsets <controller_name> \
       -n default -o=jsonpath='{.status.replicas}'
    

    Save this value. You will need it to scale the StatefulSet controller once the migration of your stateful workloads is complete.

  3. Reduce the number of pods to zero:

    kubectl scale statefulset <controller_name> --replicas=0
    

    This will stop the pods that are using disks, while retaining the PersistentVolumeClaim Kubernetes API object (PVC).

  4. For the PersistentVolume object (PV) associated with PersistentVolumeClaim, change the persistentVolumeReclaimPolicy value from Delete to Retain to prevent accidental data loss.

    1. Get the name of the PersistentVolume object:

      kubectl get pv
      
    2. Edit the PersistentVolume object:

      kubectl edit pv <PV_name>
      
  5. Check if the PersistentVolume object manifest contains the spec.nodeAffinity parameter:

    kubectl get pv <PV_name> --output='yaml'
    

    If the manifest contains the spec.nodeAffinity parameter with an availability zone specified in it, save this parameter. You will need to specify it in a new PersistentVolume object.

  6. Create a PersistentVolume snapshot. Learn more about snapshots in the relevant Kubernetes guide.

    1. Get the name of the PersistentVolumeClaim object:

      kubectl get pvc
      
    2. Create the snapshot.yaml with the snapshot manifest and specify the PersistentVolumeClaim name in it:

      apiVersion: snapshot.storage.k8s.io/v1
      kind: VolumeSnapshot
      metadata:
         name: new-snapshot-test-<number>
      spec:
         volumeSnapshotClassName: yc-csi-snapclass
         source:
            persistentVolumeClaimName: <PVC_name>
      

      If you are creating several snapshots for different PersistentVolumeClaim objects, specify the <number> (consecutive) to make sure each snapshot gets a unique metadata.name value.

    3. Create a snapshot:

      kubectl apply -f snapshot.yaml
      
    4. Make sure the snapshot was created:

      kubectl get volumesnapshots.snapshot.storage.k8s.io
      
    5. Make sure the VolumeSnapshotContent Kubernetes API object was created:

      kubectl get volumesnapshotcontents.snapshot.storage.k8s.io
      
  7. Get the snapshot ID:

    yc compute snapshot list
    
  8. Create a VM disk from the snapshot:

    yc compute disk create \
       --source-snapshot-id <snapshot_ID> \
       --zone <availability_zone>
    

    In the command, specify the availability zone to which you are migrating your Managed Service for Kubernetes node group.

    Save the following parameters from the command output:

    • Disk ID from the id field.
    • Disk type from the type_id field.
    • Disk size from the size field.
  9. Create a PersistentVolume Kubernetes API object from the new disk:

    1. Create the persistent-volume.yaml file with the PersistentVolume manifest:

      apiVersion: v1
      kind: PersistentVolume
      metadata:
         name: new-pv-test-<number>
      spec:
         capacity:
            storage: <PersistentVolume_size>
         accessModes:
            - ReadWriteOnce
         csi:
            driver: disk-csi-driver.mks.ycloud.io
            fsType: ext4
            volumeHandle: <disk_ID>
         storageClassName: <disk_type>
      

      In the file, specify the parameters of the disk created from the snapshot:

      • spec.capacity.storage: Disk size.

      • spec.csi.volumeHandle: Disk ID.

      • spec.storageClassName: Disk type. Specify it in accordance with the following table:

        Snapshot-based disk type Disk type for the YAML file
        network-ssd yc-network-ssd
        network-ssd-nonreplicated yc-network-ssd-nonreplicated
        network-nvme yc-network-nvme
        network-hdd yc-network-hdd

      If you are creating several PersistentVolume objects, specify the <number> (consecutive) to make sure each gets a unique metadata.name value.

      Add the previously saved spec.nodeAffinity parameter to the manifest and specify the availability zone to which you are migrating your Managed Service for Kubernetes node group. If you skip it, the workload may run in a different availability zone where PersistentVolume is not available, causing an error.

      Here is an example of the spec.nodeAffinity parameter:

      spec:
         ...
         nodeAffinity:
            required:
               nodeSelectorTerms:
               - matchExpressions:
                  - key: failure-domain.beta.kubernetes.io/zone
                    operator: In
                    values:
                       - ru-central1-d
      
    2. Create a PersistentVolume object:

      kubectl apply -f persistent-volume.yaml
      
    3. Make sure PersistentVolume was created:

      kubectl get pv
      

      The command output will display the new-pv-test<number> object.

    4. If you specified the spec.nodeAffinity parameter in the manifest, make sure to apply it for the PersistentVolume object:

      Management console
      1. In the management console, select the folder with your Managed Service for Kubernetes cluster.

      2. Navigate to Managed Service for Kubernetes.

      3. Select the Managed Service for Kubernetes cluster.

      4. Navigate to the Persistent volumes tab, and then to PersistentVolumes.

      5. Find the new-pv-test-<number> object.

        View the Availability zone field value of the object. It should specify an availability zone. A dash means there is no assignment to an availability zone.

    5. If you skipped the spec.nodeAffinity parameter in the manifest, you can add it by editing the PersistentVolume object:

      kubectl edit pv new-pv-test-<number>
      
  10. Create a PersistentVolumeClaim object from the new PersistentVolume:

    1. Create the persistent-volume-claim.yaml file with the PersistentVolumeClaim manifest:

      apiVersion: v1
      kind: PersistentVolumeClaim
      metadata:
         name: <PVC_name>
      spec:
         accessModes:
            - ReadWriteOnce
         resources:
            requests:
               storage: <PV_size>
         storageClassName: <disk_type>
         volumeName: new-pv-test-<number>
      

      In the file, set the following parameters:

      • metadata.name: Name of the PersistentVolumeClaim object you used to create the snapshot. You can get this name by running the kubectl get pvc command.
      • spec.resources.requests.storage: PersistentVolume size, which matches the size of the created disk.
      • spec.storageClassName: PersistentVolume disk type, which matches the disk type of the new PersistentVolume.
      • spec.volumeName: Name of the PersistentVolume object to base PersistentVolumeClaim on. You can get this name by running the kubectl get pv command.
    2. Delete the original PersistentVolumeClaim so you can replace it:

      kubectl delete pvc <PVC_name>
      
    3. Create a PersistentVolumeClaim object:

      kubectl apply -f persistent-volume-claim.yaml
      
    4. Make sure PersistentVolumeClaim was created:

      kubectl get pvc
      

      The command output will return the PersistentVolumeClaim size you specified in the YAML file.

  11. Create a subnet in the new availability zone and migrate the node group:

    CLI
    Terraform
    1. Create a subnet:

      yc vpc subnet create \
         --name <subnet_name> \
         --zone <availability_zone> \
         --network-id <network_ID> \
         --range <subnet_CIDR>
      

      Where:

      • --name: Subnet name.
      • --zone: Availability zone, ru-central1-a, ru-central1-b, or ru-central1-d.
      • --network-id: ID of the network that contains the new subnet.
      • --range: List of IPv4 addresses for incoming or outgoing traffic, e.g., 10.0.0.0/22 or 192.168.0.0/16. Make sure the addresses are unique within the network. The minimum subnet size is /28, while the maximum subnet size is /16. Only IPv4 is supported.
    2. Migrate the node group to the new availability zone. The example below shows a command for migrating a group placed in a single zone:

      yc managed-kubernetes node-group update \
         --id <node_group_ID> \
         --location zone=<availability_zone>,subnet-id=<subnet_ID> \
         --network-interface subnets=<subnet_ID>,`
              `ipv4-address=nat,`
              `security-group-ids=[<security_group_IDs>]
      

      Where:

      • id: ID of the node group you want to migrate to a different availability zone.
      • zone: Availability zone you want to migrate your node group to, ru-central1-a, ru-central1-b, or ru-central1-d.
      • subnet_id and subnets: ID of the new subnet you created earlier.
      • ipv4-address: IPv4 address assignment method. The nat value allows assigning public and internal IP addresses to nodes.
      • security-group-ids: List of security group IDs.

      Warning

      If you want to keep the values of other network parameters for the node group, specify them in the network-interface parameter as well. Otherwise, the group may be recreated with default values. For more information, see Updating a Managed Service for Kubernetes node group.

      Make sure to provide the ipv4-address and security-group-ids parameters in the command: this will allow assigning public IP addresses to the node group and keeping security groups within it.

      This command recreates the nodes within their group in the specified availability zone and subnet. When recreating, the deployment settings are considered: the maximum number of nodes by which you can increase or decrease the group size against the initial number of nodes.

      How to migrate a node group placed in different availability zones

      In this case, use the following command:

      yc managed-kubernetes node-group update \
         --id <node_group_ID> \
         --location zone=<availability_zone>,subnet-id=<subnet_ID> \
         ...
         --location zone=<availability_zone>,subnet-id=<subnet_ID> \
         --network-interface subnets=[<subnet_IDs>],`
              `ipv4-address=nat,`
              `security-group-ids=[<security_group_IDs>]
      

      Where:

      • id: ID of the node group you want to migrate to a different availability zone.
      • zone: Availability zone, ru-central1-a, ru-central1-b, or ru-central1-d. Specify the location parameters for each availability zone that will host the node group.
      • subnet-id and subnets: IDs of the subnets for the specified availability zones.
      • ipv4-address: IPv4 address assignment method. The nat value allows assigning public and internal IP addresses to nodes.
      • security-group-ids: List of security group IDs.

    Alert

    To make sure your node group is not recreated (unless it is your intention to do so), analyze the output of the terraform plan and terraform apply commands before applying the configuration.

    You can migrate a node group to a different availability zone without recreating it only if the configuration file contains the allocation_policy section.

    1. Edit the configuration file as follows:

      • Add a new subnet manifest (the yandex_vpc_subnet resource) in the availability zone to which you want to migrate the node group.
      • Change the node group location parameters (the yandex_kubernetes_node_group resource):
        • allocation_policy.location.subnet_id: Remove this parameter from the manifest.
        • allocation_policy.location.zone: Specify the availability zone you want to migrate the node group to.
        • instance_template.network_interface.subnet_ids: Specify the new subnet ID. Add this parameter to the manifest if missing.
      resource "yandex_vpc_subnet" "my-new-subnet" {
         name           = "<subnet_name>"
         zone           = "<availability_zone>"
         network_id     = "<network_ID>"
         v4_cidr_blocks = ["<subnet_CIDR>"]
      }
      ...
      resource "yandex_kubernetes_node_group" "k8s-node-group" {
         allocation_policy {
            location {
               zone = "<availability_zone>"
            }
         }
         ...
         instance_template {
            network_interface {
               subnet_ids = [yandex_vpc_subnet.my-new-subnet.id]
               ...
            }
            ...
         }
         ...
      }
      

      Where:

      • name: Subnet name.
      • zone: Availability zone you want to migrate your node group to, ru-central1-a, ru-central1-b, or ru-central1-d.
      • network_id: ID of the network that contains the new subnet.
      • v4_cidr_blocks: List of IPv4 addresses for incoming or outgoing traffic, e.g., 10.0.0.0/22 or 192.168.0.0/16. Make sure the addresses are unique within the network. The minimum subnet size is /28, while the maximum subnet size is /16. Only IPv4 is supported.
      • subnet_ids: New subnet ID.
    2. Make sure the configuration file is correct.

      1. In the command line, navigate to the directory that contains the current Terraform configuration files defining the infrastructure.

      2. Run this command:

        terraform validate
        

        Terraform will show any errors found in your configuration files.

    3. Confirm updating the resources.

      1. Run this command to view the intended changes:

        terraform plan
        

        If you described the configuration correctly, the terminal will display a list of the resources to update and their parameters. This is a verification step that does not apply changes to your resources.

      2. If everything looks correct, apply the changes:

        1. Run this command:

          terraform apply
          
        2. Confirm updating the resources.

        3. Wait for the operation to complete.

    The group nodes will be recreated in the specified availability zone and subnet. When recreating, the deployment settings are considered: the maximum number of nodes by which you can increase or decrease the group size against the initial number of nodes.

  12. Restore the original number of pods managed by the StatefulSet controller:

    kubectl scale statefulset <controller_name> --replicas=<number_of_pods>
    

    This will start the pods in the migrated node group.

    In the command, specify the following parameters:

    • Name of the StatefulSet controller. You can get it by running the kubectl get statefulsets command.
    • Number of pods prior to scaling down the controller.
  13. Make sure the pods are running in the migrated node group:

    kubectl get po --output wide
    

    The output of this command shows the nodes on which your pods are currently running.

  14. Delete the unused PersistentVolume object, i.e., the one with the Released status.

    1. Get the name of the PersistentVolume object:

      kubectl get pv
      
    2. Delete the PersistentVolume object:

      kubectl delete pv <PV_name>
      

Gradually migrating stateless and stateful workloadsGradually migrating stateless and stateful workloads

See below how to gradually migrate workloads from the old node group to the new one. For the PersistentVolume and PersistentVolumeClaim migration steps, see Migrating stateful workloads.

  1. Create a new Managed Service for Kubernetes node group in the new availability zone.

  2. Disable running new pods in the old node group:

    kubectl cordon -l yandex.cloud/node-group-id=<old_node_group_ID>
    
  3. For each node in the old node group, run the following command:

    kubectl drain <node_name> --ignore-daemonsets --delete-emptydir-data
    

    The pods will gradually move to the new node group.

  4. Make sure the pods are running in the new node group:

    kubectl get po --output wide
    
  5. Delete the old node group.

Was the article helpful?

Previous
Setting up time-slicing GPUs
Next
Encrypting secrets
© 2026 Direct Cursus Technology L.L.C.