VDC API: How to change the configuration of your VM

Introduction
Step-by-step using cloudmonkey
API calls
Get the status of a virtual machine
Start a virtual machine
Stop a virtual machine
Reboot a virtual machine
Destroy a virtual machine
Recover a virtual machine
Reset the Administrator/Root user password for a virtual machine
Scale a virtual machine to a new service offering
List the service offerings available
Python scripts download

 

Introduction

This document describes how to do several basic configuration tasks for the virtual machines (VMs) in your VDC. These are:

  • check the status of a VM

  • stop, start or reboot (stop and then re-start) a VM.

  • destroy a VM, and recover it from destruction

  • reset the Administrator/Root user password of a VM.

  • change (scale) the 'service offering' (number of CPUs and RAM memory size) for a stopped VM.

  • do 'dynamic scaling' of a VM (change the service offering while the VM is running).

In the Interoute Virtual Data Centre, virtual machines are persistent by default. A VM can be in 'stopped' or 'running' state; a stopped VM holds its storage and network configurations ready to be restarted. You continue to be charged for the stored data of the VM rootdisk, and also for the storage of any snapshots that you have created. A VM must be destroyed to be removed (un-deployed) from the VDC.

Step-by-step using cloudmonkey

You can check the status of a VM if you know its id or its name:

sync

list virtualmachines id=UUID

list virtualmachines name=STRING

(Replace UUID, STRING, and so on, with the actual values for your VDC.)

Most of the commands to modify a VM are asynchronous, so it is most convenient to set

asyncblock=true

With this setting cloudmonkey will perform the necessary querying of the job and returning the final 'jobresult'. You can make this setting permanent in your cloudmonkey configuration file. For more details see Introduction to the VDC API.

Starting and stopping a VM requires only the VM id as a parameter:

start virtualmachine id=UUID

stop virtualmachine id=UUID

The 'reboot' command combines a VM stop followed by a start:

reboot virtualmachine id=UUID

If you start a VM for the first time after it has been deployed, and the VM has been created from a template that is password-enabled, then a new, random password for the Administrator/Root user will be created for the VM and returned in the 'jobresult'. Note that this is the only time the password is communicated through the API. You are recommended always to treat these system-generated passwords as temporary and to login to the VM console and set your own secure password.

If you lose the Admin/Root password, or need to reset the password via the API for any other reason, use the command:

reset passwordforvirtualmachine id=UUID

The new password will be returned in the 'jobresult'. The reset function is also available in the Control Centre user interface.

To destroy a VM involves two steps. The first is to issue a destroy command:

destroy virtualmachine id=UUID

The VM is give the state 'Destroyed' and will remain in your VDC for a period of up to 72 hours (the expunge interval), after which the second step happens and it will be permanently removed (expunged) from the VDC system. During the expunge interval, the VM can be recovered from its Destroyed state by using the command:

recover virtualmachine id=UUID

The VM should now be in a Stopped state.

It is possible to 'scale' (change) the service offering (number of CPUs and amount of RAM memory) of a VM, and different rules apply for a stopped or running VM. When a VM is stopped, the service offering can be changed to any one that is available:

scale virtualmachine id=UUID serviceofferingid=UUID

To find out what service offerings are available, use:

list serviceofferings

When a VM is running, scaling the service offering is known as 'dynamic scaling'. The command is the same:

scale virtualmachine id=UUID serviceofferingid=UUID

However there is a restriction that dynamic scaling has to be upward, that is, at least one of the 'cpunumber' or 'memory' must increase, and the values cannot decrease. Dynamic scaling is only possible when the template used to create the VM has been made 'dynamically scalable' by inclusion of the necessary software. You can check this by taking the UUID value of 'templateid' from the output of list virtualmachine and running the command:

list templates templatefilter=executable id=UUID

Look for the value 'true' for the key 'isdynamicallyscalable'.

API calls

To make a complete HTTP GET request from these example calls, use

http://server/path/to/api?command=.......&apiKey=STRING&signature=HASH

The signature HASH is unique to every API request, calculated by a hashing that uses the content of the GET request and your secret key. If you use cloudmonkey or the Python scripts the signature is calculated for you (see the class file vdc_api_call.py). The procedure to calculate it is described in Introduction to the VDC API.

The letter (A) after a command name means asynchronous. Asynchronous commands start a job to complete their task and immediately return a 'job ID'. You need to send further calls to the API using queryAsyncJobResult with the job ID to check if the job has completed (or use a script to handle that for you). For more information see Introduction to the VDC API.

Only selected optional parameters are listed here, as they are typically used. See the API Command Reference for full descriptions of parameters for all of the commands.

Get the status of a virtual machine

Purpose: To get the status of a virtual machine
Command name: listVirtualMachines
Parameters (Required): None
Parameters (Optional): id=UUID (specify a VM by its ID)
name=STRING (or specify a VM by its name - only one parameter is needed)
Returns: Detailed information about the VM.
Code: command=listVirtualMachine&id=UUID or command=listVirtualMachine&name='VM-Test-01'

Start a virtual machine

Purpose: To start a VM
Command name: startVirtualMachine (A)
Parameters (Required): id=UUID (ID of the VM)
Parameters (Optional): None
Returns: A job ID under the key 'jobid' which can be used to check for completion of the job. When the job is successfully completed the key 'jobresult' contains the details of the VM. If this is a new VM being started for the first time, jobresult may contain the administrator/root password for the VM.
Code:
command=startVirtualMachine&id=UUID

Stop a virtual machine

Purpose: To stop a VM. There is a 'forced stop' option which, in spite of its name, does not force the VM to stop. With this option, the VM is given 'stopped' status in the VDC database, even when the hypervisor fails to report a successful VM stop, for any reason. You must be certain that a VM has actually stopped before executing a forced stop command, or ask a VDC administrator to check the state of the VM at hypervisor level.
Command name: stopVirtualMachine (A)
Parameters (Required): id=UUID (ID of the VM)
Parameters (Optional): forced=BOOLEAN (if true, execute a forced stop of the VM)
Returns: A job ID under the key 'jobid' which can be used to check for completion of the job. When the job is successfully completed the key 'jobresult' contains the details of the VM.
Code:
command=stopVirtualMachine&id=UUID

Reboot a virtual machine

Purpose: To reboot (stop and restart) a VM
Command name: rebootVirtualMachine (A)
Parameters (Required): id=UUID (ID of the VM)
Parameters (Optional): None
Returns: A job ID under the key 'jobid' which can be used to check for completion of the job. When the job is successfully completed the key 'jobresult' contains the details of the virtual machine.
Code:
command=rebootVirtualMachine&id=UUID

Destroy a virtual machine

Purpose: To destroy a VM. The effect is immediate and there is no confirmation step. However a destroyed VM can be recovered for up to 72 hours, after which time it will be expunged (permanently removed from the VDC system). The expunge parameter gives you the option of immediate permanent removal (use with care!).
Command name: destroyVirtualMachine (A)
Parameters (Required): id=UUID (ID of the VM)
Parameters (Optional): expunge=BOOLEAN (if true, destroy the VM and immediately expunge it from the VDC system)
Returns: A job ID under the key 'jobid' which can be used to check for completion of the job. When the job is successfully completed the key 'jobresult' contains the final details of the destroyed VM.
Code:
command=destroyVirtualMachine&id=UUID

Recover a virtual machine

Purpose: To recover a VM from a 'Destroyed' state. This command can be used after a VM has been destroyed and during the expunge interval. If successful, the VM will be left in a Stopped state.
Command name: recoverVirtualMachine
Parameters (Required): id=UUID (ID of the VM)
Parameters (Optional): None
Returns: Status information about the VM.
Code:
command=recoverVirtualMachine&id=UUID

Reset the Administrator/Root user password for a virtual machine

Purpose: To reset the Administrator/Root user password for a VM to a new random password. Only works for a VM that is stopped. The password is returned only once in the output and it is not available later. This command only works for VMs based on templates that are password-enabled. The standard Windows and Linux templates provided by Interoute are all password-enabled. Note also: this is not available for a VM which is only connected to a network of type 'Isolated' (because it requires a virtual router, which is not present).
Command name: resetPasswordForVirtualMachine (A)
Parameters (Required): id=UUID (ID of the VM)
Parameters (Optional): None
Returns: A job ID under the key 'jobid' which can be used to check for completion of the job. When the job is successfully completed the key 'jobresult' contains the details of the virtual machine, including the new password under the key 'password'.
Code:
command=resetPasswordForVirtualMachine&id=UUID

Scale a virtual machine to a new service offering

Purpose: To scale a VM by changing its service offering. For a stopped VM, any available service offering can be applied. For a running VM, only upward scaling is allowed, that is, at least one of the cpunumber or memory must increase, and the values cannot decrease.
Command name: scaleVirtualMachine (A)
Parameters (Required): id=UUID (ID of the VM)
serviceofferingid=UUID (ID of the service offering to be applied)
Parameters (Optional): None
Returns: A job ID under the key 'jobid' which can be used to check for completion of the job. When the job is successfully completed the key 'jobresult' contains the details of the virtual machine. The service offering state of the VM is contained in the keys 'cpunumber', 'memory', and 'serviceofferingname'.
Code:
command=scaleVirtualMachine&id=UUID&serviceofferingid=UUID

List the service offerings available

Purpose: To list the service offerings (compute offerings) available
Command name: listServiceOfferings
Parameters (Required): None
Parameters (Optional): None for this purpose.
Returns: List of service offerings and their properties ('cpunumber' gives number of CPUs, 'memory' gives the memory in MBytes, 'id' gives the UUID of the service offering).
Code:
command=listServiceOfferings

Social

youtubelinkedinfacebookgoogle plustwitter

Interoute's Awards

UK Cloud Awards 2016
Best Cloud Service Provider at the UK Cloud Awards 2016

Gartner Magic Quadrant
2017 Leader in Gartner's Magic Quadrant for Managed Hybrid Cloud Hosting, Europe
2016 Leader in Gartner's Magic Quadrant for Managed Hybrid Cloud Hosting, Europe

Gartner 2015 Magic Quadrant
Leader in Gartner's Cloud-Enabled Managed Hosting Magic Quadrant, Europe

IT Europa European IT & Software Excellence Award
2015 Managed Service Solution of the Year for Interoute Virtual Data Centre

ECO Internet Award
2014 Carrier/ISP Winner for Interoute One Bridge

Capacity Awards
2014 Best pan-European Wholesale Carrier
2013 Best European Product/Service Interoute SmartPoint

Data Center Market
2014 Data Centre Innovation