How to deploy a virtual machine from OVA or OVF

Owned by JM Lopez
Last updated: May 01, 2020
5 min read

Pre-reqs

Step-by-step guide

In order to deploy a new virtual machine, we need at least 5 parameters, however, in case of deploying a vm from image, there's a 6th parameter:

  • client = DepartmentName
  • built_from = Image
  • description = Testing image deployment
  • folder
  • os
  • source_image

If additional customization is needed, we can add:

  • disks
  • networks

Source Image

In order to get the source image, the user deploying the VM will need to upload the OVA or OVF to VSKEY-STOR and then look for the path using the API as follows:

  1. Login to VSKEY-STOR with your VSS credentials and upload the OVA or OVF (including vmdk disks) to deploy.

    Since we run vSphere 5.5, VMX 10 is supported. If you have the latest VMware Fusion or Workstation (VMX 12), update VM compatibility settings to version 10.

  2. Using the /v2/image resource, query any available OVA/OVF files associated with your account as follows:

    Request
    http GET "https://vss-api.eis.utoronto.ca:8001/v2/image" "Authorization: Bearer $TK"
curl -H "Authorization: Bearer $TK" -X GET "https://vss-api.eis.utoronto.ca:8001/v2/image"
    Response body 
    {
    "_links": {
        "api": "https://vss-api.eis.utoronto.ca:8001/v2/",
        "self": "https://vss-api.eis.utoronto.ca:8001/v2/image"
    },
    "data": [
        {
            "name": "Ubuntu_64-bit-vmx10",
            "path": "Ubuntu_64-bit-vmx10.ova"
        }
    ],
    "meta": {
        "count": 1,
        "time": "0.28058s",
        "user": "jm"
    }
}

  3. For our new VM, we will use the JSON object attribute path Ubuntu_64-bit-vmx10.ova.


Target folder

Folders can be got from the /v2/folder with filters as shown below:

  1. Make a GET request disabling summary and looking for the name in question, in this case our target folder will be API Demo

    Request
    http GET "https://vss-api.eis.utoronto.ca/v2/folder?filter=name,like,%APIDemo%" "Authorization: Bearer $TK"
curl -H "Authorization: Bearer $TK" -X GET "https://vss-api.eis.utoronto.ca/v2/folder?filter=name,like,%APIDemo%"
    Response Body 
    {
    "_links": {
        "api": "https://vss-api.eis.utoronto.ca/v2/",
        "self": "https://vss-api.eis.utoronto.ca/v2/folder"
    },
    "data": [
        {
            "_links": {
                "self": "https://vss-api.eis.utoronto.ca/v2/folder/group-v6736"
            },
            "moref": "group-v6666",
            "name": "APIDemo"
        }
    ],
    "meta": {
        "count": 1,
        "time": "0.35628s",
        "user": "jm"
    }
}
  2. From the response body, save the managed object reference (moref) of the folder in question: group-6666. This will be the value of the parameter folder in the VM deployment request.

Target OS

Using the /v2/os resource, the guest identifier can be obtained filtering by name:

  1. Make a GET request with the filter name equals to the operating system to use, for instance ubuntu:

    http GET "https://vss-api.eis.utoronto.ca/v2/os?filter=guest_id,like,%ubuntu%" "Authorization: Bearer $TK"
curl -H "Authorization: Bearer $TK" -X GET "https://vss-api.eis.utoronto.ca/v2/os?filter=guest_id,like,%ubuntu%"
    Response Body 
    {
    "_links": {
        "api": "https://vss-api.eis.utoronto.ca/v2/",
        "self": "https://vss-api.eis.utoronto.ca/v2/os"
    },
    "data": [
        {
            "guest_id": "ubuntuGuest",
            "full_name": "Ubuntu Linux"
        },
        {
            "guest_id": "ubuntu64Guest",
            "full_name": "Ubuntu Linux (64 bit)"
        }
    ],
    "meta": {
        "count": 2,
        "time": "0.00197s",
        "user": "jm"
    }
}
  2. Copy the attribute id value ubuntu64Guest which will be used to populate the os parameter in the VM deployment request.


Target Network

The /v2/network resource provides all virtual networks available for you to use, and as we did with the target folder, we need the target network moref.

  1. Make a GET request to the network resource filtering by name as follows:

    http GET "https://vss-api.eis.utoronto.ca/v2/network?filter=name,like,%1072%" "Authorization: Bearer $TK"
curl -H "Authorization: Bearer $TK" -X GET "https://vss-api.eis.utoronto.ca:8001/v2/network?filter=name,like,%1072%"
    Response Body 
    {
    "_links": {
        "api": "https://vss-api.eis.utoronto.ca/v2/",
        "self": "https://vss-api.eis.utoronto.ca/v2/network"
    },
    "data": [
        {
            "_links": {
                "self": "https://vss-api.eis.utoronto.ca:8001/v2/network/dvportgroup-92"
            },
            "moref": "dvportgroup-92",
            "name": "VL-1072-VSGAN"
        }
    ],
    "meta": {
        "count": 1,
        "time": "0.50400s",
        "user": "jm"
    }
}
  2. The managed object reference dvportgroup-92 will be used to map any existent NIC. If it does not exist, a new NIC will be created.

Deployment

So far, we've got the following parameters ready to deploy a new vm:

  • client = DepartmentName
  • built_from = Image
  • description = Testing image deployment
  • folder = group-6666
  • os = ubuntu64Guest
  • source_image = Ubuntu_64-bit-vmx10.ova
  • networks = dvportgroup-92

However, according to the API documentation, the payload sent via a POST request to the /v2/vm endpoint needs to be sent in JSON format.

{"client": "DepartmentName",
 "built_from": "image",
 "description": "Testing image deployment",
 "folder": "group-6666",
 "os": "ubuntu64Guest",
 "source_image": "Ubuntu_64-bit-vmx10.ova",
 "networks": [{"network": "dvportgroup-92"}],
 "disks": [40, 40]}

Disks was not considered originally but can be added. In this example it will expand disk 1 and add another disk of 40G.

CURL Request
curl -H "Authorization: Bearer $TK" -X POST -H "Content-Type: application/json" https://vss-api.eis.utoronto.ca:8001/v2/vm -d {"client": "DepartmentName", "built_from": "image", "description": "Testing image deployment", "folder": "group-6666", "os": "ubuntu64Guest", "source_image": "Ubuntu_64-bit-vmx10.ova", "networks": [{"network": "dvportgroup-92"}], "disks": [40, 40]}
HTTPie Request
http POST "https://vss-api.eis.utoronto.ca:8001/v2/vm client=DepartmentName" "Authorization: Bearer $TK" built_from=image description="Testing image deployment" folder="group-6666" os="ubuntu64Guest" source_image="Ubuntu_64-bit-vmx10.ova" networks:='[{"network": "dvportgroup-92"}]' disks:='[40, 40]'