Skip to main content

Virtual Machine State Management

To manage the state of your virtual machines, utilize the API operations outlined below. For each operation, call the corresponding endpoint and include the ID of the virtual machine in the request path.

In this article


API operations for managing VM states

OperationsEndpoints
Start a virtual machineGET /core/virtual-machines/{virtual_machine_id}/start
Stop a virtual machineGET /core/virtual-machines/{virtual_machine_id}/stop
Hard-reboot a virtual machineGET /core/virtual-machines/{virtual_machine_id}/hard-reboot
Hibernate a virtual machineGET /core/virtual-machines/{virtual_machine_id}/hibernate
Restore a virtual machine from hibernationGET /core/virtual-machines/{virtual_machine_id}/hibernate-restore
Delete a virtual machineDELETE /core/virtual-machines/{virtual_machine_id}
info

To avoid data loss, before modifying your virtual machines (hibernate, resize, or delete), back up the data from the temporary storage of the current session, known as the ephemeral disk, to one or more Shared Storage Volumes (SSVs). See the instructions below:

How to save your workload data to an SSV

VM data can be stored by utilizing Shared Storage volumes (SSVs).

  1. Create a volume either through Hyperstack, or by using the Infrahub API's "Create volume" endpoint.

  2. Attach and mount the volume to your virtual machine, achieved either through Hyperstack or by using the "Attach volumes to virtual machine" Infrahub API endpoint.

  3. Once the volume is attached to your virtual machine, you can proceed to move or copy the data from the ephemeral disk to the shared storage volume, saving your data.

  4. With the data now saved on the volume, you can modify the state of the virtual machine without the risk of data loss.


Path parameters


virtual_machine_id REQUIRED integer

The unique identifier for the virtual machine on which the operation is being performed.


Returns


Returns an object containing the status of the response (Where true represents success, and false indicates an error has occurred.) and a message describing the status of the request.


Attributes


status boolean

Specifies the status of the operation performed on the virtual machine. A status of true indicates success, whereas false indicates that an error has occurred.


message string

Provides a message describing the status of the operation carried out on the specified virtual machine.

Example request
curl -X GET "https://infrahub-api.nexgencloud.com/v1/core/virtual-machines/{virtual_machine_id}/start" \
-H "accept: application/json"\
-H "api_key: YOUR API KEY"
Response
{
"status": true,
"message": "Instance Starting"
}

How-to restore a VM with stuck GPUs

When one or more GPUs within a virtual machine become stuck due to hung processes and the VM is improperly rebooted, it can cause the VM to become unresponsive, leading it to enter an ERROR state. To restore a VM with stuck GPU(s) to a functional state, you must first SHUTOFF the VM to release any hung processes. Once in the SHUTOFF state, you can then issue the start command to reboot the operating system and software stack, thereby restoring the VM.

Follow the instructions below to restore a VM with stuck GPU(s) using the Infrahub API.

Error VM

note

This solution also applies to a VM that is in ERROR state. However, we recommend contacting support in these cases at [email protected].


1. Shutting down the VM

To restore the VM, you'll first need to shut it down to release any hung processes. This can be done by issuing the stop command through the Infrahub API. Simply call the GET /core/virtual-machines/{virtual_machine_id}/stop endpoint and include the virtual machine's ID in the request path.



Example request
curl -X GET "https://infrahub-api.nexgencloud.com/v1/core/virtual-machines/{virtual_machine_id}/stop" \
-H "accept: application/json"\
-H "api_key: YOUR API KEY"
Response
{
"status": true,
"message": "VM example-vm is scheduled to stop."
}

VM Shutoff


2. Starting the VM

After the virtual machine has been successfully shut down and is in the SHUTOFF state, you can start it by calling the GET /core/virtual-machines/{virtual_machine_id}/start endpoint and providing the virtual machine's ID in the request path.



Example request
curl -X GET "https://infrahub-api.nexgencloud.com/v1/core/virtual-machines/{virtual_machine_id}/start" \
-H "accept: application/json"\
-H "api_key: YOUR API KEY"
Response
{
"status": true,
"message": "VM example-vm is scheduled to start."
}

Active VM



Back to top