VDC API: How to create a virtual machine

Introduction
A note about passwords
Step-by-step using cloudmonkey
API calls
Create (deploy) a virtual machine
List the zones (and hypervisors) available
List the templates available to create a VM
List the service offerings available
List the disk offerings available
List the ISOs available to create a VM
List the networks available to connect to a VM
Get status information about a VM
Python scripts download

Introduction

To create and configure a new virtual machine you can use a single API command deployVirtualMachine. You must specify the following:

  • The VDC zone and hypervisor where the VM will run.

  • The template or ISO for the operating system.

  • The 'service offering': the number of CPUs and the internal RAM memory. (Note this is called 'compute offering' in the VDC Control Centre.)

The VM is by default created and started by the deploy process. There is an option to create a stopped VM, using startvm=false.

There are many optional parameters, including:

  • A name for the VM (if not specified, the name will be the same as the UUID assigned to the VM).

  • The network(s) to be connected to the VM.

  • The affinity groups to which the VM should belong. (VMs in the same affinity group will not run on the same hypervisor, and will be automatically distributed across several hypervisors. This means that is it is easy to build a resilient solution using multiple VMs.)

Note that you must have an existing network in your VDC before deploying a VM. If there is more than one network in the zone, you need to specify a network.

No network connections to your VM will be created by default.

A note about passwords

If you create a VM using one of the standard Windows or Linux templates provided by Interoute then the initial Administrator password (Windows) or root user password (Linux) will be randomly generated when the VM boots up for the first time. The password is written into the 'jobresult' of the deployVirtualMachine command, unless you set startvm=false, then the password will be output in the jobresult from the later startVM command.

You must extract the password from the jobresult as it is not otherwise obtainable through the API, or the VDC Control Centre user interface. If you lose this password or need to reset it for another reason, use the resetPasswordForVirtualMachine command, which can be applied only to a stopped VM (note: reset password is also available as a function in the Control Centre).

Step-by-step using cloudmonkey

You may need to find the UUIDs of zones, templates, ISOs, or service offerings (RAM and CPU). The basic commands are as follows (replace UUID with the id for the zone you want to use):

sync

list zones

list templates zoneid=UUID templatefilter=executable

list isos zoneid=UUID isofilter=executable

list serviceofferings

If you are using an ISO, then a diskoffering is required for the root disk. (For a template, the rootdisk is already present inside the template, so using the diskoffering option would result in adding a data disk.)

list diskofferings

Using the above information, to deploy from a template, you would use:

deploy virtualmachine zoneid=UUID serviceoffering=UUID
templateid=UUID

Or, from an ISO, you would use:

deploy virtualmachine zoneid=UUID serviceoffering=UUID
templateid=UUID diskofferingid=UUID hypervisor='VMware'

Note that deployment from ISO unusually requires specifying the hypervisor name.

Finally, you can check the status of a VM if you know its id:

list virtualmachines id=UUID

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.

Create (deploy) a virtual machine

Purpose: To create a virtual machine
Command name: deployVirtualMachine (A)
Parameters (Required): templateid=UUID (UUID of the template or ISO)
zoneid=UUID (UUID of the zone where the VM will be created)
serviceofferingid=UUID (UUID of the service offering)
networkids=UUID (required if there is more than one network in the zone)
(UUID of one network to be used, or a list of network UUIDS separated by commas)
diskofferingid=UUID (required for ISO) (UUID of the disk offering)
hypervisor='VMware' (required for ISO)
Parameters (Optional): displayname=STRING (any text to describe the VM)
name=STRING (any text for the name of the VM)
startvm=BOOLEAN (true or false, create the VM in started or stopped state)
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=deployVirtualMachine&templateid=UUID&zoneid=UUID
&serviceofferingid=UUID&name='VM-Test-01'&displayname='My VM 01'

List the zones (and hypervisors) available

Purpose: To list the zones (and hypervisors) available
Command name: listZones
Parameters (Required): None
Parameters (Optional): available=BOOLEAN (true: list all available zones; false: list zones where at least one VM exists)
Returns: List of zones and their properties.
Code:
command=listZones&available=true

List the templates available to create a VM

Purpose: To list the templates available to create a VM (they must be 'executable' and available in the zone of deployment)
Command name: listTemplates
Parameters (Required): templatefilter=executable
Parameters (Optional): zoneid=UUID (UUID of zone for deployment)
Returns: List of templates and their properties.
Code:
command=listTemplates&templatefilter=executable&zoneid=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

List the disk offerings available

Purpose: To list the disk offerings (storage volumes) available. Only the offerings named nnGB VM can be used to create VM root disks in API calls
Command name: listDiskOfferings
Parameters (Required): None
Parameters (Optional): None for this purpose.
Returns: List of disk offerings and their properties (disksize is the size in GB, id gives the UUID of the disk offering).
Code:
command=listDiskOfferings

List the ISOs available to create a VM

Purpose: To list the ISOs available (they must be 'executable' and available in the zone of deployment)
Command name: listIsos
Parameters (Required): None
Parameters (Optional): isofilter=executable
zoneid=UUID (UUID of zone for deployment)
Returns: List of ISOs and their properties.
Code:
command=listIsos&isofilter=executable&zoneid=UUID

List the networks available to connect to a VM

Purpose: To list the networks available (they must be in the zone of deployment)
Command name: listNetworks
Parameters (Required): None
Parameters (Optional): zoneid=UUID (UUID of zone for deployment)
Returns: List of networks and their properties.
Code:
command=listNetworks&zoneid=UUID

Get status information about a VM

Purpose: To get status information about a VM
Command name: listVirtualMachines
Parameters (Required): None
Parameters (Optional): id=UUID (UUID of the VM)
Returns: Properties and status of the VM.
Code:
command=listVirtualMachines&id=UUID

Python scripts download

Right-click on the following links to download each file. Note: '.txt' is added to the filenames on the webserver to prevent the possibility of programs from executing when you download.

vdc_api_call.py

vm_deploy.py

zone_get_all.py

template_get_by_zone.py

service_offering_get_all.py

disk_offering_get_all.py

iso_get_by_zone.py

networks_get_by_zone.py

vm_get_one.py

 

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