Skip to main content

GPU Virtual Machine Features

Explore the range of features offered by Infrahub's virtual machines (VMs) to understand how our VM APIs can aid you in creating and managing customized VMs tailored to your specific needs. This VM API guide provides an in-depth look at virtual machines, outlining their capabilities and explaining the supported API operations that empower you to effortlessly create, optimize, and efficiently manage your VMs according to your requirements.

In this article


Features of GPU virtual machines


Environments

An environment is a pre-defined resource container that is established within a region. Virtual machines, SSH keys, and volumes are created within these environments, facilitating the organization of your resources.


Flavors - GPU configurations

Infrahub provides a range of GPU/CPU configurations for your virtual machines, comprising combinations of GPU, vCPUs, RAM, and system disk. These virtual machine configurations are referred to as flavors. Our pre-configured flavors are designed to cater to a diverse range of workloads.


In development

Soon, we will introduce the capability to create custom flavors tailored to the specific requirements of your workloads. Additionally, you will be able to modify the flavor of your existing virtual machines through a process known as resizing.



Operating system images

Select an operating system (OS) image for installation on your virtual machine, or opt for a volume pre-installed with your desired OS, referred to as a bootable volume.


SSH key pairs

Secure shell (SSH) key pairs provide a secure method for accessing and managing your virtual machines. During the creation of a new VM, you must select an existing SSH key pair for association or import a new key pair. Once a key pair is linked with a virtual machine, SSH access to your virtual machines becomes possible.



Volumes

When deploying new virtual machines, you can attach volumes known as Shared Storage Volumes (SSV). This allows for an increase in their data storage capacity by 2PB per volume. One or more volumes can also be attached to an existing virtual machine using the "Attach volumes to virtual machine" endpoint.


Bootable volumes

Virtual machines can be created from volumes with pre-installed operating system images, known as bootable volumes. If a virtual machine is created from a bootable volume, it can be deleted without losing its data, as the data is stored on the volume. You can create a virtual machine from an existing bootable volume by specifying the name of the bootable volume in the volume_name field during VM creation, or the Hyperstack UI. This allows the new VM to access the data saved on the volume and use its operating system, providing a way to modify the VM's specifications without data loss. It's important to note that a bootable volume can only be attached to a single virtual machine at a time due to the lack of support for parallel access to a single disk by most operating systems and file systems.



Cloud-init configuration

Cloud initialization (cloud-init) commands can be used to manage the configuration of a virtual machine at the time of launch. User data can be passed to a virtual machine by using the user_data field within the body of the "Create virtual machine" endpoint. Custom user data instructs a virtual machine to perform automated configuration tasks at the time of launch, including software installation, user account configuration, user initialization, automation of repetitive tasks, and provisioning of specific VM configurations.


Event callbacks

When creating a virtual machine, you have the option to specify a callback URL to receive events when actions are performed on the virtual machine. Additionally, callback URLs can be added to virtual machines after they have been created using the "Attach callback to virtual machine" endpoint.



Internet accessibility

Attach a Public IP address to your virtual machines for internet accessibility. Public IP addresses can be assigned to your virtual machine during VM creation using the assign_floating_ip field. Alternatively, you can attach them to an existing VM by utilizing the "Attach public IP to virtual machine" endpoint.


Provisioning profiles

The Provisioning Profiles feature allows you to save your virtual machine configurations for later use. This includes storing the flavors, environments, user data, and other customization options. These profiles can be easily applied when creating future VMs, making the process more efficient and reducing the chance of errors.



API operations for creating and managing virtual machines


Manage security permissions

OperationsEndpoints
Create a firewall rule for a virtual machinePOST /core/virtual-machines/{id}/sg-rules
Delete a firewall rule for a virtual machineDELETE /core/virtual-machines/{virtual_machine_id}/sg-rules/{sg_rule_id}

Retrieve information about your virtual machines

OperationsEndpoints
Retrieve a list of your virtual machinesGET /core/virtual-machines
Retrieve information from a virtual machineGET /core/virtual-machines/{id}
Retrieve metrics data from a virtual machineGET /core/virtual-machines/{virtual_machine_id}/metrics

Attach a volume to a virtual machine

OperationsEndpoints
Attach a volume to a virtual machinePOST /core/virtual-machines/{virtual_machine_id}/attach-volumes
Detach a volume from a virtual machinePOST /core/virtual-machines/{virtual_machine_id}/detach-volumes

Manage the status of your virtual machine

OperationsEndpoints
Start a virtual machineGET /core/virtual-machines/{id}/start
Stop a virtual machineGET /core/virtual-machines/{id}/stop
Hard-reboot a virtual machineGET /core/virtual-machines/{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/{id}

Create a virtual machine

POST https://infrahub-api.nexgencloud.com/v1/core/virtual-machines

Create a custom virtual machine by including the desired resource configuration in the body of the request.

This request allows you to customize the specifications, operating system, storage, internet accessibility, security, custom initialization configuration scripts, event callbacks and more.

Learn more about these features below.


Example request
curl -X POST "https://infrahub-api.nexgencloud.com/v1/core/virtual-machines" \
-H "accept: application/json"\
-H "api_key: YOUR API KEY"\
-H "content-type: application/json" \
-d '{
"name": "string",
"environment_name": "string",
"image_name": "string",
"volume_name": "string",
"create_bootable_volume": false,
"flavor_name": "string",
"flavor": {...},
"key_name": "string",
"user_data": "string",
"callback_url": "string",
"assign_floating_ip": false,
"security_rules": [{...}],
"profile": {...},
"count": 0
}'

The Create Virtual Machine object

Learn about the fields within the object sent in the body of the request to create a virtual machine. These fields are used to choose the specifications and features of your virtual machine.

Required fields

The following fields must be included in the body of the request to create a new virtual machine.


name string

Name of the virtual machine being deployed.
A string with a maximum length of 50 characters.


environment_name string

Name of the environment within which the virtual machine will be created.


image_name string

Name of the operating system image to be installed on the virtual machine, or bootable volume if the optional create_bootable_volume field is set to true.

note

If you are creating a virtual machine from an existing bootable volume, do not provide a value for the image_name field, as the operating system is already installed on the existing bootable volume.


key_name string

Name of the SSH key pair that was used to import an SSH key.


flavor_name string

Name of the flavor (hardware configuration) that was chosen from the response of the GET /core/flavors endpoint call.


flavor object In development

The flavor object including the custom configuration of the specifications for the virtual machine.

note

The flavor object field is a feature presently under development, which will enable the creation of custom specification configurations.


count integer

The number of virtual machines to be deployed.

The Create Virtual Machine object - required fields
  {
"name": "string",
"environment_name": "string",
"image_name": "string",
"key_name": "string",
"flavor_name": "string",
"flavor": {...},
"count": 0
"volume_name": "string",
"create_bootable_volume": true,
"user_data": "string",
"callback_url": "string",
"assign_floating_ip": false,
"security_rules": [{...}],
"profile": {...},
}'

Optional fields

To specify additional features of a custom virtual machine, you can include the following optional fields in the body of the creation request.



volume_name string

The name(s) of the volumes to be attached to the virtual machine, providing increased storage capacity.

note

Include either the operating system image_name or the volume_name if the existing volume being attached is bootable. Including both will result in a failed API request.


create_bootable_volume boolean

Specify whether to create a virtual machine from a bootable operating system volume with the following valid values: true enables creation from a bootable volume, and false disables it.

To create a virtual machine from a new bootable volume, include the desired operating system image in the image_name and set the create_bootable_volume field to true. To create from an existing bootable volume, include the volume_name and set create_bootable_volume to true.


user_data string

Configure your virtual machine for launch by including cloud-init scripts to be executed during virtual machine deployment.


callback_url string

The URL where callback events will be sent whenever actions are executed on the virtual machine.


assign_floating_ip boolean

Designates whether or not to assign a public IP address to the virtual machine. Setting this field to true makes the virtual machine publicly accessible using the SSH key pair. If you don't want your virtual machine to be publicly accessible, set the assign_floating_ip to false.


security_rules array of objects

Create one or more firewall rules during virtual machine creation by including the security_rules object containing its configuration.

Show child parameters
direction string REQUIRED

The direction of traffic that the firewall rule applies to. Possible values: one of ingress or egress.


protocol string REQUIRED

The network protocol associated with the rule. Possible values: Any one of the protocol values retrieved by calling the GET /core/sg-rules-protocols endpoint.


ethertype string REQUIRED

The Ethernet type associated with the rule. Possible values: one of IPv4 or IPv6.


remote_ip_prefix string REQUIRED

The IP address range that is allowed to access the specified port.


port_range_min integer optional

The minimum port number in the range of ports to be allowed by the firewall rule.


port_range_max integer optional

The maximum port number in the range of ports to be allowed by the firewall rule.


profile object

Save the configuration of this virtual machine for future use by creating a provisioning profile. Include the name and description of the profile as parameters in the profile object.

Show child parameters
name string REQUIRED

The name of the provisioning profile that will be created.
Maximum length of 50 characters.


description string REQUIRED

A brief description of the provisioning profile being saved.
Maximum length of 150 characters.

The Create Virtual Machine object - optional fields
  {
"name": "test-virtual-machine",
"environment_name": "test1",
"image_name": "Ubuntu",
"key_name": "test-key",
"flavor_name": "RTX-A6000",
"count": 1
"volume_name": "string",
"create_bootable_volume": false,
"user_data": "string",
"callback_url": "string",
"assign_floating_ip": false,
"security_rules": [{...}],
"profile": {...},
}'

Back to top