Quickstart: Create a VM in Anthos clusters on bare metal

This quickstart shows you how to use Anthos VM Runtime to create a virtual machine (VM) on Anthos clusters on bare metal. Anthos VM Runtime 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 Anthos clusters on bare metal version 1.12 (anthosBareMetalVersion: 1.12) or higher cluster. You can use any cluster type capable of running workloads. If needed, try Anthos clusters on bare metal on Compute Engine or see the cluster creation overview.

Enable Anthos VM Runtime

Anthos VM Runtime is automatically installed in Anthos clusters on bare metal version 1.10 or higher, but is disabled by default. Before you can run VM resources in your Anthos clusters on bare metal, you must enable the Anthos VM Runtime.


Anthos clusters on bare metal 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. Anthos clusters on bare metal 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 Anthos VM Runtime is already enabled, the command returns an error.

Custom resource

Anthos clusters on bare metal version 1.10 or higher can use a custom resource definition to enable Anthos VM Runtime. This custom resource is installed by default.

  1. Edit the VMRuntime custom resource:

    kubectl edit vmruntime
  2. Set enabled:true in the spec:

    apiVersion: vm.cluster.gke.io/v1
    kind: VMRuntime
      name: vmruntime
      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 Anthos VM Runtime
    • 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 Anthos VM Runtime 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.
  3. Save the custom resource in your editor.

  4. Verify that the VMRuntime custom resource is enabled:

    kubectl describe vmruntime vmruntime

    The details of the VMRuntime custom resource include a Status section. Anthos VM Runtime is enabled and working when VMRuntime.Status.Ready shows as true.

Install the virtctl client tool

To create and manage VMs, install the virtctl client tool.

  1. Install the virtctl client tool as a kubectl plugin:

    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.

  2. 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 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.

  1. Create a VM in your cluster. The virtctl plugin is used with the kubectl 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 the virtctl client tool. For more information, see the Anthos VM Runtime known issues.

  2. 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

Connect to your VM

When your VM is running, connect to the console of the VM.

  1. To access a VM from the console, use kubectl:

    kubectl virt console VM_NAME
  2. When prompted, enter the user credentials you specified to create the VM.

  3. 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.

  1. To delete the VM and associated DataVolume, use kubectl:

    kubectl virt delete vm VM_NAME --all

What's next