VM power actions using the API

To perform a power action (except for reset) on a VM using the API:

Perform a GET request to obtain the VM object and find the VM state link
Create a virtualmachinestate object
Send a PUT request to the VM state link

The VM state link is a link in the VM object with the "rel" attribute set to state. The "title" attribute contains the current state. You can send a PUT request of a virtualmachine state object to the link (in the "href" attribute) to change the state of the VM.

    {
      "href": "https://mjsabiquo.bcn.abiquo.com:443/api/cloud/virtualdatacenters/2/virtualappliances/1/virtualmachines/47/state",
      "type": "application/vnd.abiquo.virtualmachinestate+json",
      "rel": "state",
      "title": "ON"
    },

Examples of virtualmachinestate objects

Hard power off
```
{"state": "OFF"}
```

Graceful shutdown

{"state": "OFF", "gracefulShutdown": true}

Power on
```
{"state": "ON"}
```
Pause
```
{"state": "PAUSED"}
```

Azure power off and deallocate

Azure has two power off states - powered off and deallocated.

To power off a VM in Azure via the Abiquo API, use the graceful shutdown
To deallocate a VM in Azure via the Abiquo API, use the hard power off
- The deallocated VM will have a "deallocated" attribute that is set to "true".

Example of VM hard power off via API

The API will return a link where you can monitor the progress of this operation.

See https://wiki.abiquo.com/api/latest/VirtualMachinesResource.html#change-the-state-of-a-virtual-machine

Example of failed graceful shutdown

To perform a graceful shutdown, your VM will need to have guest extensions installed on it. After an operation completes, you can view the status of the task by going to the link in the accepted request link of the response. In this case, the graceful shutdown was not supported and failed.

Click here to show or hide the request example

{
  "taskId": "0e69ac87-305a-49c7-b40e-1d7bbc30956d",
  "userId": "10",
  "type": "SHUTDOWN",
  "ownerId": "17883",
  "state": "FINISHED_UNSUCCESSFULLY",
  "creationTimestamp": 1589970620,
  "timestamp": 1589970621,
  "jobs": {
    "links": [],
    "collection": [
      {
        "id": "0e69ac87-305a-49c7-b40e-1d7bbc30956d.818cbbfb-2d08-48d2-9c0b-079811fe0b62",
        "parentTaskId": "0e69ac87-305a-49c7-b40e-1d7bbc30956d",
        "type": "SHUTDOWN",
        "description": "Shutdown task's shutdown on virtual machine with id 17883",
        "state": "FAILED",
        "rollbackState": "ROLLBACK_DONE",
        "creationTimestamp": 1589970620,
        "timestamp": 1589970621,
        "links": []
      }
    ]
  },
  "links": [
    {
      "rel": "self",
      "href": "https://nardo40.bcn.abiquo.com:443/api/cloud/virtualdatacenters/2262/virtualappliances/2829/virtualmachines/17883/tasks/0e69ac87-305a-49c7-b40e-1d7bbc30956d"
    },
    {
      "rel": "parent",
      "href": "https://nardo40.bcn.abiquo.com:443/api/cloud/virtualdatacenters/2262/virtualappliances/2829/virtualmachines/17883/tasks"
    },
    {
      "rel": "acknowledge",
      "href": "https://nardo40.bcn.abiquo.com:443/api/cloud/virtualdatacenters/2262/virtualappliances/2829/virtualmachines/17883/tasks/0e69ac87-305a-49c7-b40e-1d7bbc30956d/action/ack"
    },
    {
      "title": "cloudadmin",
      "rel": "user",
      "type": "application/vnd.abiquo.user+json",
      "href": "https://nardo40.bcn.abiquo.com:443/api/admin/enterprises/304/users/10"
    },
    {
      "title": "ABQ_17d7d473-71e5-45ce-95ca-6deb305a3554",
      "rel": "virtualmachine",
      "type": "application/vnd.abiquo.virtualmachine+json",
      "href": "https://nardo40.bcn.abiquo.com:443/api/cloud/virtualdatacenters/2262/virtualappliances/2829/virtualmachines/17883"
    }
  ]
}

Reset a VM using the API

To reset a VM using the API, use a POST request to the reset action link. If you are using a test environment, you may wish to add the --insecure option.

Click here to expand...

cURL:

curl -X POST http://mjsabiquo.bcn.abiquo.com/api/cloud/virtualdatacenters/2/virtualappliances/1/virtualmachines/47/action/reset \ 
	 -H 'Accept:application/vnd.abiquo.acceptedrequest+json; version=5.0' \ 
	 -u user:password --verbose | jq .

Success status code: 202

Request payload:

--none--

Response payload:

{
  "message": "You can keep track of the progress in the link",
  "links": [
    {
      "title": "status",
      "rel": "status",
      "type": "application/vnd.abiquo.task+json",
      "href": "https://mjsabiquo.bcn.abiquo.com:443/api/cloud/virtualdatacenters/2/virtualappliances/1/virtualmachines/47/tasks/af40013c-ed14-4872-8906-0dc698df46c8"
    }
  ]
}