Create and start a VM instance

This page gives instructions for creating a virtual machine (VM) instance using a boot disk image or a boot disk snapshot.

You can create a VM with one or more disks. You can also add disks to your VM after creation. Google Distributed Cloud (GDC) air-gapped automatically starts the VM instance after creation.

You can add startup scripts to a VM, either before or after creation. To read more about startup scripts, see the Use a startup script with a VM instance page.

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 use the gdcloud or kubectl CLI, and require an operating system (OS) environment.

Get the kubeconfig file path

To run commands against the org admin cluster, ensure you have the following resources:

  1. Locate the org admin cluster name, or ask your Platform Administrator (PA) what the cluster name is.

  2. Sign in and generate the kubeconfig file for the org admin cluster if you don't have one.

  3. Use the path to the kubeconfig file of the org admin cluster to replace ORG_ADMIN_KUBECONFIG in these instructions.

Request permissions and access

To perform the tasks listed in this page, you must have the Project VirtualMachine Admin role. Follow the steps to verify that you have the Project VirtualMachine Admin (project-vm-admin) role in the namespace of the project where the VM resides.

For VM operations using the GDC console or the gdcloud CLI, request your Project IAM Admin to assign you both the Project VirtualMachine Admin role and the Project Viewer (project-viewer) role.

Create a VM instance from an image

This section shows how to create a VM from either a GDC-provided OS image or from a custom OS image.

View a list of available GDC-provided images

Before you create a VM using a GDC-provided image, review the list of available images.

gdcloud

  • List all available images and their minimum disk size:

    gdcloud compute images list

    This command includes both GDC-provided and custom images. Choose either image in the vm-system namespace.

API

  1. List all available GDC-provided images:

    kubectl --kubeconfig ORG_ADMIN_KUBECONFIG \
get virtualmachineimage.virtualmachine.gdc.goog --namespace vm-system

  2. Get the minimumDiskSize for a particular GDC-provided image:

    kubectl --kubeconfig ORG_ADMIN_KUBECONFIG \
    get virtualmachineimage.virtualmachine.gdc.goog --namespace vm-system \
    BOOT_DISK_IMAGE_NAME -ojsonpath='{.spec.minimumDiskSize}{"\n"}'

    Replace the following:

    • ORG_ADMIN_KUBECONFIG: the kubeconfig for the org admin cluster.
    • BOOT_DISK_IMAGE_NAME: the name of the image.

Create a VM instance from a GDC-provided image

By default, all GDC projects can create VMs from GDC-provided OS images.

gdcloud

  1. Select a GDC-provided image to create the VM instance:

    gdcloud compute instances create VM_NAME \
    --machine-type=MACHINE_TYPE \
    --image=BOOT_DISK_IMAGE_NAME --image-project=vm-system \
    --boot-disk-size=BOOT_DISK_SIZE \
    --no-boot-disk-auto-delete=NO_BOOT_DISK_AUTO_DELETE

    Replace the following:

    VariableDefinition
    VM_NAME The name of the new VM. The name must only contain alphanumeric characters and dashes, and be no longer than 53 characters.
    BOOT_DISK_IMAGE_NAME The name of the image to use for the new VM boot disk.
    BOOT_DISK_SIZE The size of the boot disk, such as 20G.
    This value must always be greater than or equal to the minimumDiskSize of the boot disk image.
    NO_BOOT_DISK_AUTO_DELETE Either true or false, indicating the inverse of whether the boot disk is automatically deleted when the VM instance gets deleted.
    MACHINE_TYPE The predefined machine type for the new VM. To select an available machine type, run the following:
    gdcloud compute machine-types list

API

  1. Select a GDC-provided image to create the VM instance:

    kubectl --kubeconfig ORG_ADMIN_KUBECONFIG \
    apply -n PROJECT -f - <<EOF
apiVersion: virtualmachine.gdc.goog/v1
kind: VirtualMachineDisk
metadata:
  name: VM_BOOT_DISK_NAME
spec:
  source:
    image:
      name: BOOT_DISK_IMAGE_NAME
      namespace: vm-system
  size: BOOT_DISK_SIZE
---
apiVersion: virtualmachine.gdc.goog/v1
kind: VirtualMachine
metadata:
  name: VM_NAME
spec:
  compute:
    virtualMachineType: MACHINE_TYPE
  disks:
    - virtualMachineDiskRef:
        name: VM_BOOT_DISK_NAME
      boot: true
      autoDelete: BOOT_DISK_AUTO_DELETE
EOF

    Replace the following:

    VariableDefinition
    ORG_ADMIN_KUBECONFIG The org admin cluster kubeconfig path.
    PROJECT The GDC project to create the VM.
    VM_NAME The name of the new VM. The name must only contain alphanumeric characters and dashes, and be no longer than 53 characters.
    VM_BOOT_DISK_NAME The name of the new VM boot disk.
    BOOT_DISK_IMAGE_NAME The name of the image to use for the new VM boot disk.
    BOOT_DISK_SIZE The size of the boot disk, such as 20G.
    This value must always be greater than or equal to the minimumDiskSize of the boot disk image.
    BOOT_DISK_AUTO_DELETE Either true or false, indicating whether the boot disk is automatically deleted when the VM instance gets deleted.
    MACHINE_TYPE The predefined machine type for the new VM. To select an available machine type, run the following:
    gdcloud compute machine-types list

  2. Verify that the VM is created and wait for the VM to show the Running state. The Running state does not indicate that the OS is fully ready and accessible.

    kubectl --kubeconfig ORG_ADMIN_KUBECONFIG \
get virtualmachine.virtualmachine.gdc.goog VM_NAME -n PROJECT

    Replace VM_NAME and PROJECT with the name and project of the VM.

    To add a startup script to your VM instance creation, follow the steps provided on the Use a startup script with a VM instance page. Ensure you shut down the VM before you add the script.

Create a VM instance from a custom image

A custom image belongs exclusively to your project. To create a VM with a custom image, you must first create a custom image in the same project.

gdcloud

  1. List all custom images:

    gdcloud compute images list --no-standard-images=true

  2. Create the VM instance:

    gdcloud compute instances create VM_NAME \
    --machine-type=MACHINE_TYPE \
    --image=BOOT_DISK_IMAGE_NAME \
    --boot-disk-size=BOOT_DISK_SIZE \
    --no-boot-disk-auto-delete=NO_BOOT_DISK_AUTO_DELETE

    Replace the following:

    VariableDefinition
    VM_NAME The name of the new VM. The name must only contain alphanumeric characters and dashes, and be no longer than 53 characters.
    BOOT_DISK_IMAGE_NAME The name of the image to use for the new VM boot disk.
    BOOT_DISK_SIZE The size of the boot disk, such as 20G.
    This value must always be greater than or equal to the minimumDiskSize of the boot disk image.
    NO_BOOT_DISK_AUTO_DELETE Either true or false, indicating the inverse of whether the boot disk is automatically deleted when the VM instance gets deleted.
    MACHINE_TYPE The predefined machine type for the new VM. To select an available machine type, run the following:
    gdcloud compute machine-types list

API

  1. List all custom images:

    kubectl --kubeconfig ORG_ADMIN_KUBECONFIG \
    get virtualmachineimage.virtualmachine.gdc.goog --namespace PROJECT

    Get the minimumDiskSize of a particular image to create a VM instance:

    kubectl --kubeconfig ORG_ADMIN_KUBECONFIG \
    get virtualmachineimage.virtualmachine.gdc.goog --namespace PROJECT \
    BOOT_DISK_IMAGE_NAME -ojsonpath='{.spec.minimumDiskSize}{"\n"}'

    Replace the following:

    VariableDefinition
    ORG_ADMIN_KUBECONFIG The org admin cluster kubeconfig path.
    BOOT_DISK_IMAGE_NAME The name of the image chosen from the command to list all custom images.
    PROJECT The project of the image.

  2. Create the VM instance:

    kubectl --kubeconfig ORG_ADMIN_KUBECONFIG \
    apply -n PROJECT -f - <<EOF
apiVersion: virtualmachine.gdc.goog/v1
kind: VirtualMachineDisk
metadata:
  name: VM_BOOT_DISK_NAME
spec:
  source:
    image:
      name: BOOT_DISK_IMAGE_NAME
  size: BOOT_DISK_SIZE
---
apiVersion: virtualmachine.gdc.goog/v1
kind: VirtualMachine
metadata:
  name: VM_NAME
spec:
  compute:
    virtualMachineType: MACHINE_TYPE
  disks:
    - virtualMachineDiskRef:
        name: VM_BOOT_DISK_NAME
      boot: true
      autoDelete: BOOT_DISK_AUTO_DELETE
EOF

    Replace the following:

    VariableDefinition
    ORG_ADMIN_KUBECONFIG The org admin cluster kubeconfig path.
    PROJECT The GDC project to create the VM.
    VM_NAME The name of the new VM. The name must only contain alphanumeric characters and dashes, and be no longer than 53 characters.
    VM_BOOT_DISK_NAME The name of the new VM boot disk.
    BOOT_DISK_IMAGE_NAME The name of the image to use for the new VM boot disk.
    BOOT_DISK_SIZE The size of the boot disk, such as 20G.
    This value must always be greater than or equal to the minimumDiskSize of the boot disk image.
    BOOT_DISK_AUTO_DELETE Either true or false, indicating whether the boot disk is automatically deleted when the VM instance gets deleted.
    MACHINE_TYPE The predefined machine type for the new VM. To select an available machine type, run the following:
    kubectl --kubeconfig ORG_ADMIN_KUBECONFIG get virtualmachinetype.virtualmachine.gdc.goog --namespace vm-system

  3. Verify that the VM is created and wait for the VM to show that it's in the Running state. Being in the Running state doesn't mean that the OS is fully ready and accessible.

    kubectl --kubeconfig ORG_ADMIN_KUBECONFIG \
get virtualmachine.virtualmachine.gdc.goog VM_NAME -n PROJECT

    Replace VM_NAME and PROJECT with the name and project of the VM.

Create a VM instance with additional non-boot disks

You can create non-boot disks when you create a VM. Each additional disk can either specify an image source or not. The latter case is for creating a blank disk.

gdcloud

  1. Create a disk from an image:

    gdcloud compute disks create NON_BOOT_DISK_FROM_IMAGE \
    --size=NON_BOOT_DISK_SIZE \
    --image=NON_BOOT_DISK_IMAGE_NAME \
    --image-project=NON_BOOT_DISK_IMAGE_NAMESPACE

  2. Create a disk from a blank image:

    gdcloud compute disks create NON_BOOT_BLANK_DISK \
    --size=NON_BOOT_BLANK_DISK_SIZE \

  3. Create an instance with the disks from the previous step:

    gdcloud compute instances create VM_NAME \
    --machine-type=MACHINE_TYPE \
    --image=BOOT_DISK_IMAGE_NAME --image-project=vm-system \
    --boot-disk-size=BOOT_DISK_SIZE \
    --no-boot-disk-auto-delete=NO_BOOT_DISK_AUTO_DELETE \
    --disk=name=NON_BOOT_DISK_FROM_IMAGE \
    --disk=name=NON_BOOT_BLANK_DISK

    Replace the following:

    VariableDefinition
    VM_NAME The name of the new VM. The name must only contain alphanumeric characters and dashes, and be no longer than 53 characters.
    BOOT_DISK_IMAGE_NAME The name of the image to use for the new VM boot disk.
    BOOT_DISK_IMAGE_NAMESPACE The namespace of the image to use for the new VM boot disk. Use `vm-system` for a GDC-provided image, or leave the field blank for a custom image.
    BOOT_DISK_SIZE The size of the boot disk, such as 20G.
    This value must always be greater than or equal to the minimumDiskSize of the boot disk image.
    NO_BOOT_DISK_AUTO_DELETE Either true or false, indicating the inverse of whether the boot disk is automatically deleted when the VM instance gets deleted.
    MACHINE_TYPE The predefined machine type for the new VM. To select an available machine type, run the following:
    gdcloud compute machine-types list

    For additional disks, replace the following:

    • NON_BOOT_DISK_FROM_IMAGE, NON_BOOT_BLANK_DISK: the name of the additional disk.
    • NON_BOOT_DISK_SIZE, NON_BOOT_BLANK_DISK_SIZE: the size of the additional disks, for example, 20G.
    • NON_BOOT_DISK_IMAGE_NAME: the name of the image to use as a non-boot disk.
    • NON_BOOT_DISK_IMAGE_NAMESPACE: the namespace of the image to use as a non-boot disk. Use vm-system for a GDC-provided image, or leave the field blank for a custom image.

API

  1. Create a VM with a non-boot disk:

    kubectl --kubeconfig ORG_ADMIN_KUBECONFIG \
    apply -n PROJECT -f - <<EOF
apiVersion: virtualmachine.gdc.goog/v1
kind: VirtualMachineDisk
metadata:
  name: NON_BOOT_DISK_FROM_IMAGE
spec:
  source:
    image:
      name: NON_BOOT_DISK_IMAGE_NAME
      namespace: NON_BOOT_DISK_IMAGE_NAMESPACE
  size: NON_BOOT_DISK_SIZE
---
apiVersion: virtualmachine.gdc.goog/v1
kind: VirtualMachineDisk
metadata:
  name: NON_BOOT_BLANK_DISK
spec:
  size: NON_BOOT_BLANK_DISK_SIZE
---
apiVersion: virtualmachine.gdc.goog/v1
kind: VirtualMachineDisk
metadata:
  name: VM_BOOT_DISK_NAME
spec:
  source:
    image:
      name: BOOT_DISK_IMAGE_NAME
      namespace: BOOT_DISK_IMAGE_NAMESPACE
  size: BOOT_DISK_SIZE
---
apiVersion: virtualmachine.gdc.goog/v1
kind: VirtualMachine
metadata:
  name: VM_NAME
spec:
  compute:
    virtualMachineType: MACHINE_TYPE
  disks:
    - virtualMachineDiskRef:
        name: VM_BOOT_DISK_NAME
      boot: true
      autoDelete: BOOT_DISK_AUTO_DELETE
    - virtualMachineDiskRef:
        name: NON_BOOT_DISK_FROM_IMAGE
    - virtualMachineDiskRef:
        name: NON_BOOT_BLANK_DISK
EOF

    Replace the following:

    VariableDefinition
    ORG_ADMIN_KUBECONFIG The org admin cluster kubeconfig path.
    PROJECT The GDC project to create in the VM.
    VM_NAME The name of the new VM. The name must only contain alphanumeric characters and dashes, and be no longer than 53 characters.
    VM_BOOT_DISK_NAME The name of the new VM boot disk.
    BOOT_DISK_IMAGE_NAME The name of the image to use for the new VM boot disk.
    BOOT_DISK_IMAGE_NAMESPACE The namespace of the image to use for the new VM boot disk. Use the namespace vm-system for a GDC-provided image, or blank for a custom image.
    BOOT_DISK_SIZE The size of the boot disk, such as 20G.
    This value must always be greater than or equal to the minimumDiskSize of the boot disk image.
    BOOT_DISK_AUTO_DELETE Either true or false, indicating whether the boot disk is automatically deleted when the VM instance gets deleted.
    MACHINE_TYPE The predefined machine type for the new VM. To select an available machine type, run the following:
    kubectl --kubeconfig ORG_ADMIN_KUBECONFIG get virtualmachinetype.virtualmachine.gdc.goog --namespace vm-system

    For additional disks, replace the following:

    • NON_BOOT_DISK_FROM_IMAGE, NON_BOOT_BLANK_DISK: the name of the additional disk.
    • NON_BOOT_DISK_SIZE, NON_BOOT_BLANK_DISK_SIZE: the size of the additional disks, for example, 20G.
    • NON_BOOT_DISK_IMAGE_NAME: the name of the image that you want to use as a non-boot disk.
    • NON_BOOT_DISK_IMAGE_NAMESPACE: the namespace of the image that you want to use as a non-boot disk. Use the namespace vm-system for a GDC-provided image, or blank for a custom image.

    Format and mount the disks before using them.

Create a VM from a snapshot or backup

You can create a new VM from a snapshot in the following ways:

  • Restore a VM boot disk: If you backed up a boot disk of a VM with a snapshot, use that snapshot to create a new VM. See Restore a snapshot.
    • Restore a non-boot disk: If you backed up a non-boot disk with a snapshot, you can also restore the snapshot to a new non-boot disk when you create a VM, using the same instructions.

To create more than one VM with the same boot disk, do the following:

  1. Create a custom image.
  2. Create VMs from that image without using a snapshot.

Create a VM without using machine type

Distributed Cloud offers predefined machine types that you can use when you create a VM instance. A predefined machine type has a preset number of vCPUs and amount of memory.

If predefined VMs don't meet your needs, create a VM instance with custom virtualized hardware settings.

Custom VMs are ideal in the following scenarios:

  • Workloads that aren't applicable for the predefined VM types.

  • Workloads that require more processing power or more memory but don't need all the upgrades the next-level machine type provides.

gdcloud

  1. Create a VM with a machine type that you define:

    gdcloud compute instances create VM_NAME \
    --custom-cpu=NUM_VCPU \
    --custom-memory=MEMORY
    --image=BOOT_DISK_IMAGE_NAME --image-project=vm-system \
    --boot-disk-size=BOOT_DISK_SIZE \
    --no-boot-disk-auto-delete=NO_BOOT_DISK_AUTO_DELETE

    Replace the following:

    VariableDefinition
    VM_NAME The name of the new VM. The name must only contain alphanumeric characters and dashes, and be no longer than 53 characters.
    BOOT_DISK_IMAGE_NAME The name of the image to use for the new VM boot disk.
    BOOT_DISK_SIZE The size of the boot disk, such as 20G.
    This value must always be greater than or equal to the minimumDiskSize of the boot disk image.
    NO_BOOT_DISK_AUTO_DELETE Either true or false, indicating the inverse of whether the boot disk is automatically deleted when the VM instance gets deleted.
    NUM_VCPU The number of vCPUs. The maximum number of vCPUs supported is 192.
    MEMORY The size of memory, such as 8G. The maximum memory size is one terabyte (TB).

API

  1. Create a VM with a machine type that you define:

    kubectl --kubeconfig ORG_ADMIN_KUBECONFIG \
    apply -n PROJECT -f - <<EOF
apiVersion: virtualmachine.gdc.goog/v1
kind: VirtualMachineDisk
metadata:
  name: VM_BOOT_DISK_NAME
spec:
  source:
    image:
      name: BOOT_DISK_IMAGE_NAME
      namespace: vm-system
  size: BOOT_DISK_SIZE
---
apiVersion: virtualmachine.gdc.goog/v1
kind: VirtualMachine
metadata:
  name: VM_NAME
spec:
  compute:
    vcpus: NUM_VCPU
    memory: MEMORY
  disks:
    - virtualMachineDiskRef:
        name: VM_BOOT_DISK_NAME
      boot: true
      autoDelete: BOOT_DISK_AUTO_DELETE
EOF

    Replace the following:

    VariableDefinition
    ORG_ADMIN_KUBECONFIG The org admin cluster kubeconfig path.
    PROJECT The Distributed Cloud project to create the VM.
    VM_NAME The name of the new VM. The name must only contain alphanumeric characters and dashes, and be no longer than 53 characters.
    VM_BOOT_DISK_NAME The name of the new VM boot disk.
    BOOT_DISK_IMAGE_NAME The name of the image to use for the new VM boot disk.
    BOOT_DISK_SIZE The size of the boot disk, such as 20G.
    This value must always be greater than or equal to the minimumDiskSize of the boot disk image.
    BOOT_DISK_AUTO_DELETE Either true or false, indicating whether the boot disk is automatically deleted when the VM instance gets deleted.
    NUM_VCPU The number of vCPUs. The maximum number of vCPUs supported is 192.
    MEMORY The size of memory, such as 8G. The maximum memory size is one TB.