Stay organized with collections
Save and categorize content based on your preferences.
A VM instance can transition through many states throughout its lifecycle. When
you create a VM, Google Distributed Cloud (GDC) air-gapped provisions
resources to start the VM. Next, the VM moves into the start state, where it
prepares for a first boot. During and after start-up, a VM is considered
to be running. During its lifetime, a running VM can be repeatedly stopped and
restarted, or suspended and resumed.
VM status definitions
State
Definition
Pending
The VM is accepted by the system and is waiting for allocation.
Provisioning
Resources associated with the VM, such as
VirtualMachineDisk, are being provisioned and prepared.
Starting
The VM is being prepared to run.
Running
The VM is running.
Stopping
The VM is in the process of stopping.
Stopped
The VM is stopped and isn't expected to start.
Paused
The VM is paused and in a frozen state, which is
preserved. The VM cannot be accessed.
Terminating
The VM and its associated resources are undergoing
the deletion process.
ErrorConfiguration
The VM has a configuration error. The invalid
configuration states can be caused by the following:
MachineTypeNotFound - VM type the VM refers to is not found or is being deleted.
MachineDiskMisconfig - The VM disk is incorrectly configured.
InterfaceCreationFailed - The network interface creation failed.
CrashLoopBackOff
The VM is in a crash loop and is waiting to be retried.
PendingIPAllocation
The VM is waiting for the system to assign it an IP address.
Unknown
The VM state could not be obtained, typically due to an error in
communicating with the host on which it's running.
ErrorUnschedulable
An error has occurred while scheduling the VM, for example,
due to resource requests or scheduling constraints that cannot be satisfied
or supported.
DiskError
The VM has an error with one or more of the attached disks.
WaitingForDisk
The VM is waiting for one or more of the attached VirtualMachineDisk to be ready.
CrashLoopBackoff
The VM has been consistently crashing for some reason.
Before you begin
To use gdcloud command-line interface (CLI) commands, ensure that you have downloaded, installed,
and configured the gdcloud CLI.
All commands for Distributed Cloud use the gdcloud or
kubectl CLI, and require an operating system (OS) environment.
Get the kubeconfig file path
To run commands against the Management API server, ensure you have the following
resources:
Sign in and generate the
kubeconfig file for the Management API server if you don't have one.
Use the path to the kubeconfig file of the Management API server to replace
MANAGEMENT_API_SERVER in these instructions.
Request permissions and access
To perform the tasks listed in this page, you must have the Project
VirtualMachine Admin role. Follow the steps to
verify
that you have the Project VirtualMachine Admin (project-vm-admin) role in the namespace
of the project where the VM resides.
For VM operations using the GDC console or the gdcloud CLI,
request your Project IAM Admin to assign you both the
Project VirtualMachine Admin role and the Project Viewer (project-viewer)
role.
Check VM status
Every VM reports its status as part of the VM's properties. Check a VM's status
for any of the following reasons:
If there are issues with the VM.
To confirm the VM is running after it has started.
To verify the VM is in the Paused or Stopped state.
List VMs to check status
The following procedure shows how to list VMs, view their status, and get
additional status information.
MANAGEMENT_API_SERVER with the kubeconfig file for
the Management API server you obtained from the gdcloud auth login command.
VM_NAME with the name of the new VM.
PROJECT with the GDC project
in which the VM resides.
Example output showing Reason and Message values:
State: ErrorConfiguration
Reason: MachineDiskNotFound
Message: VirtualMachineDisk disk-1 in namespace project-1 does not exist.
You might also get empty fields for Reason and Message. This indicates
there was nothing for the system to report regarding them.
Example output with Reason and Message empty:
State: Running
Reason:
Message:
Stop, or restart a VM
During the VM lifecycle you might need to stop and restart a VM,
or delete a VM to respond to a status change or generally manage the VM. See
these pages to stop, reset, or delete a VM:
[[["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-29 UTC."],[[["\u003cp\u003eVM instances in Google Distributed Cloud (GDC) air-gapped environments transition through various states, including \u003ccode\u003ePending\u003c/code\u003e, \u003ccode\u003eProvisioning\u003c/code\u003e, \u003ccode\u003eStarting\u003c/code\u003e, \u003ccode\u003eRunning\u003c/code\u003e, \u003ccode\u003eStopping\u003c/code\u003e, \u003ccode\u003eStopped\u003c/code\u003e, and more, reflecting their current operational status.\u003c/p\u003e\n"],["\u003cp\u003eThe status of a VM can be checked using \u003ccode\u003ekubectl\u003c/code\u003e commands, providing details on the VM's current state, as well as the \u003ccode\u003eReason\u003c/code\u003e and \u003ccode\u003eMessage\u003c/code\u003e fields for troubleshooting configuration errors or other issues.\u003c/p\u003e\n"],["\u003cp\u003eDuring their lifecycle, VMs can be stopped, restarted, or deleted to manage their operational status or to respond to changes, allowing for proper management of resources.\u003c/p\u003e\n"],["\u003cp\u003eTo perform VM operations, users need to have both the Project VirtualMachine Admin and Project Viewer roles assigned to them by the Project IAM Admin.\u003c/p\u003e\n"],["\u003cp\u003eThe \u003ccode\u003egdcloud\u003c/code\u003e CLI and \u003ccode\u003ekubectl\u003c/code\u003e are the primary command-line tools used for interacting with and managing VMs, and requires a valid kubeconfig file from the Management API server.\u003c/p\u003e\n"]]],[],null,["# Manage the VM instance lifecycle\n\nA VM instance can transition through many states throughout its lifecycle. When\nyou create a VM, Google Distributed Cloud (GDC) air-gapped provisions\nresources to start the VM. Next, the VM moves into the start state, where it\nprepares for a first boot. During and after start-up, a VM is considered\nto be running. During its lifetime, a running VM can be repeatedly stopped and\nrestarted, or suspended and resumed.\n\nVM status definitions\n---------------------\n\nBefore you begin\n----------------\n\nTo use `gdcloud` command-line interface (CLI) commands, ensure that you have downloaded, installed,\nand configured the [`gdcloud` CLI](/distributed-cloud/hosted/docs/latest/gdch/resources/gdcloud-overview).\nAll commands for Distributed Cloud use the `gdcloud` or\n`kubectl` CLI, and require an operating system (OS) environment.\n\n### Get the kubeconfig file path\n\nTo run commands against the Management API server, ensure you have the following\nresources:\n\n1. [Sign in and generate](/distributed-cloud/hosted/docs/latest/gdch/application/ao-user/iam/sign-in#cli) the\n kubeconfig file for the Management API server if you don't have one.\n\n2. Use the path to the kubeconfig file of the Management API server to replace\n \u003cvar translate=\"no\"\u003eMANAGEMENT_API_SERVER\u003c/var\u003e in these instructions.\n\n### Request permissions and access\n\nTo perform the tasks listed in this page, you must have the Project\nVirtualMachine Admin role. Follow the steps to\n[verify](/distributed-cloud/hosted/docs/latest/gdch/application/ao-user/vms/preparation#verify-user-access)\nthat you have the Project VirtualMachine Admin (`project-vm-admin`) role in the namespace\nof the project where the VM resides.\n\nFor VM operations using the GDC console or the gdcloud CLI,\nrequest your Project IAM Admin to assign you both the\nProject VirtualMachine Admin role and the Project Viewer (`project-viewer`)\nrole.\n\nCheck VM status\n---------------\n\nEvery VM reports its status as part of the VM's properties. Check a VM's status\nfor any of the following reasons:\n\n- If there are issues with the VM.\n- To confirm the VM is running after it has started.\n- To verify the VM is in the `Paused` or `Stopped` state.\n\n### List VMs to check status\n\nThe following procedure shows how to list VMs, view their status, and get\nadditional status information.\n\n1. List all VMs and view the status of each:\n\n kubectl --kubeconfig \u003cvar translate=\"no\"\u003eMANAGEMENT_API_SERVER\u003c/var\u003e \\\n get virtualmachines.virtualmachine.gdc.goog -n \u003cvar translate=\"no\"\u003ePROJECT\u003c/var\u003e\n\n Replace the variables in the code examples with your own values\n according to the following table.\n\n Example output: \n\n NAME STATUS AGE\n vm-1 Running 1d\n vm-2 Stopped 8d\n vm-3 ErrorConfiguration 1d\n\n2. Get additional details about a particular VM's status:\n\n kubectl --kubeconfig \u003cvar translate=\"no\"\u003eMANAGEMENT_API_SERVER\u003c/var\u003e \\\n get virtualmachines.virtualmachine.gdc.goog \u003cvar translate=\"no\"\u003eVM_NAME\u003c/var\u003e -n \u003cvar translate=\"no\"\u003ePROJECT\u003c/var\u003e -o \\\n jsonpath='{\"State:\"}{.status.state}{\"\\n\"}{\"Reason:\"}{.status.reason}{\"\\n\"}{\"Message:\"}{.status.message}{\"\\n\"}'\n\n Replace the following:\n - \u003cvar translate=\"no\"\u003eMANAGEMENT_API_SERVER\u003c/var\u003e with the kubeconfig file for the Management API server you obtained from the `gdcloud auth login` command.\n - \u003cvar translate=\"no\"\u003eVM_NAME\u003c/var\u003e with the name of the new VM.\n - \u003cvar translate=\"no\"\u003ePROJECT\u003c/var\u003e with the GDC project in which the VM resides.\n\n Example output showing `Reason` and `Message` values: \n\n State: ErrorConfiguration\n Reason: MachineDiskNotFound\n Message: VirtualMachineDisk disk-1 in namespace project-1 does not exist.\n\n You might also get empty fields for `Reason` and `Message`. This indicates\n there was nothing for the system to report regarding them.\n\n Example output with `Reason` and `Message` empty: \n\n State: Running\n Reason:\n Message:\n\nStop, or restart a VM\n---------------------\n\nDuring the VM lifecycle you might need to stop and restart a VM,\nor delete a VM to respond to a status change or generally manage the VM. See\nthese pages to stop, reset, or delete a VM:\n\n- [Stop a VM](/distributed-cloud/hosted/docs/latest/gdch/application/ao-user/vms/manage-vms/operations-and-lifecycle/start-and-stop-vm#stop-a-vm)\n- [Restart a VM](/distributed-cloud/hosted/docs/latest/gdch/application/ao-user/vms/manage-vms/operations-and-lifecycle/start-and-stop-vm#restart-a-vm)\n- [Delete a VM](/distributed-cloud/hosted/docs/latest/gdch/application/ao-user/vms/manage-vms/operations-and-lifecycle/delete-vms)"]]