VMs¶

VM is a CloudsFor virtual machine. By sending requests to the VM endpoint, you can list, create, or delete VMs.

Some of the attributes will have an object value. The region and image objects will all contain the standard attributes of their associated types. Find more information about each of these objects in their respective sections.

Attribute	Type	Description
id	string	A unique identifier for each VM instance. This is automatically generated upon VM creation.
name	string	The human-readable name set for the VM instance.
memory	number	Memory of the VM in gigabytes.
vcpus	string	The number of virtual CPUs.
disk	string	The size of the VM’s disk in gigabytes.
locked	boolean	A boolean value indicating whether the VM has been locked, preventing actions by users.
created_at	string	A time value given in ISO8601 combined date and time format that represents when the VM was created.
status	string	A status string indicating the state of the VM instance. This may be “running” and “stopped”.
backup_ids	array	An array of backup IDs of any backups that have been taken of the VM instance. VM backups are enabled at the of instance creation.
snapshot_ids	array	An array of snapshot IDs of any snapshots created from the VM instance.
image	object	The details of operating system image, used in this VM. Attributes are: id (internal image identificator), distro (image identificator, that was used upon VM creation stage) and name (human-readable OS description).
features	array	An array of features enabled on this VM.
networks	object	The details of the network that are configured for the VM instance. This is an object that contains keys for IPv4. The value of each of these is an array that contains objects describing an individual IP resource allocated to the VM. These will define attributes like the IP address, netmask, and gateway of the specific network depending on the type of network it is.

Create a new VM¶

To create a new VM, send a POST request to /api/v1/vms.

The attribute values that must be set to successfully create a VM are:

Attribute	Type	Description	Required
name	string	The human-readable string you wish to use when displaying the VM name. The name, if set to a domain name managed in the CloudsFor DNS management system, will configure a PTR record for the VM. The name set during creation will also determine the hostname for the VM in its internal configuration.	true
region	string	The unique slug identifier for the region that you wish to deploy in.	true
image	string	Unique identifier for a public image. This image will be the base image for your VM.	true
size	number	Memory size	true
cpu	number	The number of virtual CPUs.	true
disk_size	number	The size of the VM’s disk in gigabytes.	true
plan	string	Tariff plan, used for accounting of this VM. It may be PLAN_ID_STD (dynamic tarrification) or PLAN_ID_FIX (static tarrification). If value is not set, it would be PLAN_ID_FIX by default.	false
ssh_keys	array	An array containing the IDs of the SSH keys that you wish to embed in the VM’s root account upon creation.	false

A VM will be created using the provided information. The response body will contain a JSON object with a key called vm. The value will be an object containing the standard attributes for your new VM:

Attribute	Type	Description
id	string	A unique identifier for each VM instance. This is automatically generated upon VM creation.
name	string	The human-readable name set for the VM instance.
memory	number	Memory of the VM in gigabytes.
vcpus	string	The number of virtual CPUs.
disk	string	The size of the VM’s disk in gigabytes.
locked	boolean	A boolean value indicating whether the VM has been locked, preventing actions by users.
created_at	string	A time value given in ISO8601 combined date and time format that represents when the VM was created.
status	string	A status string indicating the state of the VM instance. This may be “running” and “stopped”.
backup_ids	array	An array of backup IDs of any backups that have been taken of the VM instance. VM backups are enabled at the time of the instance creation.
snapshot_ids	array	An array of snapshot IDs of any snapshots created from the VM instance.
plan	string	Tariff plan, used for accounting of this VM.
features	array	An array of features enabled on this VM.
networks	object	The details of the network that are configured for the VM instance. This is an object that contains keys for IPv4. The value of each of these is an array that contains objects describing an individual IP resource allocated to the VM. These will define attributes like the IP address, netmask, and gateway of the specific network depending on the type of network it is.

cURL Example:

curl -X POST -H 'Content-Type: application/json' -u 'user@example.com:password' -d '{"name":"example.com","region":"moscow_01","size":1,"image":"fedora-19","ssh_keys":null,"backups":false,"ipv6":false,"user_data":null,"private_networking":null}' "https://cloudsfor.com/api/v1/vms"

Request Headers:

Content-Type: application/json
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=

Request Body:

{
  "name": "example.com",
  "region": "moscow_01",
  "size": 1,
  "disk_size": 10,
  "cpu": 1,
  "image": "fedora-19",
  "ssh_keys": null,
  "backups": false,
  "ipv6": false,
  "user_data": null,
  "private_networking": false
}

Response Headers:

content-type: application/json; charset=utf-8
status: 202 Accepted

Response Body:

{
  "vm": {
    "id": "9a33ef4fec394360a88e3c60b78b5dbc",
    "name": "example.com",
    "memory": 1,
    "vcpus": 1,
    "disk": 10,
    "locked": true,
    "status": "new",
    "plan": "PLAN_ID_FIX",
    "created_at": "2015-01-14T16:36:31Z",
    "features": [],
    "backup_ids": [],
    "snapshot_ids": [],
  },
  "links": {
  }
}

Retrieve an existing VM by id¶

To show an individual VM, send a GET request to /api/v1/vms/$VM_ID.

The response will be a JSON object with a key called vm. This will be set to a JSON object that contains the VM’s attributes:

Attribute	Type	Description
id	string	A unique identifier for each VM instance. This is automatically generated upon VM creation.
name	string	The human-readable name set for the VM instance.
memory	number	Memory of the VM in gigabytes.
vcpus	string	The number of virtual CPUs.
disk	string	The size of the VM’s disk in gigabytes.
locked	boolean	A boolean value indicating whether the VM has been locked, preventing actions by users.
created_at	string	A time value given in ISO8601 combined date and time format that represents when the VM was created.
status	string	A status string indicating the state of the VM instance. This may be “running” and “stopped”.
backup_ids	array	An array of backup IDs of any backups that have been taken of the VM instance. VM backups are enabled at the time of the instance creation.
snapshot_ids	array	An array of snapshot IDs of any snapshots created from the VM instance.
image	object	The details of operating system image, used in this VM. Attributes are: id (internal image identificator), distro (image identificator, that was used upon VM creation stage) and name (human-readable OS description).
plan	string	Tariff plan, used for accounting of this VM.
features	array	An array of features enabled on this VM.
networks	object	The details of the network that are configured for the VM instance. This is an object that contains keys for IPv4. The value of each of these is an array that contains objects describing an individual IP resource allocated to the VM. These will define attributes like the IP address, netmask, and gateway of the specific network depending on the type of network it is.

cURL Example:

curl -X GET -H 'Content-Type: application/json' -u 'user@example.com:password' "https://cloudsfor.com/api/v1/vms/9a33ef4fec394360a88e3c60b78b5dbc"

Request Headers:

Content-Type: application/json
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=

Response Headers:

content-type: application/json; charset=utf-8
status: 200 OK

Response Body:

{
  "vm": {
    "id": "9a33ef4fec394360a88e3c60b78b5dbc",
    "name": "example.com",
    "memory": 1,
    "vcpus": 1,
    "disk": 10,
    "locked": true,
    "plan": "PLAN_ID_FIX",
    "status": "running",
    "created_at": "2015-01-14T16:36:31Z",
    "features": [],
    "backup_ids": [],
    "snapshot_ids": [],
  },
  "links": {
  }
}

List All VMs¶

To list all VMs in your account, send a GET request to /api/v1/vms.

The response body will be a JSON object with a key of vms. This will be set to an array containing objects representing each VM. These will contain the standard VM attributes:

Attribute	Type	Description
id	string	A unique identifier for each VM instance. This is automatically generated upon VM creation.
name	string	The human-readable name set for the VM instance.
memory	number	Memory of the VM in gigabytes.
vcpus	string	The number of virtual CPUs.
disk	string	The size of the VM’s disk in gigabytes.
locked	boolean	A boolean value indicating whether the VM has been locked, preventing actions by users.
created_at	string	A time value given in ISO8601 combined date and time format that represents when the VM was created.
status	string	A status string indicating the state of the VM instance. This may be “running” and “stopped”.
backup_ids	array	An array of backup IDs of any backups that have been taken of the VM instance. VM backups are enabled at the time of the instance creation.
snapshot_ids	array	An array of snapshot IDs of any snapshots created from the VM instance.
image	object	The details of operating system image, used in this VM. Attributes are: id (internal image identificator), distro (image identificator, that was used upon VM creation stage) and name (human-readable OS description).
features	array	An array of features enabled on this VM.
networks	object	The details of the network that are configured for the VM instance. This is an object that contains keys for IPv4. The value of each of these is an array that contains objects describing an individual IP resource allocated to the VM. These will define attributes like the IP address, netmask, and gateway of the specific network depending on the type of network it is.

cURL Example:

curl -X GET -H 'Content-Type: application/json' -u 'user@example.com:password' "https://cloudsfor.com/api/v1/vms"

Request Headers:

Content-Type: application/json
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=

Response Headers:

content-type: application/json; charset=utf-8
status: 200 OK

Response Body:

{
  "vms": {
    "id": "9a33ef4fec394360a88e3c60b78b5dbc",
    "name": "example.com",
    "memory": 1,
    "vcpus": 1,
    "disk": 10,
    "locked": true,
    "status": "running",
    "created_at": "2015-01-14T16:36:31Z",
    "features": [],
    "backup_ids": [],
    "snapshot_ids": [],
  },
  {
    "id": "fcaa52bf0f1d4157a71912e1a70f1bd2",
    "name": "example2.com",
    "memory": 2,
    "vcpus": 4,
    "disk": 30,
    "locked": true,
    "status": "stopped",
    "created_at": "2015-01-14T16:36:31Z",
    "features": [],
    "backup_ids": [],
    "snapshot_ids": [],
  },
  "links": {
  }
}

List snapshots for a VM¶

To retrieve the snapshots that have been created from a VM, sent a GET request to /api/v1/vms/$VM_ID/snapshots.

You will get back a JSON object that has a snapshots key. This will be set to an array of snapshot objects, each of which contain the standard image attributes:

Attribute	Type	Description
id	string	A unique identifier for each VM instance. This is automatically generated upon VM creation.
name	string	The human-readable name set for the VM instance.
memory	number	Memory of the VM in gigabytes.
vcpus	string	The number of virtual CPUs.
disk	string	The size of the VM’s disk in gigabytes.
locked	boolean	A boolean value indicating whether the VM has been locked, preventing actions by users.
created_at	string	A time value given in ISO8601 combined date and time format that represents when the VM was created.
status	string	A status string indicating the state of the VM instance. This may be “running” and “stopped”.
backup_ids	array	An array of backup IDs of any backups that have been taken of the VM instance. VM backups are enabled at the time of the instance creation.
snapshot_ids	array	An array of snapshot IDs of any snapshots created from the VM instance.
features	array	An array of features enabled on this VM.
networks	object	The details of the network that are configured for the VM instance. This is an object that contains keys for IPv4. The value of each of these is an array that contains objects describing an individual IP resource allocated to the VM. These will define attributes like the IP address, netmask, and gateway of the specific network depending on the type of network it is.

Delete a VM¶

To delete a VM, send a DELETE request to /api/v1/vms/$VM_ID.

No response body will be sent back, but the response code will indicate success. Specifically, the response code will be a 204, which means that the action was successful with no returned body data.

cURL Example:

curl -X DELETE -H 'Content-Type: application/json' -u 'user@example.com:password' "https://cloudsfor.com/api/v1/vms/9a33ef4fec394360a88e3c60b78b5dbc"

Request Headers:

Content-Type: application/json
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=

Response Headers:

content-type: application/octet-stream
status: 204 No Content