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.

bmctl

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
    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 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:

    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.

  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 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 UBUNTU_VM \
        --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:

    • UBUNTU_VM: name for your VM
    • 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
    UBUNTU_VM   Running   64s   192.168.2.124
    

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 UBUNTU_VM
    
  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 UBUNTU_VM --all
    

What's next