How to Bytemark

Virtual machines

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!
  • 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 machines 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)
Bytemark Cloud used to be called "BigV"—nothing has changed except the name! We’re hiring! Please visit careers.bytemark.co.uk to find out more.