How to update NIC backend network of a virtual machine

Owned by JM Lopez
Last updated: Feb 03, 2017
4 min read

Introduction

When you have multiple Virtual Networks available in our environment, you can easily update any virtual machine NIC backend using the REST API.

A common use case is when virtual machines have been deployed in our public Network, and you have requested a new network subnet (Network Admin Tools) for your department which has been already presented and defined throughout the network core to our environment. 

This guide demonstrates how to update the virtual network attached to any given network interface controller.

Prerequisites

  1. Valid access token. 
  2. Access to Virtual Machine
  3. Virtual Machine name and network interface card to update.

Table of Contents

Step-by-step guide with PyVss

This section assumes, you have already set up both VSS_API_USER and VSS_API_USER_PASS or VSS_API_TOKEN environment variables and installed PyVss.

  1. Create an instance of VssManager and generate token via get_token as follows:

    from pyvss.manager import VssManager
 
vss = VssManager(None)
vss.get_token()        # generates token

  2. Get target VM UUID by first searching by its name

    vms = vss.get_vms(name='vm-testing') # get target vm uuid
vm = vms[0].get('uuid')

  3. Look for the target network:

    networks = vss.get_networks(name='1072')
network = networks[0].get('moref')

  4. Submit change:

    r =  vss.update_vm_nic_network(uuid=vm, nic=1, network=network)

  5. Wait for request to be processed:

    completed = vss.wait_for_request(request_url=r.get('_links').get('request'), request_attr='status', required_status='Processed')

  6. Validate changes

    nic = vss.get_vm_nic(vm, 1)

Step-by-step guide with API Calls

  1. Set the access token environment variable (TK):

    set TK <really_long_string>

  2. Get virtual machine UUID using the search feature in the /vm resource:

    Request
    http GET "https://vss-api.eis.utoronto.ca/v2/vm?name=vm-testing&summary" "Authorization: Bearer $TK"

  3. Display virtual machine network adapters:

    Request
    http GET "https://vss-api.eis.utoronto.ca/v2/vm/<vm_uuid>/nic" "Authorization: Bearer $TK"
    Response Body 
    {
    "_links": {
        "self": "https://vss-api.eis.utoronto.ca/v2/vm/<vm_uuid>/nic",
        "vm": "https://vss-api.eis.utoronto.ca/v2/vm/<vm_uuid>"
    },
    "data": [
        {
            "_links": {
                "network": "https://vss-api.eis.utoronto.ca/v2/network/dvportgroup-92",
                "self": "https://vss-api.eis.utoronto.ca/v2/vm/<vm_uuid>/nic/1"
            },
            "label": "Network adapter 1",
            "network": "VL-1072-VSGAN"
        }
    ],
    "meta": {
        "count": 1,
        "time": "0.21006s",
        "user": "jm"
    }
}

  4. Get the network MOR using the network resource from the API:

    Request
    http GET "https://vss-api.eis.utoronto.ca/v2/network?name=VL-000-TEST" "Authorization: Bearer $TK"
    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/v2/network/dvportgroup-00"
            },
            "accessible": true,
            "moref": "dvportgroup-00",
            "name": "VL-0000-TEST"
        }
    ],
    "meta": {
        "count": 1,
        "time": "0.15235s",
        "user": "jm"
    }
}

  5. Make a PUT request to the virtual machine nic number endpoint update virtual network using attribute network and value dvportgroup-00:

    http PUT "https://vss-api.eis.utoronto.ca/v2/vm/<vm_uuid>/nic/1" "Authorization: Bearer $TK" attribute='network' value='dvportgroup-00'

  6. Display virtual machine network adapters:

    Request
    http GET "https://vss-api.eis.utoronto.ca/v2/vm/<vm_uuid>/nic" "Authorization: Bearer $TK"
    Response Body 
    {
    "_links": {
        "self": "https://vss-api.eis.utoronto.ca/v2/vm/<vm_uuid>/nic",
        "vm": "https://vss-api.eis.utoronto.ca/v2/vm/<vm_uuid>"
    },
    "data": [
        {
            "_links": {
                "network": "https://vss-api.eis.utoronto.ca/v2/network/dvportgroup-92",
                "self": "https://vss-api.eis.utoronto.ca/v2/vm/<vm_uuid>/nic/1"
            },
            "label": "Network adapter 1",
            "network": "VL-0000-TEST"
        }
    ],
    "meta": {
        "count": 1,
        "time": "0.21006s",
        "user": "jm"
    }
}

Using the /vm/<vm_uuid>/nic resource you can also update NIC type (VMXNET3, VMXNET2, E1000, etc.) and state (connect, disconnect). For more information, please refer to this KB Article.