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:bmctl enable vmruntime --kubeconfig KUBECONFIG_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:kubectl edit vmruntime
Set
enabled:true
in the spec:apiVersion: vm.cluster.gke.io/v1 kind: VMRuntime metadata: name: vmruntime spec: 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 GDCuseEmulation
: 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. TheuseEmulation
field defaults tofalse
, if it isn't specified.vmImageFormat
: Supports two disk image format values:raw
andqcow2
. If you don't setvmImageFormat
, the VM Runtime on GDC uses theraw
disk image format to create VMs. Theraw
format may provide improved performance overqcow2
, 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:kubectl describe vmruntime vmruntime
The details of the
VMRuntime
custom resource include aStatus
section. VM Runtime on GDC is enabled and working whenVMRuntime.Status.Ready
shows astrue
.
Install the virtctl
client tool
To create and manage VMs, install the virtctl client tool.
Install the
virtctl
client tool as akubectl
plugin:export GOOGLE_APPLICATION_CREDENTIALS="PATH_TO_SERVICE_ACCOUNT_KEY/bm-gcr.json" sudo -E bmctl install virtctl
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:kubectl plugin list
If
kubectl-virt
is listed in the response, the plugin is successfully installed.If
kubectl-virt
is not listed, check theinstall-virtctl.log
file as noted in the output of the previousbmctl install
command, such asbmctl-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 thekubectl
command:kubectl virt create vm VM_NAME \ --image ubuntu20.04 \ --configure-initial-password USERNAME:PASSWORD
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 thevirtctl
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:kubectl get gvm
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
:kubectl virt console VM_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
:kubectl virt delete vm VM_NAME --all
What's next
- Manage the power state of a VM in Google Distributed Cloud.
- Edit a VM in Google Distributed Cloud.
- View VM console logs in Google Distributed Cloud.