Manage the VM instance lifecycle

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 org admin cluster, ensure you have the following resources:

  1. Locate the org admin cluster name, or ask your Platform Administrator (PA) what the cluster name is.

  2. Sign in and generate the kubeconfig file for the org admin cluster if you don't have one.

  3. Use the path to the kubeconfig file of the org admin cluster to replace ORG_ADMIN_KUBECONFIG 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.

  1. List all VMs and view the status of each:

    kubectl --kubeconfig ORG_ADMIN_KUBECONFIG \
        get virtualmachines.virtualmachine.gdc.goog -n PROJECT
    

    Replace the variables in the code examples with your own values according to the following table.

    VariableDefinition
    ORG_ADMIN_KUBECONFIG The org admin cluster kubeconfig path.
    PROJECT The GDC project in which the VM resides.

    Example output:

    NAME          STATUS                    AGE
    vm-1          Running                    1d
    vm-2          Stopped                    8d
    vm-3          ErrorConfiguration         1d
    
  2. Get additional details about a particular VM's status:

    kubectl --kubeconfig ORG_ADMIN_KUBECONFIG \
        get virtualmachines.virtualmachine.gdc.goog VM_NAME -n PROJECT -o \
        jsonpath='{"State:"}{.status.state}{"\n"}{"Reason:"}{.status.reason}{"\n"}{"Message:"}{.status.message}{"\n"}'
    

    Replace the following:

    • ORG_ADMIN_KUBECONFIG with the kubeconfig file path for the org admin cluster 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: