Quickstart: Create a VM in Google Distributed Cloud clusters
Stay organized with collections
Save and categorize content based on your preferences.
This quickstart shows you how to use VM Runtime on GDC to create a
virtual machine (VM) on Google Distributed Cloud. VM Runtime on GDC uses
KubeVirt
to orchestrate VMs on clusters, and lets you work with your VM-based apps and
workloads in a uniform development environment.
Before you begin
To complete this quickstart, you need access to Google Distributed Cloud version
1.12 (anthosBareMetalVersion: 1.12) or higher cluster. You can use any
cluster type capable of running workloads. If needed,
try Google Distributed Cloud on Compute Engine
or see the
cluster creation overview.
Enable VM Runtime on GDC
VM Runtime on GDC is automatically installed in Google Distributed Cloud
version 1.10 or higher, but is disabled by default. Before you can run VM
resources in your Google Distributed Cloud, you must enable the
VM Runtime on GDC.
bmctl
Google Distributed Cloud version 1.11 or higher can use the bmctl command-line tool:
To enable the runtime, use the bmctl tool:
bmctlenablevmruntime--kubeconfigKUBECONFIG_PATH
Provide the path to the kubeconfig file for your cluster.
Google Distributed Cloud generates the kubeconfig file on the admin
workstation when you create a cluster. By default, the path is
bmctl-workspace/CLUSTER_NAME/CLUSTER_NAME-kubeconfig.
If VM Runtime on GDC is already enabled, the command returns an
error.
Custom resource
Google Distributed Cloud version 1.10 or higher can use a custom resource definition
to enable VM Runtime on GDC. This custom resource is installed by
default.
Edit the VMRuntime custom resource:
kubectleditvmruntime
Set enabled:true in the spec:
apiVersion:vm.cluster.gke.io/v1kind:VMRuntimemetadata:name:vmruntimespec:enabled:true# useEmulation defaults to "false" if not set.useEmulation:true# vmImageFormat defaults to "qcow2" if not set.vmImageFormat:qcow2
In the preceding spec section, the following values can be set:
enabled: set to true to enable VM Runtime on GDC
useEmulation: If your node doesn't support hardware virtualization, or
you aren't sure, set the value to true. If available, hardware
virtualization provides better performance than software emulation. The
useEmulation field defaults to false, if it isn't specified.
vmImageFormat: Supports two disk image format values: raw and
qcow2. If you don't set vmImageFormat, the
VM Runtime on GDC uses the raw disk image format to create
VMs. The raw format may provide improved performance over qcow2, a
copy on write format, but may use more disk. For more information about
the image formats for your VM, see
Disk image file formats
in the QEMU documentation.
Save the custom resource in your editor.
Verify that the VMRuntime custom resource is enabled:
kubectldescribevmruntimevmruntime
The details of the VMRuntime custom resource include a Status section.
VM Runtime on GDC is enabled and working when
VMRuntime.Status.Ready shows as true.
The credentials let you authenticate and download the virtctl client tool,
then install to /usr/bin/kubectl-virt on your local machine.
Verify that the virtctl plugin is installed:
kubectlpluginlist
If kubectl-virt is listed in the response, the plugin is successfully
installed.
If kubectl-virt is not listed, check the install-virtctl.log file as noted
in the output of the previous bmctl install command, such as
bmctl-workspace/log/install-virtctl-[date]/install-virtctl.log.
Create a VM
In this quickstart, you use the kubectl CLI to create a VM that uses a public
VM image and default credentials.
Create a VM in your cluster. The virtctl plugin is used with the
kubectl command:
This command creates an Ubuntu 20.04 VM and defaults of 2 CPU, 4Gi
memory, and a 20Gi boot disk in ReadWriteOnce mode using the
local-shared storage class. Replace the following values:
VM_NAME: name for your VM. VM names
must contain only lowercase alphanumeric characters or '-', start and end
with an alphanumeric character, and contain at most 63 characters. For
more information, see
RFC 1123 Label Names
in the Kubernetes documentation.
USERNAME: user name for the account to create on the
VM.
PASSWORD: password for the user account.
If you receive an error about CLI parameters, verify that your cluster is at
version 1.11.1 or higher and that you have the latest version of the
virtctl client tool. For more information about CLI errors, consult the
console log. For username and password rules, see the documentation for the
guest operating system (OS). If something isn't working as expected, check for
VM Runtime on GDC known issues.
It can take a few minutes to create the VM. Check the status of the VM with
the kubectl command:
kubectlgetgvm
The following example output shows the VM in a Running state:
NAME STATUS AGE IP
vm-sample1 Running 64s 192.168.2.124
Connect to your VM
When your VM is running, connect to the console of the VM.
To access a VM from the console, use kubectl:
kubectlvirtconsoleVM_NAME
When prompted, enter the user credentials you specified to create the VM.
After you have successfully connected to the console of the VM, exit the VM
session and console:
Ctrl+]
Clean up
To clean up the resources created in this quickstart, follow these steps.
To delete the VM and associated DataVolume, use kubectl:
[[["Easy to understand","easyToUnderstand","thumb-up"],["Solved my problem","solvedMyProblem","thumb-up"],["Other","otherUp","thumb-up"]],[["Hard to understand","hardToUnderstand","thumb-down"],["Incorrect information or sample code","incorrectInformationOrSampleCode","thumb-down"],["Missing the information/samples I need","missingTheInformationSamplesINeed","thumb-down"],["Other","otherDown","thumb-down"]],["Last updated 2025-08-25 UTC."],[],[],null,["# Quickstart: Create a VM in Google Distributed Cloud clusters\n\nThis quickstart shows you how to use VM Runtime on GDC to create a\nvirtual machine (VM) on Google Distributed Cloud. VM Runtime on GDC uses\n[KubeVirt](https://kubevirt.io/)\nto orchestrate VMs on clusters, and lets you work with your VM-based apps and\nworkloads in a uniform development environment.\n\nBefore you begin\n----------------\n\nTo complete this quickstart, you need access to Google Distributed Cloud version\n1.12 (`anthosBareMetalVersion: 1.12`) or higher cluster. You can use any\ncluster type capable of running workloads. If needed,\n[try Google Distributed Cloud on Compute Engine](/kubernetes-engine/distributed-cloud/bare-metal/docs/try/gce-vms)\nor see the\n[cluster creation overview](/kubernetes-engine/distributed-cloud/bare-metal/docs/installing/creating-clusters/create-clusters-overview).\n\nEnable VM Runtime on GDC\n------------------------\n\nVM Runtime on GDC is automatically installed in Google Distributed Cloud\nversion 1.10 or higher, but is disabled by default. Before you can run VM\nresources in your Google Distributed Cloud, you must enable the\nVM Runtime on GDC. \n\n### bmctl\n\nGoogle Distributed Cloud version 1.11 or higher can use the `bmctl` command-line tool:\n\n- To enable the runtime, use the `bmctl` tool:\n\n bmctl enable vmruntime --kubeconfig \u003cvar label=\"Kubeconfig path\" translate=\"no\"\u003eKUBECONFIG_PATH\u003c/var\u003e\n\n Provide the path to the kubeconfig file for your cluster.\n Google Distributed Cloud generates the kubeconfig file on the admin\n workstation when you create a cluster. By default, the path is\n `bmctl-workspace/`\u003cvar translate=\"no\"\u003eCLUSTER_NAME\u003c/var\u003e`/`\u003cvar translate=\"no\"\u003eCLUSTER_NAME\u003c/var\u003e`-kubeconfig`.\n\n If VM Runtime on GDC is already enabled, the command returns an\n error.\n\n### Custom resource\n\nGoogle Distributed Cloud version 1.10 or higher can use a custom resource definition\nto enable VM Runtime on GDC. This custom resource is installed by\ndefault.\n\n1. Edit the `VMRuntime` custom resource:\n\n kubectl edit vmruntime\n\n2. Set `enabled:true` in the spec:\n\n apiVersion: vm.cluster.gke.io/v1\n kind: VMRuntime\n metadata:\n name: vmruntime\n spec:\n enabled: true\n # useEmulation defaults to \"false\" if not set.\n useEmulation: true\n # vmImageFormat defaults to \"qcow2\" if not set.\n vmImageFormat: qcow2\n\n In the preceding `spec` section, the following values can be set:\n - `enabled`: set to true to enable VM Runtime on GDC\n - `useEmulation`: If your node doesn't support hardware virtualization, or you aren't sure, set the value to true. If available, hardware virtualization provides better performance than software emulation. The `useEmulation` field defaults to `false`, if it isn't specified.\n - `vmImageFormat`: Supports two disk image format values: `raw` and `qcow2`. If you don't set `vmImageFormat`, the VM Runtime on GDC uses the `raw` disk image format to create VMs. The `raw` format may provide improved performance over `qcow2`, a copy on write format, but may use more disk. For more information about the image formats for your VM, see [Disk image file formats](https://www.qemu.org/docs/master/system/images.html#disk-image-file-formats) in the QEMU documentation.\n3. Save the custom resource in your editor.\n\n4. Verify that the `VMRuntime` custom resource is enabled:\n\n kubectl describe vmruntime vmruntime\n\n The details of the `VMRuntime` custom resource include a `Status` section.\n VM Runtime on GDC is enabled and working when\n `VMRuntime.Status.Ready` shows as `true`.\n\nInstall the `virtctl` client tool\n---------------------------------\n\nTo create and manage VMs, install the\n[virtctl client tool](https://kubevirt.io/user-guide/operations/virtctl_client_tool/).\n\n1. Install the `virtctl` client tool as a `kubectl` plugin:\n\n export GOOGLE_APPLICATION_CREDENTIALS=\"\u003cvar label=\"name\" translate=\"no\"\u003ePATH_TO_SERVICE_ACCOUNT_KEY\u003c/var\u003e/bm-gcr.json\"\n sudo -E bmctl install virtctl\n\n The credentials let you authenticate and download the `virtctl` client tool,\n then install to `/usr/bin/kubectl-virt` on your local machine.\n2. Verify that the `virtctl` plugin is installed:\n\n kubectl plugin list\n\n If `kubectl-virt` is listed in the response, the plugin is successfully\n installed.\n\n If `kubectl-virt` is not listed, check the `install-virtctl.log` file as noted\n in the output of the previous `bmctl install` command, such as\n `bmctl-workspace/log/install-virtctl-[date]/install-virtctl.log`.\n\nCreate a VM\n-----------\n\nIn this quickstart, you use the `kubectl` CLI to create a VM that uses a public\nVM image and default credentials.\n| **Note:** For instructions on creating a VM from a `VirtualMachine` YAML manifest file, see [Tutorial: Create and manage a Linux VM in VM Runtime on GDC](/kubernetes-engine/distributed-cloud/bare-metal/docs/vm-runtime/tutorial-create-vm).\n\n1. Create a VM in your cluster. The `virtctl` plugin is used with the\n `kubectl` command:\n\n kubectl virt create vm \u003cvar label=\"name\" translate=\"no\"\u003eVM_NAME\u003c/var\u003e \\\n --image ubuntu20.04 \\\n --configure-initial-password \u003cvar label=\"username\" translate=\"no\"\u003eUSERNAME\u003c/var\u003e:\u003cvar label=\"name\" translate=\"no\"\u003ePASSWORD\u003c/var\u003e\n\n This command creates an *Ubuntu 20.04* VM and defaults of *2* CPU, *4Gi*\n memory, and a *20Gi* boot disk in *ReadWriteOnce* mode using the\n *local-shared* storage class. Replace the following values:\n - \u003cvar scope=\"VM_NAME\" translate=\"no\"\u003eVM_NAME\u003c/var\u003e: name for your VM. VM names must contain only lowercase alphanumeric characters or '-', start and end with an alphanumeric character, and contain at most 63 characters. For more information, see [RFC 1123 Label Names](https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#dns-label-names) in the Kubernetes documentation.\n - \u003cvar translate=\"no\"\u003eUSERNAME\u003c/var\u003e: user name for the account to create on the VM.\n - \u003cvar translate=\"no\"\u003ePASSWORD\u003c/var\u003e: password for the user account.\n\n If you receive an error about CLI parameters, verify that your cluster is at\n version `1.11.1` or higher and that you have the latest version of the\n `virtctl` client tool. For more information about CLI errors, consult the\n console log. For username and password rules, see the documentation for the\n guest operating system (OS). If something isn't working as expected, check for\n [VM Runtime on GDC known issues](/kubernetes-engine/distributed-cloud/bare-metal/docs/troubleshooting/known-issues).\n | **Note:** The preceding command creates a YAML file, such as `vm-sample1.yaml`, in the `~/google-virtctl` directory. You can view the content of this file to see the definition of the Kubernetes resources that were created by VM Runtime on GDC.\n2. It can take a few minutes to create the VM. Check the status of the VM with\n the `kubectl` command:\n\n kubectl get gvm\n\n The following example output shows the VM in a `Running` state: \n\n NAME STATUS AGE IP\n vm-sample1 Running 64s 192.168.2.124\n\nConnect to your VM\n------------------\n\nWhen your VM is running, connect to the console of the VM.\n\n1. To access a VM from the console, use `kubectl`:\n\n kubectl virt console \u003cvar scope=\"VM_NAME\" translate=\"no\"\u003eVM_NAME\u003c/var\u003e\n\n2. When prompted, enter the user credentials you specified to create the VM.\n\n3. After you have successfully connected to the console of the VM, exit the VM\n session and console:\n\n Ctrl + ]\n\nClean up\n--------\n\nTo clean up the resources created in this quickstart, follow these steps.\n\n1. To delete the VM and associated DataVolume, use `kubectl`:\n\n kubectl virt delete vm \u003cvar scope=\"VM_NAME\" translate=\"no\"\u003eVM_NAME\u003c/var\u003e --all\n\nWhat's next\n-----------\n\n- [Manage the power state of a VM in Google Distributed Cloud](/kubernetes-engine/distributed-cloud/bare-metal/docs/vm-runtime/manage-power-state).\n- [Edit a VM in Google Distributed Cloud](/kubernetes-engine/distributed-cloud/bare-metal/docs/vm-runtime/edit-vm).\n- [View VM console logs in Google Distributed Cloud](/kubernetes-engine/distributed-cloud/bare-metal/docs/vm-runtime/view-console-logs)."]]