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
- Supported virtual machine API operations
- Creating a virtual machine with custom features
- How to manage your existing virtual machines
Features of GPU virtual machines
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.
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.
- Click here for additional information on SSV's.
- See instructions on how to create and attach volumes via the Infrahub API.
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
Create a virtual machine
| Operations | Endpoints |
|---|---|
| Create a new virtual machine | POST /core/virtual-machines |
| Retrieve a list of all supported GPU configurations (flavors) | GET /core/flavors |
Manage security permissions
| Operations | Endpoints |
|---|---|
| Create a firewall rule for a virtual machine | POST /core/virtual-machines/{id}/sg-rules |
| Delete a firewall rule for a virtual machine | DELETE /core/virtual-machines/{virtual_machine_id}/sg-rules/{sg_rule_id} |
Retrieve information about your virtual machines
| Operations | Endpoints |
|---|---|
| Retrieve a list of your virtual machines | GET /core/virtual-machines |
| Retrieve information from a virtual machine | GET /core/virtual-machines/{id} |
| Retrieve metrics data from a virtual machine | GET /core/virtual-machines/{virtual_machine_id}/metrics |
Attach a volume to a virtual machine
| Operations | Endpoints |
|---|---|
| Attach a volume to a virtual machine | POST /core/virtual-machines/{virtual_machine_id}/attach-volumes |
| Detach a volume from a virtual machine | POST /core/virtual-machines/{virtual_machine_id}/detach-volumes |
Manage the status of your virtual machine
| Operations | Endpoints |
|---|---|
| Start a virtual machine | GET /core/virtual-machines/{id}/start |
| Stop a virtual machine | GET /core/virtual-machines/{id}/stop |
| Hard-reboot a virtual machine | GET /core/virtual-machines/{id}/hard-reboot |
| Hibernate a virtual machine | GET /core/virtual-machines/{virtual_machine_id}/hibernate |
| Restore a virtual machine from hibernation | GET /core/virtual-machines/{virtual_machine_id}/hibernate-restore |
| Delete a virtual machine | DELETE /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.
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.
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.
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.
{
"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.
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 security 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.
{
"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": {...},
}'