Honeycomb/VBD API

This document outlines the supported operations for managing Virtual Bridge Domains (VBD) on netconf-mounted honeycomb VPP nodes. Currently, the implementation supports the following operations:

• Creating new VBDs
• Adding netconf-mounted nodes to a VBD
• Creating vxlan tunnels between VPP nodes to create a full-mesh network topology
• Creating interfaces on VPP nodes to support vxlan tunnels
• Adding created vxlan tunnel interfaces to a VBD
• Creating termination points to represent created interfaces
• Creating links to represent vxlan tunnels
• Creating VBDs backed by VLAN provider networks

The only requirement for the user is to create new VBDs and then to add nodes to it. All the other operations are used internally by the implementation to set up the infrastructure and state necessary to support and interact with the VBD.

The steps to create a functional VBD are as follows:

1. Mount nodes via netconf
2. Create a new VBD
3. Add netconf-mounted nodes to the VBD topology

This article won't cover mounting nodes via netconf, as that is out of scope, so let's just move right into creating a VBD.

Network types supported by VBD

Currently, VBD allows the creation of virtual bridge domains which are backed by either VXLAN tunnels, or a VLAN provider network. For users of VBD, they are very similar in their creation and configuration, with only a few extra fields required for VLAN provider networks. We'll cover these differences in the section on VLAN provider network VBDs below.

Creating a new VXLAN-based Virtual Bridge Domain

To create a new VBD, you must create a new topology in the controller's datastore with vbridge-topology as the topology type. You must also provide a name for the new VBD, as well as a VNI to use for vxlan tunneling. There are also several other options which can be configured for the new VBD, which you can find in the example below.

The easiest way to get the data into the controller's datastore is via RESTCONF. You can make a request like this:

PUT  http://localhost:8181/restconf/config/network-topology:network-topology/topology/testBD

With this as the request body:

{
   "topology": [
       {
           "topology-id": "testBD",
           "topology-types": {
               "vbridge-topology:vbridge-topology": {}
           },
           "vbridge-topology:tunnel-type": "vxlan-tunnel:tunnel-type-vxlan",
           "vbridge-topology:flood": "true",
           "vbridge-topology:forward": "true",
           "vbridge-topology:learn": "true",
           "vbridge-topology:unknown-unicast-flood": "true",
           "vbridge-topology:arp-termination": "false",
           "vxlan-tunnel:vni": "17"
       }
   ]
}

Make sure that the topology id field and the last segment of the request URL match.

Now that you have a new VBD, we can add a node to it.

Adding nodes to the new virtual bridge domain

To add a node to the VBD, you must add it to the network topology which we created above. Then the implementation will configure the node and add it to the VBD.

Adding a node to the topology is again easiest to do over RESTCONF. The request looks like this:

PUT http://localhost:8181/restconf/config/network-topology:network-topology/network-topology:topology/testBD/node/node0

With this as the request body:

{
   "node": 
   {
       "node-id": "node0",
       "supporting-node": [
           {
               "topology-ref": "topology-netconf",
               "node-ref": "hcmount0"
           }
       ]
   }
}

There are some constraints on this requests body:

1. The node-id field should match the last segment of the request URL
2. The third to last segment of the URL (testBD in the above example) should match the id of the VBD which was created
3. The topology-ref field should contain the id of the netconf topology which was created
4. The node-ref field should contain the id of the netconf mount which is to back this node

Once at least two nodes are added to the VBD topology, vxlan tunnels will be set up automatically to create a full-mesh network between the VPP nodes.

You can then verify that the VBD was created by looking at the controller's operational store as follows:

GET   http://localhost:8181/restconf/operational/network-topology:network-topology/topology/testBD

And you can see the created VBD, the termination points and supporting interfaces, and the links between the nodes:

{
 "topology": [
   {
     "topology-id": "testBD",
     "topology-types": {
       "vbridge-topology:vbridge-topology": {}
     },
     "node": [
       {
         "node-id": "node0",
         "vbridge-topology:bridge-member": {
           "supporting-bridge-domain": "v3po:vpp/bridge-domains/bridge-domain/testBD"
         },
         "termination-point": [
           {
             "tp-id": "vxlan_tunnel0",
             "vbridge-topology:tunnel-interface": "vxlan_tunnel0"
           }
         ]
       },
       {
         "node-id": "node1",
         "vbridge-topology:bridge-member": {
           "supporting-bridge-domain": "v3po:vpp/bridge-domains/bridge-domain/testBD"
         },
         "termination-point": [
           {
             "tp-id": "vxlan_tunnel0",
             "vbridge-topology:tunnel-interface": "vxlan_tunnel0"
           }
         ]
       }
     ],
     "link": [
       {
         "link-id": "node0-node1",
         "destination": {
           "dest-node": "node1",
           "dest-tp": "vxlan_tunnel0"
         },
         "source": {
           "source-tp": "vxlan_tunnel0",
           "source-node": "node0"
         },
         "vbridge-topology:tunnel": "vxlan_tunnel0"
       },
       {
         "link-id": "node1-node0",
         "destination": {
           "dest-node": "node0",
           "dest-tp": "vxlan_tunnel0"
         },
         "source": {
           "source-tp": "vxlan_tunnel0",
           "source-node": "node1"
         },
         "vbridge-topology:tunnel": "vxlan_tunnel0"
       }
     ]
   }
 ]
}

Adding interfaces to the Virtual Bridge Domain

In order to actually add a VPP interface to the VBD, you must create a new termination point which represents the interface under the node which was created in the above step.

To create this termination point, you can make a request like this:

PUT <TODO>

With this as the body:

 <TODO>

Once you have successfully added the termination point to the node, VBD will add the corresponding VPP interface to the correct virtual bridge domain.

Verifying successful virtual bridge domain creation and configuration

The easiest way to verify that the virtual bridge domain has been created successfully is to use the VPP CLI:

<TODO>

Here you can see that we have a new (VXLAN-based) virtual bridge domain, with no interfaces added to it. We'll add a pair of nodes into the virtual bridge domain as well as termination points to represent the bridged interfaces on each node:

<TODO>

You can verify that VBD has correctly configured the virtual bridge domain on the node by checking the VPP CLI:

 <TODO>

As you can see, we now have a virtual bridge domain which contains the specified interfaces.

Since this is a bridge domain backed by VXLAN tunnels, we can check that the tunnel interfaces were also properly created and configured via the VPP CLI as well:

<TODO>

Using VBD on VLAN Provider Networks

VBD also supports the creation of virtual bridge domains on top of VLAN provider networks. The creation of the VBD topology itself is slightly different, and there is an additional field required for nodes which are to be part of the virtual bridge domain.

Creating a VLAN-based Virtual Bridge Domain

<TODO>

Adding nodes to the Virtual Bridge Domain

<TODO>