Version 1.12. This version is no longer supported. For information about how to upgrade to version 1.13, see Upgrading Anthos on bare metal in the 1.13 documentation. For more information about supported and unsupported versions, see the Version history page in the latest documentation.
This document shows you how to enable or disable VM Runtime on Google Distributed Cloud
by either updating the VMRuntime custom resource or running bmctl commands.
Before you begin
To enable or disable VM Runtime on Google Distributed Cloud, you need access to the
following resources and tools:
VM Runtime on Google Distributed Cloud 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 Google Distributed Cloud.
bmctl
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 Google Distributed Cloud is already enabled, the command returns an
error.
Additional settings, such as for emulation or image format, can be configured
by editing the VMRuntime custom resource.
Custom resource
To enable the runtime, update the VMRuntime custom resource. 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 Google Distributed Cloud
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 Google Distributed Cloud 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 Google Distributed Cloud is enabled and working when
VMRuntime.Status.Ready shows as true.
Disable VM Runtime on Google Distributed Cloud
When you no longer need to use VM Runtime on Google Distributed Cloud, you can disable
this feature.
Save the updated custom resource specification in your editor.
To verify that the VMRuntime custom resource is disabled, view the pods
that run in the vm-system namespace:
kubectlgetpods--namespacevm-system
VM Runtime on Google Distributed Cloud is disabled when only the pods that belong to
the vmruntime-controller-manager deployment are running in the
namespace.
Understand the behavior for running VMs
The baremetal.cluster.gke.io/vmrumtime-force-disableannotation can be used on
VM Runtime on Google Distributed Cloud resource to define the behavior when the runtime is
disabled while VMs are running in the cluster.
The following example shows that the value of this annotation is set to false
by default:
// VM runtime yaml fileapiVersion:vm.cluster.gke.io/v1kind:VMRuntimemetadata:annotations:baremetal.cluster.gke.io/vmrumtime-force-disable:"false"name:vmruntime[...]
When this annotation is set to false, VM Runtime on Google Distributed Cloud tries
to protect running VMs. Delete all running VMs before the
VM Runtime on Google Distributed Cloud is disabled, or specify the --force=true
parameter with the bmctl disable vmruntime command as shown in the previous
section.
The following table explains what happens to running VMs when this annotation
is set to true or false and if you specify the --force=true parameter or
not:
Cluster state
--force parameter
vmrumtime-force-disable annotation
Behavior
No VMs
N/A
N/A
Disable VM Runtime on Google Distributed Cloud.
Existing VMs
True
True
Delete all running VMs and the related resources. Disable the
VM Runtime on Google Distributed Cloud.
True
False
Delete all running VMs and the related resources. Disable the
VM Runtime on Google Distributed Cloud.
False
True
Prompt to delete running VMs and related resources. When all running
VMs have been deleted, disable VM Runtime on Google Distributed Cloud.
False
False
Don't delete any existing VMs that are running. Don't disable the
VM Runtime on Google Distributed Cloud. The bmctl command returns an
error.
[[["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-09-03 UTC."],[[["\u003cp\u003eVM Runtime on Google Distributed Cloud, although installed by default in version 1.10 or higher, must be manually enabled before running VM resources.\u003c/p\u003e\n"],["\u003cp\u003eYou can enable or disable VM Runtime using either the \u003ccode\u003ebmctl\u003c/code\u003e command-line tool or by updating the \u003ccode\u003eVMRuntime\u003c/code\u003e custom resource.\u003c/p\u003e\n"],["\u003cp\u003eWhen disabling VM Runtime, the \u003ccode\u003e--force=true\u003c/code\u003e parameter is needed with \u003ccode\u003ebmctl\u003c/code\u003e to delete existing VM resources, and a \u003ccode\u003evmrumtime-force-disable\u003c/code\u003e annotation in the \u003ccode\u003eVMRuntime\u003c/code\u003e resource determines whether running VMs are automatically deleted.\u003c/p\u003e\n"],["\u003cp\u003eIf hardware virtualization is unavailable, the \u003ccode\u003euseEmulation\u003c/code\u003e field in the \u003ccode\u003eVMRuntime\u003c/code\u003e resource can be set to \u003ccode\u003etrue\u003c/code\u003e for software emulation.\u003c/p\u003e\n"],["\u003cp\u003eThe \u003ccode\u003evmImageFormat\u003c/code\u003e field allows you to choose between \u003ccode\u003eraw\u003c/code\u003e (default) and \u003ccode\u003eqcow2\u003c/code\u003e disk image formats, where \u003ccode\u003eraw\u003c/code\u003e may provide improved performance, while \u003ccode\u003eqcow2\u003c/code\u003e may use less disk.\u003c/p\u003e\n"]]],[],null,["# Enable or disable VM Runtime on Google Distributed Cloud\n\n\u003cbr /\u003e\n\nThis document shows you how to enable or disable VM Runtime on Google Distributed Cloud\nby either updating the `VMRuntime` custom resource or running `bmctl` commands.\n\nBefore you begin\n----------------\n\nTo enable or disable VM Runtime on Google Distributed Cloud, you need access to the\nfollowing resources and tools:\n\n- Access to Google Distributed Cloud version 1.12.0 (`anthosBareMetalVersion: 1.12.0`) or higher cluster. You can use any cluster type capable of running workloads. If needed, [try Google Distributed Cloud on Compute Engine](/anthos/clusters/docs/bare-metal/1.12/try/gce-vms) or see the [cluster creation overview](/anthos/clusters/docs/bare-metal/1.12/installing/creating-clusters/create-clusters-overview).\n- The `bmctl` command-line tool. For more information, see [Download and install the `bmctl` tool](/anthos/clusters/docs/bare-metal/1.12/vm-runtime/quickstart#installing-bmctl).\n\nEnable VM Runtime on Google Distributed Cloud\n---------------------------------------------\n\nVM Runtime on Google Distributed Cloud 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 Google Distributed Cloud. \n\n### bmctl\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 Google Distributed Cloud is already enabled, the command returns an\n error.\n\nAdditional settings, such as for emulation or image format, can be configured\nby editing the `VMRuntime` custom resource.\n\n### Custom resource\n\nTo enable the runtime, update the `VMRuntime` custom resource. This custom\nresource is installed by default.\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 Google Distributed Cloud\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 Google Distributed Cloud 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 Google Distributed Cloud is enabled and working when\n `VMRuntime.Status.Ready` shows as `true`.\n\nDisable VM Runtime on Google Distributed Cloud\n----------------------------------------------\n\nWhen you no longer need to use VM Runtime on Google Distributed Cloud, you can disable\nthis feature. \n\n### bmctl\n\n- To disable the runtime, use the `bmctl` tool:\n\n bmctl disable vmruntime --kubeconfig \u003cvar label=\"Kubeconfig path\" translate=\"no\"\u003eKUBECONFIG_PATH\u003c/var\u003e \\\n --force=true\n\n Provide the path to the kubeconfig file for your cluster and values for\n the following configuration options:\n - `--force`: Set to `true` to confirm you want to delete existing VM resources. The default value is `false`.\n\n### Custom resource\n\nTo disable the runtime, update the `VMRuntime` custom resource:\n\n1. Edit the `VMRuntime` custom resource:\n\n kubectl edit vmruntime\n\n2. Set `enabled:false` in the spec:\n\n apiVersion: vm.cluster.gke.io/v1`\n kind: VMRuntime\n metadata:\n name: vmruntime\n spec:\n enabled: false\n useEmulation: true\n vmImageFormat: qcow2\n\n3. Save the updated custom resource specification in your editor.\n\n4. To verify that the `VMRuntime` custom resource is disabled, view the pods\n that run in the `vm-system` namespace:\n\n kubectl get pods --namespace vm-system\n\n VM Runtime on Google Distributed Cloud is disabled when only the pods that belong to\n the `vmruntime-controller-manager` deployment are running in the\n namespace.\n\n### Understand the behavior for running VMs\n\nThe `baremetal.cluster.gke.io/vmrumtime-force-disable`annotation can be used on\nVM Runtime on Google Distributed Cloud resource to define the behavior when the runtime is\ndisabled while VMs are running in the cluster.\n\nThe following example shows that the value of this annotation is set to `false`\nby default: \n\n // VM runtime yaml file\n apiVersion: vm.cluster.gke.io/v1\n kind: VMRuntime\n metadata:\n annotations:\n baremetal.cluster.gke.io/vmrumtime-force-disable: \"false\"\n name: vmruntime\n [...]\n\nWhen this annotation is set to `false`, VM Runtime on Google Distributed Cloud tries\nto protect running VMs. Delete all running VMs before the\nVM Runtime on Google Distributed Cloud is disabled, or specify the `--force=true`\nparameter with the `bmctl disable vmruntime` command as shown in the previous\nsection.\n\nThe following table explains what happens to running VMs when this annotation\nis set to `true` or `false` and if you specify the `--force=true` parameter or\nnot:\n\nWhat's next\n-----------\n\n- [Create a VM in Google Distributed Cloud](/anthos/clusters/docs/bare-metal/1.12/vm-runtime/quickstart)."]]