1. Home
  2. Cloud Servers
  3. Cloud Server API
  4. Virtual Machines
Searching...

Virtual Machines

Contents

These calls allow management of virtual machines (also known as Cloud severs).

The rules for what can be changed on a running virtual machine are currently complex — the best advice is to power down a virtual machine before making any changes to it, or be prepared to handle a refusal from the API.

Endpoints

These are relative to https://uk0.bigv.io

GET /accounts/{account-id}/groups/{group-id}/virtual_machines
GET /accounts/{account-id}/groups/{group-id}/virtual_machines/{vm-id}
POST /accounts/{account-id}/groups/{group-id}/virtual_machines
PUT /accounts/{account-id}/groups/{group-id}/virtual_machines/{vm-id}
DELETE /accounts/{account-id}/groups/{group-id}/virtual_machines/{vm-id}

# Non-nested endpoints (currently only GET)
GET /virtual_machines
GET /virtual_machines?account_id={account-id}
GET /virtual_machines?group_id={group-id}
GET /virtual_machines/{vm-id}
  • Replace {account-id} with the account id or name.
  • Replace {group-id} with the group id or name (or default if you don’t use groups!).
  • Replace {vm-id} with the id of the virtual machine.

Additional endpoints

Attributes

  • autoreboot_on — boolean specifying whether the machine will automatically turn back on on shutdown/reboot.
  • cdrom_url — url of an iso to expose to the vm as a cd drive.
  • cores — number of cpu cores available.
  • memory — amount of memory, in megabytes.
  • name — name of the virtual machine.
  • power_on — boolean specifying whether the machine is turned on.
  • keymap —
  • hardware_profile — which hardware profile is being used (see the definitions page)
  • hardware_profile_locked — whether the hardware profile is locked and therefore will not be auto upgraded.
  • group_id — id of the group this virtual machine belongs to.

Read Only Attributes

These are returned in responses, but can not be set by the user

  • id — unique key (integer).
  • management_address — ssh’ing to this IP will allow (out-of-band) access to the virtual machine using its console. If the VM is not responding or you are locked out for some reason, this is very useful! This is only available from another Bytemark IP Address or prearranged IPs.
  • deleted — boolean specifying whether the machine has been deleted.
  • hostname — bigv hostname for the machine.
  • head — location of the VM on Bytemark’s host machines (heads).
  • zone_name — which zone the virtual machine was created in (see the definitions page). This can be set when creating, but not changed.
  • last_imaged_with — The name of the operating system this virtual machine was last imaged with, according to our records.

Parameters

If you would like to see deleted virtual machines (i.e. virtual machines in which the deleted field is set to true), you need to pass the include_deleted=true parameter through in the query string, e.g.:

GET /accounts/myaccountname/groups/default/virtual_machines?include_deleted=true

# Or if you are using the overview parameter in accounts:
GET /accounts?view=overview&include_deleted=true

Creating a virtual machine

It is possible to create a virtual machine by using POST /accounts/{account-id}/groups/{group-id}/virtual_machines, but it will only be a machine; it will not have a disc or be installed with anything.

To create a virtual machine with discs and an operating system see the create page.

Moving virtual machines between groups

By specifying the group_id in a PUT request body, you can move a virtual machine to another group (which may be in any account). The requester must be at least a group administrator for both groups.

Currently, the virtual machine must be powered off. Additionally, if one of the groups is associated with a private VLAN, the second group must be associated with the same private VLAN.

Power

The signal endpoint can be used to send ACPI signals to the machine, but there is also the more brute force approach — like the mains plug on a physical machine.

  • The power_on attribute specifies if the machine should be turned on or off.
  • The autoreboot_on attribute specifies if the machine should be restarted upon power off.

Therefore the following can be achieved:

Start

autoreboot_on = true
power_on = true

Stop

autoreboot_on = false
power_on = false

Reboot

autoreboot_on = true
power_on = false

Deleting and Purging

When a virtual machine is deleted using the DELETE endpoint, it still exists, but has its deleted attribute set to true. This means it will be taken down and will only show when the include_deleted=true query string is used.

However, it can be undeleted by setting deleted back to false for a certain amount of time after deletion.

If you wish to purge a virtual machine — either a previously deleted one or to delete a live one and ensure that it can’t be undeleted, you can use the purge=true query string with the DELETE endpoint. This will completely remove the server, put the IP address back into the pool and allow the name to be re-used.

DELETE /accounts/{account-id}/groups/{group-id}/virtual_machines/{vm-id}?purge=true

Examples

All virtual machines in a group

Request

GET /accounts/myaccountname/groups/default/virtual_machines

Curl

curl -H "Content-type: application/json" \
     -H "Authorization: Bearer {session-id}" \
     https://uk0.bigv.io/accounts/myaccountname/groups/default/virtual_machines

Response (success: 200)

[{"autoreboot_on":true,"cdrom_url":null,"cores":1,"group_id":1,"id":1234,"management_address":"213.123.123.123","memory":1024,"name":"www1","power_on":true,"keymap":null,"deleted":false,"hostname":"www1.default.myaccount.uk0.bigv.io","head":"head212","hardware_profile":"virtio2013","hardware_profile_locked":false}]

Single virtual machines

Request

GET /accounts/myaccountname/groups/default/virtual_machines/1234

Curl

curl -H "Content-type: application/json" \
     -H "Authorization: Bearer {session-id}" \
     https://uk0.bigv.io/accounts/myaccountname/groups/default/virtual_machines/1234

Response (success: 200)

[{"autoreboot_on":true,"cdrom_url":null,"cores":1,"group_id":1,"id":1234,"management_address":"213.123.123.123","memory":1024,"name":"www1","power_on":true,"keymap":null,"deleted":false,"hostname":"www1.default.myaccount.uk0.bigv.io","head":"head212","hardware_profile":"virtio2013","hardware_profile_locked":false}]

Update

Request

PUT /accounts/myaccountname/groups/default/virtual_machines/45

Curl

curl -H "Content-type: application/json" \
     -H "Authorization: Bearer {session-id}" \
     -X PUT \
     -d '{"power_on":false,"autoreboot_on":false}' \
     https://uk0.bigv.io/accounts/myaccountname/groups/default/virtual_machines/45

Response (success: 200)

{"autoreboot_on":false,"cdrom_url":null,"cores":1,"group_id":3,"id":45,"management_address":"212.123.123.123","memory":1024,"name":"myserver1","power_on":false,"keymap":null,"deleted":false,"hostname":"myserver1.default.myaccountname.uk0.bigv.io","head":null,"hardware_profile":"virtio2013","hardware_profile_locked":false}

Delete

Request

DELETE /accounts/myaccountname/groups/default/virtual_machines/45

Curl

curl -H "Content-type: application/json" \
     -H "Authorization: Bearer {session-id}" \
     -X DELETE \
     https://uk0.bigv.io/accounts/myaccountname/groups/default/virtual_machines/45

Response (success: 204)

Updated on September 14, 2020

Was this article helpful?

Yes No

Related Articles

Have you tried Kubernetes?
Kubernetes (K8s) is helping enterprises to ship faster & scale their business. Sounds good? Let us build a K8s solution for your needs.
Register your interest