Deploy Your First Virtual Machine
Deploying your first virtual machine consists of three quick and easy steps:
-
Choose a combination of GPUs, CPUs, RAM, and system disk configurations, called a flavor.
-
Choose an operating system image for your virtual machine.
-
Deploying your virtual machine using the API.
1. Choose a flavor
GET /core/flavors
Select a hardware configuration for your virtual machine, including GPU, CPUs, RAM, and disk, known as a flavor. To view a list of all available flavors, make a request to the GET /core/flavors API endpoint, as shown in the example below. After retrieving the list, choose the flavor that best suits your requirements.
-
Send a GET request to the
/core/flavorsendpoint as seen in the Example request. Make sure to include your API key as anapi_keyheader. -
Choose the flavor with the specifications that meet your workload requirements, and copy the
nameof the flavor. This will be used in the request to create your virtual machine.
In this example only one flavor is displayed; n3-RTX-A6000x1. Using the GET /core/flavors endpoint will return an array of all available flavors.
curl -X GET "https://infrahub-api.nexgencloud.com/v1/core/flavors" \
-H "accept: application/json"\
-H "api_key: YOUR API KEY"
{
"status": true,
"message": "Getting flavors successful",
"data": [
{
"gpu": "RTX-A6000",
"region_name": "CANADA-1",
"flavors": [
{
"id": 111,
"name": "n3-RTX-A6000x1",
"display_name": null,
"region_name": "CANADA-1",
"cpu": 28,
"ram": 58.0,
"disk": 100,
"ephemeral": 0,
"gpu": "RTX-A6000",
"gpu_count": 1,
"stock_available": true,
"created_at": "2024-04-29T17:13:51"
},
{...}
]
}
{...}
]
}
Save the name of the flavor that best suits your requirements. This name will be used to select the flavor for your virtual machine in Step 3.
For this example, we will use the n3-RTX-A6000x1 flavor name from the response above.
2. Choose an operating system image
GET /core/images
Call the GET /core/images endpoint to retrieve the list of available operating system (OS) images, and choose the OS to be installed on your virtual machine.
-
Send a GET request to the
/core/imagesendpoint as seen in the Example request. Make sure to include your API key as anapi_keyheader. -
Choose the operating system image with the specifications that meet your workload requirements, and copy the
nameof the image. This OS image name will be used in the request to create your virtual machine.
In this example, only one image is displayed. Using the GET /core/images endpoint will return an array of all available images.
curl -X GET "https://infrahub-api.nexgencloud.com/v1/core/images" \
-H "accept: application/json"\
-H "api_key: YOUR API KEY"
{
"status": true,
"message": "Getting images successful",
"images": [
{
"region_name": "NORWAY-1",
"type": "Ubuntu",
"logo": "https://api.nexgencloud.com:8080/hyperstack-os-logos/ubuntu.svg",
"images": [
{
"id": 34,
"name": "Ubuntu Server 22.04 LTS",
"region_name": "NORWAY-1",
"type": "Ubuntu",
"version": "Server 22.04 LTS",
"size": 10737418240,
"description": null,
"labels": [],
"display_size": "10.0 GB",
"is_public": true
},
{...}
]
}
]
}
Save the name of the image that best suits your requirements. For our example, we'll use Ubuntu Server 22.04 LTS.
3. Deploy your virtual machine
POST /core/virtual-machines
Using the flavor and image names you obtained from the steps above you are now ready to deploy your virtual machine. Use the POST /core/virtual-machines endpoint with the appropriate payload as shown in the request below.
Request body parameters
name string Required
Name of the virtual machine we are deploying. In this case dev-server.
A string with a maximum length of 50 characters.
environment_name string Required
Name of the environment for the virtual machine. This name was designated when the SSH key was imported. In this example, the environment name development is used.
image_name string Required
Name of the image that you chose from the response of the GET /core/images endpoint. In this example, the image name we are using is Ubuntu Server 22.04 LTS.
flavor_name string Required
Name of the flavor (hardware configuration) that was chosen from the response of the GET /core/flavors endpoint call. In this example, n3-RTX-A6000x1 is used.
key_name string Required
Name of the SSH keypair that was used to import an SSH key. In this example, development-key is used.
count integer Required
Number of virtual machines to be deployed. In this example, 1 virtual machine is deployed.
assign_floating_ip boolean optional
Designates whether or not to assign a public IP address to the virtual machine. In this example, assign_floating_ip is set to true, making 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.
create_bootable_volume boolean optional
Indicates whether or not to create a bootable volume for the virtual machine. Valid values are: true which creates a bootable volume, and false which does not create a bootable volume for the virtual machine. In this case, no bootable volume is required so a value of false is used.
user_data string optional
Custom data or scripts to be executed during virtual machine deployment. A value of "" is used indicating that no custom data is required. Learn more about virtual machine initialization configuration.
Returns
The status of virtual machine deployment and the instances object containing details on the created virtual machine are returned. The CREATING status in the response indicates a successful deployment of the virtual machine.
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": "dev-server",
"environment_name": "development",
"image_name": "Ubuntu Server 22.04 LTS",
"create_bootable_volume": false,
"flavor_name": "n3-RTX-A6000x1",
"key_name": "development-key",
"user_data": "",
"assign_floating_ip": true,
"count": 1
}
{
"status": true,
"message": "Instances are created successfully",
"instances": [
{
"id": 4,
"name": "example-vm",
"status": "CREATING",
"created_at": "2023-05-17T10:01:29",
"keypair": {
"name": "development-key"
"environment": {
"name": "development"
},
"image": {
"name": "Ubuntu Server 22.04 LTS"
},
"flavor": {
"name": "n3-RTX-A6000x1"
},
...
}
Save the id of the created virtual machine. This value will be used to view the details of the virtual machine and the status of its deployment.
For this example, the id of the new virtual machine is 4.
Verify successful deployment of your VM
GET /core/virtual-machines/{id}
Verify the successful deployment of your virtual machine using the GET /core/virtual-machines/{id} endpoint by including the ID of your virtual machine in the path of the request as shown in the example below.
Path parameters
virtual_machine_id integer Required
The unique identifier of the virtual machine for which to retrieve details. In this example, the id of the virtual machine is 4.
Attributes of the Instance object
For more details on the attributes returned by this request, refer to our API documentation.
curl -X GET "https://infrahub-api.nexgencloud.com/v1/core/virtual-machines/4" \
-H "accept: application/json"\
-H "api_key: YOUR API KEY"
{
"status": true,
"message": "Getting VMs successful",
"instances": [
{
"id": 4,
"name": "example-vm",
"status": "ACTIVE",
...
}
]
}
The VM deployment has been successful when "status": "ACTIVE" is returned.
If any other status is returned, such as CREATING, try the request again after waiting a few minutes.
To learn more about the states and statuses of virtual machines, click here.
What's next?
The possibilities for your new virtual machine are almost unlimited. You can now SSH into your virtual machine and begin to use it for your workloads. Learn about the capabilities of your virtual machine by exploring the virtual machines features page, where you can learn about the various resources you can now deploy.
Ensure that your newly created virtual machine has the necessary Nvidia drivers and CUDA drivers installed, both of which must be compatible with your chosen GPU.