Virtual Machine Management

Management of virtual machines adds support of the following actions:

Action Description

start

Starts a virtual machine

stop

Stops a virtual machine

suspend

Suspends a virtual machine

refresh

Refreshes a virtual machine

request_retire

Retires a virtual machine

reset

Resets a virtual machine

reboot_guest

Reboots guest in virtual machine

shutdown_guest

Shuts down guest in virtual machine

scan

Scans a virtual machine (Perform SmartState Analysis)

set_miq_server

Sets the server of a virtual machine

set_owner

Sets the owner of a virtual machine

add_event

Adding an event to a virtual machine

add_lifecycle_event

Add a life cycle event to a virtual machine

edit

Edits a virtual machine

delete

Deletes a virtual machine in the appliance

Targeting Virtual Machines

These actions can be triggered on individual virtual machine resources:

/api/vms/:id

As simply as POSTing the following action to a virtual machine.

{
  "action" : "start"
}

Requests can also be made on multiple vms by targetting the primary collection:

/api/vms
{
  "action" : "start",
  "resources" : [
    { "href" : "http://localhost:3000/api/vms/11" },
    { "href" : "http://localhost:3000/api/vms/12" },
    ...
  ]
}

Querying Virtual Machines

Virtual machines are queried via the primary collection URL:

/api/vms

Filtering, sorting and paging as mentioned on the Querying page.

When querying vms, expanding the resources themselves as well as the following subcollections:

accounts

software

For example:

GET /api/vms?expand=resources,accounts,software

Or querying an individual virtual machine

GET /api/vms/:id?expand=accounts,software

Starting a Virtual Machine

{
  "action" : "start"
}

Stopping a Virtual Machine

{
  "action" : "stop"
}

Suspending a Virtual Machine

{
  "action" : "suspend"
}

Refreshing a Virtual Machine

{
  "action" : "refresh"
}

Retiring a Virtual Machine

{
  "action" : "request_retire"
}

Resetting a Virtual Machine

{
  "action" : "reset"
}

Rebooting guest in Virtual Machine

{
  "action" : "reboot_guest"
}

Shutting Down Guest in a Virtual Machine

{
  "action" : "shutdown_guest"
}

Scanning a Virtual Machine

{
  "action" : "scan"
}

Setting Server of a Virtual Machine

{
  "action" : "set_miq_server",
  "resource" : {
    "miq_server" : { "href" : "http://localhost:3000/api/servers/5" }
  }
}
{
  "action" : "set_miq_server",
  "resource" : {
    "miq_server" : { "id" : "6" }
  }
}

To remove the server from the virtual machine, pass in an empty reference as follows:

{
  "action" : "set_miq_server",
  "resource" : {
    "miq_server" : {}
  }
}

Setting Owner of a Virtual Machine

{
  "action" : "set_owner",
  "resource" : {
    "owner" : "admin"
  }
}

Adding an Event to a Virtual Machine

{
  "action" : "add_event",
  "resource" : {
    "event_type" : "...",
    "event_message" : "...",
    "event_time" : "UTC Time"
  }
}
event_time above is optional. If skipped, current time will be used.

Adding a Lifecycle Event to a Virtual Machine

{
  "action" : "add_lifecycle_event",
  "resource" : {
    "event" : "...",
    "status" : "...",
    "message" : "...",
    "created_by" : "..."
  }
}

Editing a Virtual Machine

Basic information of virtual machines can be edited. This includes the following:

VM Info Attribute

description

description

custom attributes

custom_1 …​ custom_9

parent resource

parent_resource - resource href reference

child resources

child_resources - array of resource href references

Virtual machine resources can be edited as follows:

POST /api/vms/:id
{
  "action" : "edit",
  "resource" : {
    "description" : "Updated VM Description",
    "custom_1" : "custom_attribute_1",
    "parent_resource" : { "href" : "http://localhost:3000/api/vms/11" },
    "child_resources" : [
      { "href" : "http://localhost:3000/api/vms/101" },
      { "href" : "http://localhost:3000/api/vms/102" },
      { "href" : "http://localhost:3000/api/vms/103" },
      { "href" : "http://localhost:3000/api/vms/104" }
    ]
  }
}

Virtual machines can also be edited in bulk as follows:

POST /api/vms
{
  "action" : "edit",
  "resources" : [
    {
      "href" : "http://localhost:3000/api/vms/11",
      "custom_9" : "vm_class_a"
    },
    {
      "href" : "http://localhost:3000/api/vms/12",
      "custom_9" : "vm_class_a"
    },
    {
      "href" : "http://localhost:3000/api/vms/13",
      "custom_9" : "vm_class_a"
    }
  ]
}

Deleting a Virtual Machine

{
  "action" : "delete"
}

Or simply doing the following:

DELETE /api/vms/:id

See the main REST API examples section for additional virtual machine management examples.