Skip to content

APIs

Jump to bottom
peusterm edited this page Nov 1, 2019 · 2 revisions

REST API

The vim-emu REST API endpoint is coded in src/emuvim/rest/rest_api_endpoint.py This REST API is mainly used by the son-cli tools to control a deployed service in vim-emu. This page gives an overview of implemented REST API commands.

Datacenter

/restapi/datacenter

GET

  • Request:
curl -X GET http://127.0.0.1:5001/restapi/datacenter
  • Response
[
    {
        "internalname": "dc2",
        "label": "datacenter2",
        "metadata": {},
        "n_running_containers": 0,
        "switch": "dc2.s1"
    },
    {
        "internalname": "dc3",
        "label": "long_data_center_name3",
        "metadata": {},
        "n_running_containers": 0,
        "switch": "dc3.s1"
    },
    {
        "internalname": "dc1",
        "label": "datacenter1",
        "metadata": {},
        "n_running_containers": 0,
        "switch": "dc1.s1"
    },
    {
        "internalname": "dc4",
        "label": "datacenter4",
        "metadata": {
            "mydata": "we can also add arbitrary metadata to each DC"
        },
        "n_running_containers": 0,
        "switch": "dc4.s1"
    }
]

/restapi/datacenter/<dc_label>

GET

  • Request:
curl -X GET http://127.0.0.1:5001/restapi/datacenter/datacenter1
  • Response
{
    "internalname": "dc1",
    "label": "datacenter1",
    "metadata": {},
    "n_running_containers": 0,
    "switch": "dc1.s1"
}

Compute

/restapi/compute and /restapi/compute/<dc_label>

GET

  • Request:
 curl -X GET http://127.0.0.1:5001/restapi/compute
  • Response
[
    [
        "vnf2",
        {
            "cpu_period": null,
            "cpu_quota": -1,
            "cpu_shares": null,
            "cpuset": null,
            "datacenter": "cvim1",
            "docker_network": "172.17.0.3",
            "flavor_name": "tiny",
            "id": "41a22d8621a9de28f849df07141b491c47842f4b3238080558089e560ed37e42",
            "image": "ubuntu",
            "mem_limit": null,
            "memswap_limit": null,
            "name": "vnf2",
            "network": [
                {
                    "dc_portname": "dc1.s1-eth2",
                    "intf_name": "vnf2-eth0",
                    "ip": "10.0.0.4",
                    "mac": "ba:68:19:2e:f6:f9",
                    "status": "MISSING",
                    "up": false
                }
            ],
            "short_id": "41a22d8621a9",
            "state": {
                "Dead": false,
                "Error": "",
                "ExitCode": 0,
                "FinishedAt": "0001-01-01T00:00:00Z",
                "OOMKilled": false,
                "Paused": false,
                "Pid": 15400,
                "Restarting": false,
                "Running": true,
                "StartedAt": "2017-03-23T15:32:19.127081166Z",
                "Status": "running"
            }
        }
    ],
    [
        "vnf1",
        {
            "cpu_period": null,
            "cpu_quota": -1,
            "cpu_shares": null,
            "cpuset": null,
            "datacenter": "cvim1",
            "docker_network": "172.17.0.2",
            "flavor_name": "tiny",
            "id": "48c52260319bf3142917e0df8301ed38f4ed13f939164448618db027f81e5c2b",
            "image": "ubuntu",
            "mem_limit": null,
            "memswap_limit": null,
            "name": "vnf1",
            "network": [
                {
                    "dc_portname": "dc1.s1-eth1",
                    "intf_name": "vnf1-eth0",
                    "ip": "10.0.0.2",
                    "mac": "7a:ee:4d:0d:3d:fa",
                    "status": "MISSING",
                    "up": false
                }
            ],
            "short_id": "48c52260319b",
            "state": {
                "Dead": false,
                "Error": "",
                "ExitCode": 0,
                "FinishedAt": "0001-01-01T00:00:00Z",
                "OOMKilled": false,
                "Paused": false,
                "Pid": 15200,
                "Restarting": false,
                "Running": true,
                "StartedAt": "2017-03-23T15:30:43.873147835Z",
                "Status": "running"
            }
        }
    ]
]

/restapi/compute/<dc_label>/<compute_name>

GET

  • Request:
curl -X GET http://127.0.0.1:5001/restapi/compute/cvim1/vnf1
  • Response
{
    "cpu_period": null,
    "cpu_quota": -1,
    "cpu_shares": null,
    "cpuset": null,
    "datacenter": "cvim1",
    "docker_network": "172.17.0.2",
    "flavor_name": "tiny",
    "id": "48c52260319bf3142917e0df8301ed38f4ed13f939164448618db027f81e5c2b",
    "image": "ubuntu",
    "mem_limit": null,
    "memswap_limit": null,
    "name": "vnf1",
    "network": [
        {
            "dc_portname": "dc1.s1-eth1",
            "intf_name": "vnf1-eth0",
            "ip": "10.0.0.2",
            "mac": "7a:ee:4d:0d:3d:fa",
            "status": "MISSING",
            "up": false
        }
    ],
    "short_id": "48c52260319b",
    "state": {
        "Dead": false,
        "Error": "",
        "ExitCode": 0,
        "FinishedAt": "0001-01-01T00:00:00Z",
        "OOMKilled": false,
        "Paused": false,
        "Pid": 15200,
        "Restarting": false,
        "Running": true,
        "StartedAt": "2017-03-23T15:30:43.873147835Z",
        "Status": "running"
    }
}

PUT

  • Request:
curl -X PUT http://127.0.0.1:5001/restapi/compute/cvim1/new_vnf -H 'Content-Type: application/json' -d '{"image":"ubuntu:trusty", "network":"(id=input,ip=10.0.0.1/24),(id=output,ip=20.0.0.1/24)"}'
  • Response
{
    "cpu_period": null,
    "cpu_quota": -1,
    "cpu_shares": null,
    "cpuset": null,
    "datacenter": "cvim1",
    "docker_network": "172.17.0.2",
    "flavor_name": "tiny",
    "id": "35bc406b2751531e06e9a39ffc1e296a8f0da8faca898757b59184d1c8fb960c",
    "image": "ubuntu:trusty",
    "mem_limit": null,
    "memswap_limit": null,
    "name": "new_vnf",
    "network": [
        {
            "dc_portname": "dc1.s1-eth1",
            "intf_name": "input",
            "ip": "10.0.0.1",
            "mac": "e2:bf:6e:60:c2:99",
            "status": "OK",
            "up": true
        },
        {
            "dc_portname": "dc1.s1-eth2",
            "intf_name": "output",
            "ip": "20.0.0.1",
            "mac": "ea:85:23:61:7c:0b",
            "status": "OK",
            "up": true
        }
    ],
    "short_id": "35bc406b2751",
    "state": {
        "Dead": false,
        "Error": "",
        "ExitCode": 0,
        "FinishedAt": "0001-01-01T00:00:00Z",
        "OOMKilled": false,
        "Paused": false,
        "Pid": 19229,
        "Restarting": false,
        "Running": true,
        "StartedAt": "2017-03-23T15:57:17.783687765Z",
        "Status": "running"
    }
}

DELETE

  • Request:
curl -X DELETE http://127.0.0.1:5001/restapi/compute/cvim1/vnf1
  • Response
true

/restapi/compute/resources/<dc_label>/<compute_name>

PUT

Control the resource allocation of docker containers, using the same parameters as the docker update command: docker HTTP API

  • methods: PUT

  • parameters: blkio_weight, cpu_period, cpu_quota, cpu_shares, cpuset_cpus, cpuset_mems, mem_limit, mem_reservation, memswap_limit, kernel_memory, restart_policy

  • special parameters: cpu_bw (value between 0 and 1 to indicate the percentage of cpu time allocated to this vnf, cpu_quota is derived from this.)

Network

/restapi/network

Add or remove chains between VNFs. These chain links are implemented as flow entries in the emulated networks' SDN switches.

Actions:

  • PUT
  • DELETE

Parameters:

(can be given as parameters in the URL or as JSON payload)

  • vnf_src_name: VNF name of the source of the link
  • vnf_dst_name: VNF name of the destination of the link
  • vnf_src_interface: VNF interface name of the source of the link
  • vnf_dst_interface: VNF interface name of the destination of the link
  • weight: weight of the link (can be useful for routing calculations)
  • match: OpenFlow match format of the flow entry as string
  • bidirectional: boolean value if the link needs to be implemented from src to dst and back
  • cookie: cookie value, identifier of the flow entry to be installed.
  • priority: integer indicating the priority of the flow entry
  • skip_vlan_tag: boolean to indicate whether a new vlan tag should be created for this chain, and added to the virtual switch port.
  • monitor: boolean to indicate whether a new vlan tag should be created for this chain
  • monitor_placement: 'tx'=place the monitoring flowrule at the beginning of the chain, 'rx'=place at the end of the chain

return: message string indicating if the chain action is successful or not

/restapi/network/d3jsgraph

Actions:

  • GET

return: placement graph in json format, compatible with the 3djs library. The graph describes the connected infrastructure nodes (datacenter and switches) and the deployed VNF nodes.

Monitoring

/restapi/monitor/interface

Monitor the counters of a VNF interface.

Actions:

  • PUT
  • DELETE

Parameters:

(can be given as parameters in the URL or as JSON payload)

  • vnf_name: name of the VNF to be monitored
  • vnf_interface: name of the VNF interface to be monitored
  • metric: [tx_bytes, rx_bytes, tx_packets, rx_packets]

return: message string indicating if the monitor action is successful or not

/restapi/monitor/flow

Monitor the counters of a specific flow.

Actions:

  • PUT
  • DELETE

Parameters:

(can be given as parameters in the URL or as JSON payload)

  • vnf_name: name of the VNF to be monitored
  • vnf_interface: name of the VNF interface to be monitored
  • metric: [tx_bytes, rx_bytes, tx_packets, rx_packets]
  • cookie: specific identifier of flows to monitor

return: message string indicating if the monitor action is successful or not

/restapi/monitor/link

Add or remove flow monitoring on chains between VNFs. These chain links are implemented as flow entries in the networks' SDN switches. The monitoring is an extra flow entry on top of an existing chain, with a specific match (preserving the chaining). The counters of this new monitoring flow are exported.

Actions:

  • PUT
  • DELETE

Parameters:

(can be given as parameters in the URL or as JSON payload)

  • vnf_src_name: VNF name of the source of the link
  • vnf_dst_name: VNF name of the destination of the link
  • vnf_src_interface: VNF interface name of the source of the link
  • vnf_dst_interface: VNF interface name of the destination of the link
  • weight: weight of the link (can be useful for routing calculations)
  • match: OpenFlow match format of the flow entry
  • bidirectional: boolean value if the link needs to be implemented from src to dst and back
  • cookie: cookie value, identifier of the flow entry to be installed.
  • priority: integer indicating the priority of the flow entry
  • skip_vlan_tag: boolean to indicate whether a new vlan tag should be created for this chain
  • monitor: boolean to indicate whether a new vlan tag should be created for this chain
  • monitor_placement: 'tx'=place the monitoring flowrule at the beginning of the chain, 'rx'=place at the end of the chain
  • metric: tx_packet_rate, tx_byte_rate, rx_packet_rate, rx_byte_rate

return: message string indicating if the chain action is successful or not

/restapi/monitor/term

Actions:

  • GET

Parameters:

(can be given as parameters in the URL or as JSON payload)

  • vnf_list: list of the VNF names for which a terminal needs to be started. The xterm window can be forwarded using X11 (see VNF configuration terminal).

return: message string indicating if the chain action is successful or not

Dummy Gatekeeper API

Use the Dummy Gatekeeper's API directly to push a package to the emulator: Repository

Use the SONATA toolset to push a package to the emulator

The REST API of the Dummy Gatekeeper can be used to deploy a SONATA service package. The son-access tool has a feature to push a SONATA service package either to a SONATA MANO platform or to the vim-emu emulator in the SDK environment. To push a package to the emulator:

  1. Initialize a workspace: son-workspace --init

  2. Add a configuration entry for the emulator by providing the Dummy Gatekeeper URL:
    son-access config --platform_id emu --new --url http://127.0.0.1:5000 --default

  3. Push the package: son-access -p emu push --upload sonata-service.son

  4. Deploy the latest pushed package: son-access -p emu push --deploy latest
    This last step can be omitted if the Dummy Gatekeeper is configured to automatically deploy pushed package, see explanation of the auto_deploy flag here.

Clone this wiki locally