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 Management API server, ensure you have the following resources:

  1. Sign in and generate the kubeconfig file for the Management API server if you don't have one.

  2. Use the path to the kubeconfig file of the Management API server to replace MANAGEMENT_API_SERVER 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. See supported VM images for more information about GDC-provided 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 MANAGEMENT_API_SERVER \
  -n vm-system \
  get virtualmachineimage.virtualmachine.gdc.goog

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

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

    Replace the following:

    • MANAGEMENT_API_SERVER: the kubeconfig file for the Management API server.
    • 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 20GB.
    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 MANAGEMENT_API_SERVER \
  -n PROJECT \
  apply -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
    MANAGEMENT_API_SERVER The Management API server kubeconfig file.
    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 20Gi.
    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 MANAGEMENT_API_SERVER \
  -n PROJECT \
  get virtualmachine.virtualmachine.gdc.goog VM_NAME

    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 20GB.
    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 MANAGEMENT_API_SERVER \
  -n PROJECT \
  get virtualmachineimage.virtualmachine.gdc.goog

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

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

    Replace the following:

    VariableDefinition
    MANAGEMENT_API_SERVER The Management API server kubeconfig file.
    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 MANAGEMENT_API_SERVER \
  -n PROJECT \
  apply -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
    MANAGEMENT_API_SERVER The Management API server kubeconfig file.
    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 20Gi.
    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 MANAGEMENT_API_SERVER 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 MANAGEMENT_API_SERVER \
  -n PROJECT \
  get virtualmachine.virtualmachine.gdc.goog VM_NAME

    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 20GB.
    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, 20GB.
    • 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 MANAGEMENT_API_SERVER \
  -n PROJECT \
  apply -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
    MANAGEMENT_API_SERVER The Management API server kubeconfig file.
    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 20Gi.
    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 MANAGEMENT_API_SERVER 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, 20Gi.
    • 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 20GB.
    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 MANAGEMENT_API_SERVER \
  -n PROJECT \
  apply -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
    MANAGEMENT_API_SERVER The Management API server kubeconfig file.
    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 20Gi.
    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.

Create a VM instance with a specified IP address and subnet

By default, you can create a Distributed Cloud VM without the network specification. This type of VM attaches to the default Virtual Private Cloud (VPC) and dynamically assigns an IP from the default subnet. To create a VM with the default configurations, see Create a VM with a GDC-provided image.

If you don't want to use the default IP configuration for your Distributed Cloud VM, you can create a VM with a dynamic or static IP address:

  • Dynamic IP from a custom subnet: you create a subnet with a specific CIDR, and create a VM with an IP dynamically assigned from that CIDR.

  • Static IP from a custom subnet: you create a subnet with a specific CIDR, and create a VM with a static IP from that CIDR.

This section shows you how to create a VM with either a dynamically assigned address or with a static IP address.

Create a VM with a dynamically-assigned IP from a custom subnet

Create a VM with a dynamically-assigned IP from a specific CIDR:

   kubectl --kubeconfig MANAGEMENT_API_SERVER \
     -n PROJECT \
     apply -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
     network:
       interfaces:
       - subnet: SUBNET_NAME
   EOF

Replace the following variables:

VariableDefinition
MANAGEMENT_API_SERVER The Management API server kubeconfig file.
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, with a maximum of 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 20Gi.
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. Select an available machine type:
kubectl --kubeconfig MANAGEMENT_API_SERVER get virtualmachinetype.virtualmachine.gdc.goog --namespace vm-system
SUBNET_NAME The name of the custom subnet.

Create a VM with a static IP from a subnet

Create a VM with a static IP from a custom subnet:

   kubectl --kubeconfig MANAGEMENT_API_SERVER \
     -n PROJECT \
     apply  -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
     network:
       interfaces:
       - subnet: SUBNET_NAME
         ipAddresses:
         - address: IP_ADDRESS
   EOF

Replace the following variables:

VariableDefinition
MANAGEMENT_API_SERVER The Management API server kubeconfig file.
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 20Gi.
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 MANAGEMENT_API_SERVER get virtualmachinetype.virtualmachine.gdc.goog --namespace vm-system
SUBNET_NAME The name of the custom subnet.
IP_ADDRESS The IP address. This must be within the chosen subnet range. You can only specify one IP address in the ipAddresses field