API: Virtual Machines

The vm category contains functionality to provision and manage virtual machines.

Action	Required Parameters	Optional Parameters
vm/create	hostname, plan_id	image_id, volume_id, volume_virtio, region, ip, net_id, securitygroups, scripts, key_id, set_password, affinity_group
vm/list	None	None
vm/start	vm_id	None
vm/stop	vm_id	None
vm/reboot	vm_id	None
vm/diskswap	vm_id	None
vm/rescue	vm_id	None
vm/shelve	vm_id	None
vm/unshelve	vm_id	None
vm/delete	vm_id	None
vm/info	vm_id	None
vm/reimage	vm_id, image_id	None
vm/resize	vm_id, plan_id	None
vm/vnc	vm_id	None
vm/floatingip-add	vm_id	ip, private_ip
vm/floatingip-delete	vm_id	ip, keep
vm/iplist	vm_id	None
vm/ip-add	vm_id	ip
vm/ip-delete	vm_id, ip	None
vm/securitygroup-add	vm_id, group_id	None
vm/securitygroup-remove	vm_id, group_id	None
vm/snapshot	vm_id, name	None
vm/rename	vm_id, hostname	None

vm/create

Required parameters:

• hostname - a label for this VM, which will also be used as its hostname
• plan_id - either a numeric ID (see plan/list), or a string ID like "m.2" or "s.4"

Optional parameters:

• image_id - an image ID (see image/list)
• volume_id - a volume ID (see volume/list)
• volume_virtio - 'yes' to use the virtio storage driver (default 'no' for ide driver)
• region - region ('toronto', 'montreal', 'roubaix') (defaults to 'toronto')
• ip - an unattached floating IP to use for this VM (default is to grab a new floating IP)
• net_id - a network ID (see network/list)
• securitygroups - a comma-separated list of security group IDs (e.g. '123,999', see securitygroup/list)
• scripts - a comma-separated list of script IDs (e.g. '123,999', see script/list)
• key_id - a comma-separated list of key IDs (e.g. '123,999', see sshkey/list)
• set_password - 'yes' to set a password via cloud-init for snapshots and volumes (not needed for templates)
• affinity_group - an affinity group UUID (e.g. '68766804-eff2-4ac5-bed7-7daa2fa528c9')

Notes:

• One of image_id and volume_id must be set
• The driver for image sources is derived from the image properties rather than the volume_virtio parameter

Example request and response:

Endpoint: vm/create
hostname=myvm
plan_id=m.4
image_id=94953

{
    "success": "yes",
    "vm_id": "16b64847-0a86-42ea-bea8-ed60bd960c68"
}

vm/list

Endpoint: vm/list

{
    "success": "yes",
    "vms": [
        {
            "bandwidth": "3000",
            "hostname": "myvm",
            "name": "myvm",
            "os_status": "active",
            "plan_id": "89",
            "primaryip": "172.81.176.125",
            "privateip": "172.20.0.228",
            "ram": "4096",
            "region": "toronto",
            "storage": "70",
            "vcpu": "4",
            "vm_id": "16b64847-0a86-42ea-bea8-ed60bd960c68"
        }
    ]
}

Simple Actions (start, stop, reboot, diskswap, rescue, shelve, unshelve, delete)

These actions require vm_id (the VM UUID) and take no other parameters.

Endpoint: vm/stop
vm_id=16b64847-0a86-42ea-bea8-ed60bd960c68

{"success": "yes"}

vm/info

Example request and response:

Endpoint: vm/info
vm_id=16b64847-0a86-42ea-bea8-ed60bd960c68

{
    "extra": {
        "bandwidth": "2500",
        "hostname": "myvm",
        "name": "myvm",
        "os_status": "active",
        "plan_id": "88",
        "primaryip": "172.81.176.21",
        "privateip": "172.20.0.228",
        "ram": "4096",
        "region": "toronto",
        "storage": "35",
        "vcpu": "2",
        "vm_id": "16b64847-0a86-42ea-bea8-ed60bd960c68"
    },
    "info": {
        "additionalip": [],
        "additionalprivateip": [],
        "addresses": [
            {
                "addr": "2602:ffb6:2:0:f816:3eff:fe6a:7b4e",
                "external": "1",
                "version": "6"
            },
            {
                "addr": "172.20.0.228",
                "external": "",
                "version": "4"
            },
            {
                "addr": "172.81.176.21",
                "external": "1",
                "reverse": "21.176.81.172.rdns.lunanode.com.",
                "version": "4"
            }
        ],
        "error_detail": "",
        "host_id": "033ab13d2de597d948b1e734cf3dac2f15e541826fa72abf7c7e3669",
        "hostname": "myvm",
        "image": "Ubuntu 18.04 64-bit (template)",
        "ip": "172.81.176.21",
        "ipv6": [
            "2602:ffb6:2:0:f816:3eff:fe6a:7b4e"
        ],
        "login_details": "username: ubuntu; password: QixaTUKqP1IvxBeG",
        "os": "Ubuntu 18.04 64-bit (template)",
        "privateip": "172.20.0.228",
        "security_group_ids": [
            "4"
        ],
        "security_groups": [
            "default"
        ],
        "securitygroups": [
            "default"
        ],
        "status": "<font color="green"><b>Online</b></font>",
        "status_color": "green",
        "status_nohtml": "Online",
        "status_raw": "active",
        "task_state": "",
        "volumes": ""
    },
    "success": "yes"
}

Response notes:

• Data in "extra" is static or cached, while data in "info" is on-demand. Thus, e.g. use the status in info over os_status in extra.
• host_id is the physical hypervisor ID (you can use affinity groups to ensure your VMs are assigned to the same or distinct hypervisors)

vm/reimage

Required parameters:

• vm_id - the VM UUID
• image_id - an image ID (see image/list)

Notes:

• Re-image can only be performed on non-volume-backed, non-ISO VMs.
• For other VMs, simply delete the VM and re-create it. The floating IP can be retained across VM deletions by detaching it (vm/floatingip-delete), creating a new VM (set the optional 'ip' parameter), and deleting the old VM.

Example request and response:

Endpoint: vm/reimage
vm_id=16b64847-0a86-42ea-bea8-ed60bd960c68
image_id=94953

{"success": "yes"}

vm/resize

Required parameters:

• vm_id - the VM UUID
• plan_id - the new plan ID (see plan/list)

Notes:

• If using local storage (non-volume boot device), the new plan must have the same or larger disk size than the old plan.

Example request and response:

Endpoint: vm/resize
vm_id=16b64847-0a86-42ea-bea8-ed60bd960c68
plan_id=m.8

{"success": "yes"}

vm/vnc

Example request and response:

Endpoint: vm/vnc
vm_id=16b64847-0a86-42ea-bea8-ed60bd960c68

{
    "success": "yes",
    "vnc_url": "https://toronto-ctrl.lunanode.com:6080/vnc2.html?token=f6818d75-b815-456f-ae27-c63fe56e42de"
}

Response notes:

• The vnc_url temporarily exposes the noVNC console for the VM with the specified token secure UUID.

vm/floatingip-add

Add a new floating IP to your VM. This does not add an internal IP (see vm/ip-add).

Required parameters:

• vm_id - the VM UUID

Optional parameters:

• ip - the floating IP address (must be an unattached IP on your account, see floating/list)
• private_ip - the internal IP to which the floating IP should be attached

Notes:

• If ip is not set, a new floating IP address will be added to your account and attached to the VM.
• private_ip must be set if the VM has more than one internal IP.

Example request and response (here, the VM had one internal IP with no associated floating IP):

Endpoint: vm/floatingip-add
vm_id=16b64847-0a86-42ea-bea8-ed60bd960c68

{"success": "yes"}

vm/floatingip-delete

Remove one or all floating IPs from your VM.

Required parameters:

• vm_id - the VM UUID

Optional parameters:

• ip - the floating IP address currently attached to the VM.
• keep - 'yes' to keep the floating IP on your account so that it can be reused (default 'no')

Notes:

• If keep=yes, then the floating IP will be retained on your account in an unattached state. Unattached floating IPs can be used as the ip parameter in vm/create or vm/floatingip-add.
• If ip is not set, all floating IPs attached to the VM will be detached.

Example request and response:

Endpoint: vm/floatingip-delete
vm_id=16b64847-0a86-42ea-bea8-ed60bd960c68

{"success": "yes"}

vm/iplist

Example request and response:

Endpoint: vm/iplist
vm_id=16b64847-0a86-42ea-bea8-ed60bd960c68

{
    "ips": {
        "172.20.0.228": {
            "floating": "172.81.176.125",
            "network": "62eb5bcc-ff99-4fab-84e1-e44a2ff67a6e",
            "network_id": "4",
            "port": "1ae0fc30-9f22-4de9-9611-fe32310ccb35",
            "subnet": "172.20.0.0/16",
            "subnet_identification": "3d783fc1-b54e-4348-936c-4ff1e1812cf5"
        }
    },
    "success": "yes"
}

Response notes:

• The floating attribute will not appear if the internal IP has no associated floating IP.

vm/ip-add

Add an internal IP to the VM. The internal IP won't be associated with a floating IP, if you want an additional floating IP you'll need to call vm/floatingip-add after adding the internal IP.

Required parameters:

• vm_id - the VM UUID

Optional parameters:

• ip - an internal IP address on the network subnet of this VM

Notes:

• If ip is not set, an arbitrary unused internal IP will be selected.

Example request and response:

Endpoint: vm/ip-add
vm_id=16b64847-0a86-42ea-bea8-ed60bd960c68

{
    "ip": "172.20.0.230",
    "success": "yes"
}

vm/ip-delete

Remove an internal IP from the VM.

Required parameters:

• vm_id - the VM UUID
• ip - the internal IP address to remove

Notes:

• The ip must not have any associated floating IP. If it does, you must first detach the floating IP with vm/floatingip-delete.

Example request and response:

Endpoint: vm/ip-delete
vm_id=16b64847-0a86-42ea-bea8-ed60bd960c68
ip=172.20.0.230

{"success": "yes"}

vm/securitygroup-add

Add the VM to a security group.

Required parameters:

• vm_id - the VM UUID
• group_id - the security group ID (see securitygroup/list)

Example request and response:

Endpoint: vm/securitygroup-add
vm_id=16b64847-0a86-42ea-bea8-ed60bd960c68
group_id=5

{"success": "yes"}

vm/securitygroup-remove

Remove the VM from a security group.

Required parameters:

• vm_id - the VM UUID
• group_id - the security group ID (see securitygroup/list)

Example request and response:

Endpoint: vm/securitygroup-remove
vm_id=16b64847-0a86-42ea-bea8-ed60bd960c68
group_id=5

{"success": "yes"}

vm/snapshot

Required parameters:

• vm_id - the VM UUID
• name - a label for the snapshot image

Example request and response:

Endpoint: vm/snapshot
vm_id=16b64847-0a86-42ea-bea8-ed60bd960c68
name=mysnapshot

{
    "image_id": "141091",
    "success": "yes"
}

vm/rename

Required parameters:

• vm_id - the VM UUID
• hostname - a new name for this VM

Example request and response:

Endpoint: vm/rename
vm_id=16b64847-0a86-42ea-bea8-ed60bd960c68
hostname=myvm2

{"success": "yes"}