RO Northbound Interface

Introduction

This document describes the northbound interface of RO (openmano) Release 1.

The Northbound interface is based on REST and it allows performing actions over the following entities:

• Tenant: Intended to create groups of resources. In this version no security mechanisms are implemented.
• Datacenters: Represents the VIM information stored by openmano.
• VIMs: used to perform an action over a datacenter (specific pool of resources)
• VNFs: SW-based network function, composed of one or several VM that can be deployed on an NFV datacenter.
• Scenarios: topologies of VNFs and their interconnections.
• Instances: Each one of the Scenarios deployed in a datacenter.

HTTP protocol details

• The HTTP HEADER "X-Auth-Token" is ignored in this version, though it will be available in future. Current version does not support security and authentication
• Server supports JSON (by default), and YAML. Use HTTP HEADER "Content-Type:

   application/FORMAT" for specifying the input format and HTTP HEADER "Accept:
   application/FORMAT" for the wanted output format. In this version it does not support
   the URL suffix .yaml or .json as for example openstack neutron does.

• Server supports URL Query String filters. For example:

   HTTP GET /whatever?name1=value1&name2=value2"
   Will filter by "name1=value1 AND name2=value2"

• In a near future version it will support pagination using limit, market, page_reverse and field filtering in the same way as openstack neutron.
• Possible responses of HTTP Commands are:

   200 Ok
   400 Bad Request
   404 Not Found
   405 Method Not Allowed
   409 Conflict
   503 Service Unavailable
   500 Internal Server Error

Openmano Server primitives

Tenants

GET /openmano/tenants

Gets a list of all tenants

Params: None

Response: Content-type: application/json

   {
     "tenants": [
       {
         "created_at": "2015-08-06T10:38:07",
         "description": "tenant_de_prueba",
         "uuid": "76094a2a-3c16-11e5-9fb6-5254004aea96",
         "name": "tenanttest"
       },
       {
         "created_at": "2015-12-04T13:06:54",
         "description": "A description...",
         "uuid": "8293285c-9a7f-11e5-bc4f-5254004aea96",
         "name": "John Doe"
       }
     ]
   }

GET /openmano/tenants/{tenant_id}

Get the full description of the tenant identified by tenant_id (tenant´s name or uuid)

Params: None

Response: Content-type: application/json

   {
     "tenant": {
       "created_at": "2015-12-04T13:06:54",
       "description": "A description...",
       "modified_at": null,
       "uuid": "8293285c-9a7f-11e5-bc4f-5254004aea96",
       "name": "John Doe"
     }
   }

POST/openmano/tenants

Create new tenant

Params: (Extra parameters are ignored) Content-type: application/json

• name: tenant name provided by the client
• description: (optional) tenant description provided by the client

   {
   "tenant":
       {
           "name": "John Doe",
           "description": "A description..."
       }
   }

Response: Content-type: application/json

   {
     "tenant": {
       "created_at": "2015-12-04T13:06:54",
       "description": "A description...",
       "modified_at": null,
       "uuid": "8293285c-9a7f-11e5-bc4f-5254004aea96",
       "name": "John Doe"
     }
   }

PUT /openmano/tenants/{tenant_id}

Update tenant identified by tenant_id (tenant´s name or uuid)

Params: (Extra parameters are ignored) Content-type: application/json

• name: tenant name provided by the client
• description: (optional) tenant description provided by the client

   {
       "tenant":
           {
               "name": "John Doe",
               "description": " Unknown person..."
           }
   }

Response: Content-type: application/json

   {
       "tenant": {
           "created_at": "2015-12-04T13:06:54", 
           "description": " Unknown person...", 
           "modified_at": null, 
           "uuid": "8293285c-9a7f-11e5-bc4f-5254004aea96", 
           "name": "John Doe"
       }
   }

DELETE /openmano/tenants/{tenant_id}

Delete a tenant identified by tenant_id (tenant´s name or uuid)

Params: none

Response: Content-type: application/json

   {
       "result": "tenant 9767ac6e-9a82-11e5-bc4f-5254004aea96 deleted"
   }

Datacenters

These commands does not affect a concrete VIM, but the openmano information of a VIM

GET /openmano/{tenant_id}/datacenters

Get a list of datacenters attached to the tenant identified by tenant_id (tenant´s name or uuid). The parameter 'tenant_id' can be replaced by 'any' to get a list of all datacenters of all tenants.

Params: none.

Response: Content-type: application/json

   {
     "datacenters": [
       {
         "vim_url": "http://localhost:9080/openvim",
         "created_at": "2015-12-09T10:10:00",
         "type": "openvim",
         "uuid": "a01a4b34-9e54-11e5-bc4f-5254004aea96",
         "name": "John_Doe_data_center"
       }
     ]
   }

GET /openmano/{tenant\_id}/datacenters/{datacenter_id}

Get a the parameters of a datacenter attached to a tenant identified by tenant_id. The parameter 'tenant_id' can be replaced by 'any' to look for the datacenter_id in all tenants.

Params:none

Response Content-type: application/json

   {
     "datacenter": {
       "vim_url": "http://localhost:9080/openvim",
       "vim_url_admin": null,
       "created_at": "2015-12-09T10:10:00",
       "uuid": "a01a4b34-9e54-11e5-bc4f-5254004aea96",
       "name": "John_Doe_data_center",
       "type": "openvim",
       "description": null,
       "config": null,
     }
   }

POST /openmano/datacenters

Create a new datacenter

Params: Content-type: application/json

• name: name of the datacenter to create
• vim_url: url of the machine where is hold VIM (Openvim) (TBC)
• type: can be openvim, openstack, ...
• config: extra configuration needed by the specific VIM connectors
• description: descriptive text

   {
       "datacenter":{
           "name": "John_Doe_data_center",
           "vim_url": "http://localhost:9080/openvim"
       }
   }

Response: Content-type: application/json

   {
     "datacenter": {
       "vim_url": "http://localhost:9080/openvim",
       "vim_url_admin": null,
       "created_at": "2015-12-09T10:10:00",
       "uuid": "a01a4b34-9e54-11e5-bc4f-5254004aea96",
       "name": "John_Doe_data_center",
       "type": "openvim",
       "description": null,
       "config": null,
     }
   }

PUT /openmano/datacenters/{datacenter\_id_name}

Modify a datacenter.

Params: Content-type: application/json

Params that can be changed are:

• name: datacenter name
• vim_url: vim url

   {
       "datacenter":{
           "name": "new_datacenter_name",
           "vim_url": "http://localhost:9080/openvim"
       }
   }

Response:

If no error, same as "Post /openmano/datacenters"

GET /openmano/datacenters/{datacenter_id}/networks

Deprecated: see RO_Northbound_Interface#VIMs

POST /openmano/{tenant\_id}/datacenters/{datacenter_id}/action

Deprecated: see RO_Northbound_Interface#VIMs

DELETE /openmano/datacenters/{datacenter_id}

Delete a datacenter

Params:none

Response Content-type: application/json

   {
     "result": "datacenter e3042842-9e78-11e5-bc4f-5254004aea96 deleted"
   }

POST /openmano/<tenant\_id>/datacenters/{datacenter_id}

Attach the datacenter identifiedby datacenter_id and openvim tenant to the openmano tenant

Params: none

Response

If no error, same as GET /openmano/{tenant\_id}/datacenters/{datacenter_id}

DELETE /openmano/<tenant\_id>/datacenters/{datacenter_id}

Detach a datacenter and this tenant

Params: none

Response

If no error, same as GET /openmano/{tenant\_id}/datacenters/{datacenter_id}

VIMs

These commands make actions over a VIM (datacenter)

GET /openmano/{tenant_id}/vim/{datacenter_id}/networks

Get a list of VIM networks.

Params: none

Response: Content-type: application/json

   {
     "networks": [
       {
           "status": "ACTIVE",
           "provider:physical": "macvtap:em1",
           "name": "macvtap:em1",
           "admin_state_up": true,
           "shared": true,
           "type": "bridge_man",
           "id": "7a6c5bae-65d5-11e6-b9c7-0800273e724c"
       },
       {
           "status": "ACTIVE",
           "name": "complex-instance.dataconn1",
           "admin_state_up": true,
           "tenant_id": "8850b260-65d5-11e6-b9c7-0800273e724c",
           "provider:vlan": 3000,
           "shared": false,
           "type": "ptp",
           "id": "8c0e199c-65d5-11e6-b9c7-0800273e724c"
       },
       {
           "status": "ACTIVE",
           "name": "complex2-instance.datanet",
           "admin_state_up": true,
           "tenant_id": "8850b260-65d5-11e6-b9c7-0800273e724c",
           "provider:vlan": 3008,
           "shared": false,
           "type": "data",
           "id": "8d764b7e-65d5-11e6-b9c7-0800273e724c"
       }
     ]
   }

GET /openmano/{tenant_id}/vim/{datacenter_id}/{vim_network_id}

Get details over a VIM network.

Params: none

Response: Content-type: application/json

   {
     "network": {
       "status": "ACTIVE",
       "provider:physical": "openflow:port1/8:vlan",
       "name": "data_net",
       "admin_state_up": true,
       "provider:vlan": 3001,
       "shared": true,
       "type": "data",
       "id": "7ab198cc-65d5-11e6-b9c7-0800273e724c"
     }

}

POST /openmano/{tenant_id}/vim/{datacenter_id}/networks

Add a network at VIM

Params: Content-type: application/json

• name: name of the network
• type: type of network (data, ptp, bridge), To be changed to ETSI notation E-LAN, E-LINE
• shared: available for all tenants or private

   {
       "network":{
           "name": "mynet",
           "type": "data"
       }
   }

Response: Content-type: application/json

{

   "network": {
       "status": "ACTIVE",
       "name": "mynet",
       "admin_state_up": true,
       "tenant_id": "8850b260-65d5-11e6-b9c7-0800273e724c",
       "provider:vlan": 3009,
       "shared": false,
       "type": "data",
       "id": "a8ac819e-65d8-11e6-b9c7-0800273e724c"
   }

}

DELETE /openmano/{tenant_id}/vim/{datacenter_id}/networks/{vim_network_id}

Delete a VIM network

Params: none

Response: Content-type: application/json

   {
     "result": "network e97b7158-65d8-11e6-b9c7-0800273e724c mynet deleted"
   }

VNFs

GET /openmano/{tenant\_id}/vnfs

Get a list of vnfs

Params: none

Response Content-type: application/json

   {
       "vnfs": [
           {
               "description": "VNF1 description",
               "created_at": "2015-08-24T13:41:20",
               "uuid": "09c7209c-4a55-11e5-9f62-5254004aea96",
               "name": "VNF1",
               "path": "/path/to/VNF1.vnfd",
               "public": true,
               "physical": false
           },
           {
               "description": "VNF1 description"",
               "created_at": "2015-09-15T13:22:24",
               "uuid": "09d14bf0-5b9c-11e5-a873-5254004aea96",
               "name": "VNF2",
               "path": "/path/to/VNF2.vnfd",
               "public": true,
               "physical": false
           }
       ]
   }

GET /openmano/{tenant\_id}/vnfs/{vnf_id}

Get vnf details

Params: none

Response

• VNFC: Array of virtual machines which compose the vnf
• External-connections: array of vnf's connections

   * vm_name: name of the internal virtual machine which this connections is connected
   * external_name: name of the conection to show in the interface
   * type: type of connection
   * vpci: Virtual PCI address 
   * bw: bandwidth
   * internal_name: local iface name of the VM 

Content-type: application/json

   {
       "vnf": {
           "VNFC": [
               {
                   "description": "VM 1 in the MultiVM template",
                   "uuid": "09c73a00-4a55-11e5-9f62-5254004aea96",
                   "name": "VM1"
               }
           ],
           "description": "VNF1 description",
           "created_at": "2015-08-24T13:41:20",
           "uuid": "09c7209c-4a55-11e5-9f62-5254004aea96",
           "external-connections": [
               {
                   "vm_name": "VM1",
                   "external_name": "bridge",
                   "uuid": "09c75562-4a55-11e5-9f62-5254004aea96",
                   "type": "bridge",
                   "vpci": null,
                   "bw": null,
                   "internal_name": "eth0",
                   "vm_id": "09c73a00-4a55-11e5-9f62-5254004aea96"
               }
           ],
           "path": "/home/psa/openmano/openmano/vnfrepo/VNF1.vnfd",
           "physical": false,
           "nets": [],
           "public": true,
           "name": "VNF1"
       }
   }

POST /openmano/{tenant\_id}/vnfs

insert a vnf into the catalogue. Creates the flavor and images in the VIM, and creates the VNF and its internal structure in the OPENMANO DB

Params:

See at code /vnfs/vnf-template-2vm.yaml and /vnfs/vnf-template.yaml

• vnf:

   * name (required): vnf name
   * description (optional): vnf description
   * class (optional): Used to organize VNFs 
   * public (optional): boolean 
   * physical (optional): boolean
   * external-connections (required): array of objects. Each one describe a connection that the vnf expose to the outside.
       * name (required): connection name
       * type (required): type of connection. Types availables are: "mgmt","bridge","data"
       * VNFC (required): Name of the internal VM to which this connection is connected. Must match with one of the VM name of the VNF section
       * local\_iface_name (required): interface name of the VM. Must match with one of the interfaces described in the VM description.
       * description (optional): Connection description.
   * internal-connections (optional): Array of objects which describes inner connections between VMs that the vnf contains
       * name (required): inner connection name
       * description (optional): inner connection description
       * type (required): type of connection. Types availables are: "bridge","data","ptp"
       * elements (required): Array of objects. Describes end points of the inner connection
           * VNFC: Name of the internal VM to which this connection is connected. Must match with one of the VM name of the VNF section
           * local\_iface_name: interface name of the VM. Must match with one of the interfaces described in the VM description.
   * VNFC: Array of objects that describes each of the inner VMs. Must contain at least one.
       * name (required): Name of the VM
       * description (optional): Description of the VM
       * VNFC image (required): Path of the image location
       * image metadata (optional)
           * architecture
           * use_incremental: "yes" or "no"
           * vpci:
           * os_distro:
           * os_type:
           * os_version:
           * bus:
       * processor (optional)
           * model (required)
           * features
       * hypervisor
           * type
           * version
       * ram: RAM memory of the VM. Only for traditional cloud VMs. Memory in MBytes (not from hugepages, oversubscription is allowed)
       * vcpus: Only for traditional cloud VMs. Number of virtual CPUs (oversubscription is allowed).
       * disk: disk size in GiB, by default 1
       * numas: Array of numa nodes description
           * memory: memory in GBytes
           * cores | paired-threads | threads (only use one)
               * cores-id (optional): array of integer to specify each core
               * paired-threads-id (optional): Array of paired threads. (i.e:[ [0,1], [2,3], [4,5], [6,7], [8,9] ]) By default follows incremental order
               * threads-id (optional): array of integer to specify each thread
           * interfaces
               * name (required): interface name
               * dedicated (required): available options are "yes"(passthrough), "no"(sriov with vlan tags), "yes:sriov"(sriovi, but exclusive and without vlan tag)
               * bandwidth (required): bandwidth in Mbps or Gbps.
               * vpci (optional): Virtual PCI address  
               * mac_address (optional): avoid this option if possible
       * bridge-ifaces
           * name (required): bridge interface name
           * bandwidth (Optional): Informative only
           * vpci (optional): Virtual PCI address   
           * mac_address (optional): avoid this option if possible
           * model (optional): ("virtio","e1000","ne2k_pci","pcnet","rtl8139") By default, it is automatically filled by libvirt
       * devices: extra devices asigned to the VM. The order determines device letter asignation (hda, hdb, ...)
           * type: ("disk","cdrom","xml")
           * image: path to image
           * image metadata: device image metadata.
               * architecture
               * use_incremental
               * vpci
               * os_distro
               * os_type
               * os_version
               * bus
           * vpci (optional): depending on the device type (not needed for disk or cdrom) 
           * xml:  xml text for XML described devices

Response

Content-type: application/json

DELETE /openmano/{tenant\_id}/vnfs/{vnf_id}

delete a vnf from database, and images and flavors in VIM when appropriate, can use both uuid or name

Params: none

Response

Content-type: application/json

   {
     "result": "VNF 1ec2cdac-6779-11e5-bc4f-5254004aea96 deleted"
   }

POST /openmano/{tenant_id}/topology/verify

Action:

Params:

Response params:

Scenarios===

POST /openmano/{tenant_id}/scenarios

(TBC)

Add a scenario into the catalogue. Creates the scenario and its internal structure in the OPENMANO DB

Params:

see at code /scenarios/scenario-template.yaml

POST /openmano/{tenant\_id}/scenarios/{scenario_id}/action

take an action over a scenario

Params:

• Deploy an scenario: deploy all VNFs of the scenario. Creates a new instance scenario

   * instance_name (required): name of the scenario to deploy
   * description (optional): a description
   * datacenter (optional): name of the datacenter where the scenario will be deployed.

   Content-type: application/json:

       {
           "deploy": {
               "instance_name": "scenario1",
               "description" : "a description...",
               "datacenter" : "mydc"
           }
       }

• Start an scenario: Equivalent to deploy

   * instance_name (required): name of the scenario to start
   * description (optional): a description
   * datacenter (optional): name of the datacenter where the scenario will be started.

   Content-type: application/json:

       {
           "start": {
               "instance_name": "scenario1",
               "description" : "a description...",
               "datacenter" : "mydc"
           }
       }

• Reserve an scenario: Launch a new instance of the scenario without starting virtual machines.

   * instance_name (required): name of the scenario to launch
   * description (optional): a description
   * datacenter (optional): name of the datacenter where the scenario will be launched.

   Content-type: application/json:

       {
           "reserve": {
               "instance_name": "scenario1",
               "description" : "a description...",
               "datacenter" : "mydc"
           }
       }

• Verify an scenario: deploy and destroy an scenario to check that there is room for it.

   * instance_name (required): name of the scenario to verify
   * description (optional): a description
   * datacenter (optional): name of the datacenter where the scenario will be verified.

   Content-type: application/json:

       {
           "verify": {
               "instance_name": "scenario1",
               "description" : "a description...",
               "datacenter" : "mydc"
           }
       }

GET /openmano/{tenant_id}/scenarios

Get a list of existing scenarios for a tenant identified by tenant_id

Params: none

Response Content-type: application/json

   {
     "scenarios": [
       {
         "created_at": "2015-09-15T13:02:07",
         "description": "Scenario1 test",
         "public": false,
         "uuid": "34c4db72-5b99-11e5-a873-5254004aea96",
         "name": "Scenario1"
       },
       {
         "created_at": "2015-09-15T09:49:47",
         "description": "Scenario2 test",
         "public": false,
         "uuid": "5638c64e-5b7e-11e5-a873-5254004aea96",
         "name": "Scenario2"
       }
     ]
   }

GET /openmano/{tenant\_id}/scenarios/{scenario_id}

Get details about a scenario. Can use both uuid or name

Params: none

Response Content-type: application/json

   {
     "scenario": {
       "description": "Pconcepto-x",
       "created_at": "2015-09-15T13:02:07",
       "modified_at": null,
       "name": "Pconcepto-x",
       "vnfs": [
         {
           "vnf_id": "1f3d9aca-5b7e-11e5-a873-5254004aea96",
           "description": "VNF prueba concepto1",
           "interfaces": [
             {
               "sce_net_id": "34c4f26a-5b99-11e5-a873-5254004aea96",
               "uuid": "34c5147a-5b99-11e5-a873-5254004aea96",
               "interface_id": "1f3dce50-5b7e-11e5-a873-5254004aea96"
             }
           ],
           "name": "VNF-pconcepto1",
           "nets": [],
           "vms": [
             {
               "description": "prueba para demo",
               "interfaces": [
                 {
                   "external_name": "bridge",
                   "uuid": "1f3dce50-5b7e-11e5-a873-5254004aea96",
                   "vpci": null,
                   "bw": null,
                   "internal_name": "eth0",
                   "model": null,
                   "type": "bridge",
                   "net_id": null
                 },
                 {
                   "external_name": "eth1",
                   "uuid": "1f3de232-5b7e-11e5-a873-5254004aea96",
                   "vpci": null,
                   "bw": null,
                   "internal_name": "eth1",
                   "model": null,
                   "type": "bridge",
                   "net_id": null
                 }
               ],
               "name": "VMF-pconcepto1",
               "image_id": "bbecf86a-5b7a-11e5-a873-5254004aea96",
               "flavor_id": "09c350f2-4a55-11e5-9f62-5254004aea96",
               "uuid": "1f3db2e4-5b7e-11e5-a873-5254004aea96"
             }
           ],
           "uuid": "34c4fefe-5b99-11e5-a873-5254004aea96"
         }
       ],
       "nfvo_tenant_id": "76094a2a-3c16-11e5-9fb6-5254004aea96",
       "nets": [
         {
           "description": null,
           "vim_id": null,
           "name": "default",
           "external": true,
           "type": "bridge",
           "uuid": "34c4f26a-5b99-11e5-a873-5254004aea96"
         }
       ],
       "public": false,
       "uuid": "34c4db72-5b99-11e5-a873-5254004aea96"
     }
   }

DELETE /openmano/{tenant\_id}/scenarios/{scenario_id}

Delete a scenario from database, can use both uuid or name

Params: none

Response Content-type: application/json

   {
     "result": "Scenario 5638c64e-5b7e-11e5-a873-5254004aea96 Scenario2 deleted"
   }

PUT /openmano/{tenant\_id}/scenarios/{scenario_id}

Edit an existing scenario. Only can be edited the scenario name, scenario description, graphical topology of the VNFs and VNF name and description.

Params:

(TBC)

Response Content-type: application/json

Instances

GET /openmano/{tenant_id}/instances

Get instance list

Params: none

Response Content-type: application/json

   {
     "instances": [
       {
         "created_at": "2015-12-14T09:24:00",
         "scenario_id": "cd4cf84e-5b7a-11e5-a873-5254004aea96",
         "description": "Instance description",
         "uuid": "06e9f0ea-a23c-11e5-bc4f-5254004aea96",
         "name": "Instance 1"
       },
       {
         "created_at": "2015-12-01T12:20:08",
         "scenario_id": "fbcab89a-5dd8-11e5-8018-5254004aea96",
         "description": "Instance description",
         "uuid": "7abd7196-981d-11e5-bc4f-5254004aea96",
         "name": "Instance 2"
       }
     ]
   }

GET /openmano/{tenant\_id}/instances/{instance_id}

get instances details, can use both uuid or name

Params: none

Response Content-type: application/json

   {
     "uuid": "06e9f0ea-a23c-11e5-bc4f-5254004aea96",
     "description": "Instance x description",
     "scenario_id": "cd4cf84e-5b7a-11e5-a873-5254004aea96",
     "datacenter_id": "487c6844-40df-11e5-aaa7-5254004aea96",
     "vnfs": [
       {
         "vnf_name": "VNF1",
         "vnf_id": "bbf04ac4-5b7a-11e5-a873-5254004aea96",
         "uuid": "06ea139a-a23c-11e5-bc4f-5254004aea96",
         "vms": [
           {
             "status": "INACTIVE",
             "uuid": "06ea4aae-a23c-11e5-bc4f-5254004aea96",
             "vim_vm_id": "06e7ca2c-a23c-11e5-92d5-5254004aea96",
             "created_at": "2015-12-14T09:24:00",
             "interfaces": [],
             "name": "VMF1"
           }
         ]
       }
     ],
     "scenario_name": "Scenario x",
     "nfvo_tenant_id": "76094a2a-3c16-11e5-9fb6-5254004aea96",
     "nets": [],
     "created_at": "2015-12-14T09:24:00",
     "name": "Instance x"
   }

DELETE /openmano/{tenant\_id}/instances/{instance_id}

delete instance from VIM and from database, can use both uuid or name

Params: none

Response Content-type: application/json

   {
     "result": "instance c8d1fca2-677c-11e5-bc4f-5254004aea96 deleted"
   }

POST /openmano/{tenant\_id}/instances/{instance_id}/action

take an action over a scenario instance

Params:

Content-type: application/json:

No extra parameters are allowed. For reboot, the "type" is ignored

To start an instance:

   {
       "start": null
   }

To pause an instance:

   {
       "pause": null
   }

To resume an instance:

   {
       "resume": null
   }

To shutoff an instance:

   {
       "shutoff": null
   }

To shutdown an instance:

   {
       "shutdown": null
   }

To forceOff an instance:

   {
       "forceOff": null
   }

To rebuild an instance:

   {
       "rebuild": null
   }

To reboot an instance:

   {
       "reboot": {
           "type": "SOFT"
   }

Miscellaneous

Physicalview

GET /openmano/{tenant_id}/physicalview/{datacenter}

Deprecated

Topology

POST /openmano/{tenant_id}/topology/deploy

Deprecated