Replace a boot disk

This document contains instructions to replace a boot disk. If you need to create a boot disk before your replacement, see the Create a boot disk page.

You can detach boot disks from your virtual machine (VM) instance and attach new boot disks to it. To repair boot disks, you mount them to another VM instance without deleting the original one. Also, instead of recreating an entire VM instance, you can replace its boot disks.

Before you begin

To use gdcloud command-line interface (CLI) commands, ensure that you have downloaded, installed, and configured the gdcloud CLI. All commands for Distributed Cloud Hosted use the gdcloud or kubectl CLI, and require an operating system (OS) environment.

Get the kubeconfig file paths

  1. Run gdcloud auth login to the admin cluster.
    1. Record the path to the generated file, as in this example:

    2. Use the path to replace ORG_ADMIN_KUBECONFIG in these instructions.

  • Obtain access to VM disks. Follow the steps to verify or assign the Project VM Admin role.


You have the following restrictions when replacing a boot disk:

  • Attach or detach a boot disk only from a stopped VM instance.
  • Attach only one boot disk for each VM instance.
  • Attach only existing boot disks to a VM instance.
  • Replace the boot disk only with a new bootable disk.

Replace a boot disk

Replace a boot disk by using the GDCH console or the kubectl CLI.


  1. In the navigation menu, click Virtual Machines > Instances.

  2. In the list of VMs, click a VM name to view its details.

  3. Click Replace boot disk.

  4. In the confirmation dialog, click Stop to stop the VM.

  5. Wait a few minutes for the VM to stop.

  6. Click Refresh.

  7. When the VM is in a stopped state, click Replace boot disk again.

  8. In the Replace boot disk dialog, choose a new boot disk or an existing boot disk.

    • To provision a new boot disk, click the New boot disk tab.

      1. In the Disk name field, enter a new disk name that is unique to the project.
      2. In the Size field, enter a disk size between 12 and 65536 GiB.
      3. In the Image name list, select an image.
      4. In the Deletion rule section, click Keep disk or Delete disk.
      5. In the Storage profile section, choose a profile. The default profile is Standard.
    • To choose an existing boot disk, click the Existing boot disk tab.

      1. In the Disk list, select a disk.
      2. In the Deletion rule section, click Keep disk or Delete disk.
  9. Click Save.

  10. Restart the VM.


  1. Stop the VM instance.

  2. Open the current spec.disks value to change it for the new virtual machine disk:

    kubectl --kubeconfig ORG_ADMIN_KUBECONFIG edit --namespace PROJECT VM_NAME

    Replace the following values:

    • ORG_ADMIN_KUBECONFIG with the path to the kubeconfig file of the org admin cluster.
    • PROJECT with the GDCH project where you want to replace the boot disk.
    • VM_NAME with the name of the virtual machine.
  3. Modify the boot disk in the config file by replacing VM_BOOT_DISK_NAME with the new VM boot disk name:

    - virtualMachineDiskRef:
        name: VM_BOOT_DISK_NAME
      boot: true

    The result must look like the following example:

    - virtualMachineDiskRef: 
        name: NEW_VM_BOOT_DISK_NAME
      boot: true
  4. Restart the VM.