Create Virtual Machines
POST https://infrahub-api.nexgencloud.com/v1/core/virtual-machines
Creates one or more virtual machines with the specified custom configuration and features provided in the request body. For more information about the virtual machine features offered by Infrahub, click here.
Body parameters
name string Required
Name of the virtual machine being deployed.
A string with a maximum length of 50 characters.
environment_name string Required
Name of the environment within which your virtual machine will be created.
image_name string Required
Name of the operating system image to be installed on your virtual machine. Use the GET /core/images endpoint to retrieve a list of images offered by Infrahub.
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.
flavor_name string Required
Name of the flavor corresponding to the hardware configuration (CPUs, memory, GPUs, storage and network devices) for your virtual machine. Use the GET /core/flavors endpoint to retrieve a list of available flavors.
key_name string Required
Name of the SSH keypair to be used in gaining secure access to the virtual machine.
count integer Required
Number of virtual machines to be deployed.
The maximum number of VMs that can be deployed per API call is 20.
assign_floating_ip boolean optional
Specifies whether to assign a public IP address to the virtual machine. Setting assign_floating_ip to true enables public accessibility to the virtual machine using the SSH key pair. If you prefer to restrict public access, set assign_floating_ip to false or omit this field, in which case the default value of false will be applied.
security_rules array of objects optional
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.
create_bootable_volume boolean optional
Specify whether to create a virtual machine from a volume with an operating system image installed, known as a bootable volume. Setting this value to true enables creation from a bootable volume, while false disables it. If disabled, the VM wil be created in the Hypervisor and will have access to local NVMe storage.
To create a VM from a new bootable volume in the CEPH storage system, include the desired operating system image in the image_name field and set the create_bootable_volume field to true.
To create a VM from an existing bootable volume, include the volume_name, and leave the create_bootable_volume field blank, or set it to false. For this option, do not provide a value for the image_name field, as the operating system is already installed on the existing bootable volume.
user_data string optional
Initialization configuration data in the form of cloud-init scripts to be executed during virtual machine deployment.
callback_url string optional
The URL where callback events will be sent whenever actions are executed on the virtual machine.
profile object optional
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
labels array of strings optional
An optional array of labels can be applied to the virtual machine for organizational and identification purposes. These labels can be updated after VM deployment using the update virtual machine labels endpoint.
contract_id integer optional
An optional contract ID can be provided to assign the virtual machine (VM) to a specific contract. If the assignment fails due to reasons such as insufficient GPU resources or mismatched GPU types, the VM will still be created (on-demand), and the response will include the reasons why the contract assignment failed. The contract ID can be updated after VM deployment, allowing for organizational and identification purposes.
Attributes
status boolean
Indicates the result of the request to create virtual machines. true signifies success, while false indicates an error.
message string
A description of the status of the request.
instances array of objects
An array of instances objects, containing details about the request to create VMs.
For descriptions of the fields within the instances object returned in response to your request, please refer to the documentation here.
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": "example-vm",
"environment_name": "test1",
"image_name": "Ubuntu Server 22.04 LTS R535 CUDA 12.2",
"flavor_name": "n3-A100x1",
"key_name": "example-key",
"assign_floating_ip": true,
"count": 1
}'
- To authenticate Infrahub API requests, add an
api_keyheader to your API request that contains an API Key.
{
"status": true,
"message": "VM is scheduled for creation.",
"errors":{"contract":"Contract with ID: 1 not found."},
"instances": [
{
"id": 2786,
"name": "example-vm",
"status": "CREATING",
"environment": {
"id": 668,
"name": "test1",
"org_id": 112,
"region": "staging-CA-1"
},
"image": {
"name": "Ubuntu Server 22.04 LTS R535 CUDA 12.2"
},
"flavor": {
"id": 106,
"name": "n3-A100x1",
"cpu": 28,
"ram": 120.0,
"disk": 100,
"ephemeral": 750,
"gpu": "A100-80G-PCIe",
"gpu_count": 1
},
"os": "Ubuntu Server 22.04 LTS R535 CUDA 12.2",
"keypair": {
"name": "example-key"
},
"volume_attachments": [],
"power_state": null,
"vm_state": null,
"fixed_ip": null,
"floating_ip": null,
"floating_ip_status": "ATTACHING",
"security_rules": [],
"callback_url": null,
"locked": false,
"contract_id": null,
"labels": [],
"created_at": "2024-06-17T09:33:46"
}
]
}
Returns
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.