VMs Actions¶

VM actions are tasks that can be executed on a VM. These can be things like rebooting, resizing, snapshotting, etc.

VM action requests are generally targeted at one of the “actions” endpoints for a specific VM. The specific actions are usually initiated by sending a POST request with the action and arguments as parameters.

VM action requests create a VM actions object, which can be used to get information about the status of an action. Creating a VM action is asynchronous: the HTTP call will return the action object before the action has finished processing on the VM. The current status of an action can be retrieved from either the VM actions endpoint or the global actions endpoint.

Attribute	Type	Description
id	string	VM id against what action event was triggered.
status	string	The current status of the action. The value of this attribute will be “in-progress”, “completed”, or “errored”.
type	string	The type of action that the event is executing (reboot, power_off, etc.).
started_at	string	A time value given in ISO8601 combined date and time format that represents when the action was initiated.
completed_at	string	A time value given in ISO8601 combined date and time format that represents when the action was completed.
resource_type	string	The type of resource that the action is associated with.
region	string	Region where the action occurred.

Reboot a VM¶

To reboot a VM, send a POST request to /api/v1/vms/$VM_ID/actions. Set the “type” attribute to reboot.

A reboot action is an attempt to reboot the VM in a graceful way, similar to using the reboot command from the console.

Name	Type	Description	Required
type	string	Must be reboot \| true

The response will be a JSON object with a key called action. The value will be a VM actions object:

Attribute	Type	Description
id	string	VM id against what action event was triggered.
status	string	The current status of the action. The value of this attribute will be “in-progress”, “completed”, or “errored”.
type	string	The type of action that the event is executing (reboot, power_off, etc.).
started_at	string	A time value given in ISO8601 combined date and time format that represents when the action was initiated.
completed_at	string	A time value given in ISO8601 combined date and time format that represents when the action was completed.
resource_type	string	The type of resource that the action is associated with.
region	string	Region where the action occurred.

cURL Example:

curl -X POST -H 'Content-Type: application/json' -u 'user@example.com:password' -d '{"type":"reboot"}' "https://cloudsfor.com/api/v1/vms/5609f1ee1b0c4d2da622737b5ca25e6c/actions"

Request Headers:

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

Request Body:

{
  "type": "reboot"
}

Response Headers:

content-type: application/json; charset=utf-8
status: 201 Created

Response Body:

{
  "action": {
    "id": "5609f1ee1b0c4d2da622737b5ca25e6c",
    "status": "in-progress",
    "type": "reboot",
    "started_at": "2015-01-14T16:31:00Z",
    "completed_at": null,
    "resource_type": "vm",
    "region": "moscow_01",
  }
}

Power Cycle a VM¶

To power cycle a VM (power off and then back on), send a POST request to /api/v1/vms/$VM_ID/actions. Set the “type” attribute to power_cycle.

A powercycle action is similar to pushing the reset button on a physical machine, it’s similar to booting from scratch.

Name	Type	Description	Required
type	string	Must be power_cycle \| true

The response will be a JSON object with a key called action. The value will be a VM actions object:

Attribute	Type	Description
id	string	VM id against what action event was triggered.
status	string	The current status of the action. The value of this attribute will be “in-progress”, “completed”, or “errored”.
type	string	The type of action that the event is executing (reboot, power_off, etc.).
started_at	string	A time value given in ISO8601 combined date and time format that represents when the action was initiated.
completed_at	string	A time value given in ISO8601 combined date and time format that represents when the action was completed.
resource_type	string	The type of resource that the action is associated with.
region	string	Region where the action occurred.

cURL Example:

curl -X POST -H 'Content-Type: application/json' -u 'user@example.com:password' -d '{"type":"power_cycle"}' "https://cloudsfor.com/v1/vms/5609f1ee1b0c4d2da622737b5ca25e6c/actions"

Request Headers:

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

Request Body:

{
  "type": "power_cycle"
}

Response Headers:

content-type: application/json; charset=utf-8
status: 201 Created

Response Body:

{
  "action": {
    "id": "5609f1ee1b0c4d2da622737b5ca25e6c",
    "status": "in-progress",
    "type": "power_cycle",
    "started_at": "2015-01-14T16:31:03Z",
    "completed_at": null,
    "resource_type": "vm",
    "region": "moscow_01",
  }
}

Shutdown A VM¶

To shutdown a VM, send a POST request to /api/v1/vms/$VM_ID/actions. Set the “type” attribute to shutdown.

A shutdown action is an attempt to shutdown the VM in a graceful way, similar to using the shutdown command from the console. Since a shutdown command can fail, this action guarantees that the command is issued, not that it succeeds. The preferred way to turn off a VM is to attempt a shutdown, with a reasonable timeout, followed by a power off action to ensure the VM is off.

Name	Type	Description	Required
type	string	Must be shutdown \| true

The response will be a JSON object with a key called action. The value will be a VM actions object:

Attribute	Type	Description
id	string	VM id against what action event was triggered.
status	string	The current status of the action. The value of this attribute will be “in-progress”, “completed”, or “errored”.
type	string	The type of action that the event is executing (reboot, power_off, etc.).
started_at	string	A time value given in ISO8601 combined date and time format that represents when the action was initiated.
completed_at	string	A time value given in ISO8601 combined date and time format that represents when the action was completed.
resource_type	string	The type of resource that the action is associated with.
region	string	Region where the action occurred.

cURL Example:

curl -X POST -H 'Content-Type: application/json' -u 'user@example.com:password' -d '{"type":"shutdown"}' "https://cloudsfor.com/api/v1/vms/5609f1ee1b0c4d2da622737b5ca25e6c/actions"

Request Headers:

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

Request Body:

{
  "type": "shutdown"
}

Response Headers:

content-type: application/json; charset=utf-8
status: 201 Created

Response Body:

{
  "action": {
    "id": "5609f1ee1b0c4d2da622737b5ca25e6c",
    "status": "in-progress",
    "type": "shutdown",
    "started_at": "2015-01-04T17:08:03Z",
    "completed_at": null,
    "resource_type": "vm",
    "region": "moscow_01",
  }
}

Power Off a VM¶

To power off a VM, send a POST request to /api/v1/vms/$VM_ID/actions. Set the “type” attribute to power_off.

A power_off event is a hard shutdown and should only be used if the shutdown action is not successful. It is similar to cutting the power on a server and could lead to complications.

The request should contain the following attributes:

Name	Type	Description	Required
type	string	Must be power_off \| true

The response will be a JSON object with a key called action. The value will be a VM actions object:

Attribute	Type	Description
id	string	VM id against what action event was triggered.
status	string	The current status of the action. The value of this attribute will be “in-progress”, “completed”, or “errored”.
type	string	The type of action that the event is executing (reboot, power_off, etc.).
started_at	string	A time value given in ISO8601 combined date and time format that represents when the action was initiated.
completed_at	string	A time value given in ISO8601 combined date and time format that represents when the action was completed.
resource_type	string	The type of resource that the action is associated with.
region	string	Region where the action occurred.

cURL Example:

curl -X POST -H 'Content-Type: application/json' -u 'user@example.com:password' -d '{"type":"power_off"}' "https://cloudsfor.com/v1/vms/5609f1ee1b0c4d2da622737b5ca25e6c/actions"

Request Headers:

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

Request Body:

{
  "type": "power_off"
}

Response Headers:

content-type: application/json; charset=utf-8
status: 201 Created

Response Body:

{
  "action": {
    "id": "5609f1ee1b0c4d2da622737b5ca25e6c",
    "status": "in-progress",
    "type": "power_off",
    "started_at": "2015-01-04T17:08:03Z",
    "completed_at": null,
    "resource_type": "vm",
    "region": "moscow_01",
  }
}

Power On a VM¶

To power on a VM, send a POST request to /api/v1/vms/$VM_ID/actions. Set the “type” attribute to power_on.

Name	Type	Description	Required
type	string	Must be power_on \| true

The response will be a JSON object with a key called action. The value will be a VM actions object:

Attribute	Type	Description
id	string	VM id against what action event was triggered.
status	string	The current status of the action. The value of this attribute will be “in-progress”, “completed”, or “errored”.
type	string	The type of action that the event is executing (reboot, power_off, etc.).
started_at	string	A time value given in ISO8601 combined date and time format that represents when the action was initiated.
completed_at	string	A time value given in ISO8601 combined date and time format that represents when the action was completed.
resource_type	string	The type of resource that the action is associated with.
region	string	Region where the action occurred.

cURL Example:

curl -X POST -H 'Content-Type: application/json' -u 'user@example.com:password' -d '{"type":"power_on"}' "https://cloudsfor.com/api/v1/vms/5609f1ee1b0c4d2da622737b5ca25e6c/actions"

Request Headers:

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

Request Body:

{
  "type": "power_on"
}

Response Headers:

content-type: application/json; charset=utf-8
status: 201 Created

Response Body:

{
  "action": {
    "id": "5609f1ee1b0c4d2da622737b5ca25e6c",
    "status": "in-progress",
    "type": "power_on",
    "started_at": "2015-01-14T16:31:19Z",
    "completed_at": null,
    "resource_type": "vm",
    "region": "moscow_01",
  }
}

Password Reset a VM¶

To reset the password for a VM, send a POST request to /api/v1/vms/$VM_ID/actions. Set the “type” attribute to password_reset.

Name	Type	Description	Required
type	string	Must be password_reset \| true

The response will be a JSON object with a key called action. The value will be a VM actions object:

Attribute	Type	Description
id	string	VM id against what action event was triggered.
status	string	The current status of the action. The value of this attribute will be “in-progress”, “completed”, or “errored”.
type	string	The type of action that the event is executing (reboot, power_off, etc.).
started_at	string	A time value given in ISO8601 combined date and time format that represents when the action was initiated.
completed_at	string	A time value given in ISO8601 combined date and time format that represents when the action was completed.
resource_type	string	The type of resource that the action is associated with.
region	string	Region where the action occurred.

URL Example:

curl -X POST -H 'Content-Type: application/json' -u 'user@example.com:password' -d '{"type":"password_reset"}' "https://cloudsfor.com/api/v1/vms/5609f1ee1b0c4d2da622737b5ca25e6c/actions"

Request Headers:

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

Request Body:

{
  "type": "password_reset"
}

Response Headers:

content-type: application/json; charset=utf-8
status: 201 Created

Response Body:

{
  "action": {
    "id": "5609f1ee1b0c4d2da622737b5ca25e6c",
    "status": "in-progress",
    "type": "password_reset",
    "started_at": "2015-01-14T16:31:25Z",
    "completed_at": null,
    "resource_type": "vm",
    "region": "moscow_01",
  }
}

Resize a VM¶

To resize a VM, send a POST request to /api/v1/vms/$VM_ID/actions. Set the “type” attribute to resize and the “size” attribute to a sizes slug.

The VM must be powered off prior to resizing.

Name	Type	Description	Required
type	string	Must be resize \| true
resource	string	Must be ram, disk or cpu \| true
size	number	Must quantity or size in GB	true

There is also possibility to upgrade all the VM resources in a single request. Instead of resource and size attributes data attribute can be used like this:

Name	Type	Description	Required
type	string	Must be resize	true
data	assoc array	Should be associative array with keys disk, ram, cpu and it’s values	true

The response will be a JSON object with a key called action. The value will be a VM actions object:

Attribute	Type	Description
id	string	VM id against what action event was triggered.
status	string	The current status of the action. The value of this attribute will be “in-progress”, “completed”, or “errored”.
type	string	The type of action that the event is executing (reboot, power_off, etc.).
started_at	string	A time value given in ISO8601 combined date and time format that represents when the action was initiated.
completed_at	string	A time value given in ISO8601 combined date and time format that represents when the action was completed.
resource_type	string	The type of resource that the action is associated with.
region	string	Region where the action occurred.

cURL Example:

curl -X POST -H 'Content-Type: application/json' -u 'user@example.com:password' -d '{"type":"resize","resource":'ram', "size":2}' "https://cloudsfor.com/v1/vms/5609f1ee1b0c4d2da622737b5ca25e6c/actions"

Request Headers:

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

Request Body:

{
  "type": "resize",
  "resource": 'ram',
  "size": 2
}

Or, for bulk upgrade of VM’s resource:

cURL Example:

curl -X POST -H 'Content-Type: application/json' -u 'user@example.com:password' -d '{"type":"resize","data":{"cpu":2,"ram":3,"disk":30}}' "https://cloudsfor.com/v1/vms/5609f1ee1b0c4d2da622737b5ca25e6c/actions"

Request Headers:

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

Request Body:

{
  "type": "resize",
  "data": {"cpu": 2, "ram": 3, "disk": 30}
}

Response Headers:

content-type: application/json; charset=utf-8
status: 201 Created

Response Body:

{
  "action": {
    "id": "5609f1ee1b0c4d2da622737b5ca25e6c",
    "status": "in-progress",
    "type": "resize",
    "started_at": "2015-01-14T16:33:17Z",
    "completed_at": null,
    "resource_type": "vm",
    "region": "moscow_01",
  }
}

Rename a VM¶

To rename a VM, send a POST request to /api/v1/vms/$VM_ID/actions. Set the “type” attribute to rename and the “name” attribute to the new name for the vm.

Name	Type	Description	Required
type	string	Must be rename \| true
name	string	The new name for the VM \| true

The response will be a JSON object with a key called action. The value will be a VM actions object:

Attribute	Type	Description
id	string	VM id against what action event was triggered.
status	string	The current status of the action. The value of this attribute will be “in-progress”, “completed”, or “errored”.
type	string	The type of action that the event is executing (reboot, power_off, etc.).
started_at	string	A time value given in ISO8601 combined date and time format that represents when the action was initiated.
completed_at	string	A time value given in ISO8601 combined date and time format that represents when the action was completed.
resource_type	string	The type of resource that the action is associated with.
region	string	Region where the action occurred.

cURL Example:

curl -X POST -H 'Content-Type: application/json' -u 'user@example.com:password' -d '{"type":"rename","name":"new-name"}' "https://cloudsfor.com/api/v1/vms/5609f1ee1b0c4d2da622737b5ca25e6c/actions"

Request Headers:

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

Request Body:

{
  "type": "rename",
  "name": "new-name"
}

Response Headers:

content-type: application/json; charset=utf-8
status: 201 Created

Response Body:

{
  "action": {
    "id": "5609f1ee1b0c4d2da622737b5ca25e6c",
    "status": "in-progress",
    "type": "rename",
    "started_at": "2015-01-14T16:34:16Z",
    "completed_at": null,
    "resource_type": "vm",
    "region": "moscow_01",
  }
}

Snapshot a VM¶

Please note that this functionality is not available in demo mode. To snapshot a VM, send a POST request to /api/v1/vms/$VM_ID/actions. Set the “type” attribute to snapshot and the “name” attribute to the name you would like to give the created image.

Name	Type	Description	Required
type	string	Must be snapshot \| true

The response will be a JSON object with a key called action. The value will be a VM actions object:

Attribute	Type	Description
id	string	VM id against what action event was triggered.
status	string	The current status of the action. The value of this attribute will be “in-progress”, “completed”, or “errored”.
type	string	The type of action that the event is executing (reboot, power_off, etc.).
started_at	string	A time value given in ISO8601 combined date and time format that represents when the action was initiated.
completed_at	string	A time value given in ISO8601 combined date and time format that represents when the action was completed.
resource_type	string	The type of resource that the action is associated with.
region	string	Region where the action occurred.

cURL Example:

curl -X POST -H 'Content-Type: application/json' -u 'user@example.com:password' -d '{"type":"snapshot","name":"New Snapshot"}' "https://cloudsfor.com/api/v1/vms/5609f1ee1b0c4d2da622737b5ca25e6c/actions"

Request Headers:

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

Request Body:

{
  "type": "snapshot",
  "name": "New Snapshot"
}

Response Headers:

content-type: application/json; charset=utf-8
status: 201 Created

Response Body:

{
  "action": {
    "id": "5609f1ee1b0c4d2da622737b5ca25e6c",
    "status": "in-progress",
    "type": "snapshot",
    "started_at": "2015-01-14T16:34:39Z",
    "completed_at": null,
    "resource_type": "vm",
    "region": "moscow_01",
  }
}