[MidoNet-dev] population of the Mac-learning table - api proposal

Pino de Candia gdecandia at midokura.com
Wed Feb 6 10:55:35 UTC 2013

Hi Rossella, 

thanks for starting this discussion so promptly. 

On Wednesday, February 6, 2013 at 1:34 AM, Rossella Sblendido wrote:

> Hi devs,
> I'd like to start the discussion regarding the population of the Mac-learning table for a bridge using the API. 
> You can have a look at the requirements here (https://trello.com/card/pre-seed-mac-table-via-rest-api/510b93ac787666573800291f/25), I'm copying them at the bottom to facilitate the discussion.
> Here is my proposal:
> API changes:
> We need to have a new DTO to represent the MAC-vPortId association, something like:
>         public class DtoMacPort {
>                 private UUID portId;
>                 private MAC mac;
>                 // getters
>                 // setters
>         }
> A GET against bridges/bridge_id/macPort will return a Collection<DtoMacPort> representing all the entries of the Mac-learning table of the bridge whose id is bridge_id.
Is that actual run-time Mac-table contents at that moment in time? Or is it just the list of pre-seeded DtoMacPort? 
> A PUT of a DtoMacPort object against bridges/bridge_id/macPort will add a new entry to the Mac-learning table, if there's already an entry with the same Mac, this will be overwritten.

PUT does not return a DTO to the client. Therefore there's no way of passing the DTO's URI back to the client (in the HATEOAS style) - the client could use a template to generate the URI, but I don't like that being the only option.

Instead, can we say that the first time the client wants to set the vport for a specific MAC, they do a POST. This will return a DTO that includes the URI of the object, which will be needed for update and deletion. If you do a POST and there's already a mac-port entry for that mac, you get an error.

Subsequently, if the client wants to change a mac's vport, they set the new vport UUID in the dto and PUT it to the server.

If a client does not know if this is the first time the mac's vport has been set (doesn't know whether to use PUT or POST), then they have two options:
- GET as in #1 (lists all the DtoMacPort)
- Do a GET on a template /bridges/bridge_id/macPort/_mac_. We're using templates in other places for similar reasons. The templates are provided inside DTOs (so that we can evolve them). Where should this template be provided?

> A DELETE of a DtoMacPort object against bridges/bridge_id/macPort will remove the entry whose MAC=DtoMacPort.getMac() from the Mac-learning table of the bridge whose id is bridge_id
The DELETE will be against the DtoMacPort.getURI() right? And the URI is probably going to be /bridges/bridge_id/macPort/mac.

However, this has the following consequence, any DTO (even outdated) can be used to DELETE the mac-port entry for that mac.
> Do we need a method to check if a specific MAC is already in the map?
> ZK changes:
> We store the MAC/vPortId association in ZK under:
> bridges/bridge_id/mac_ports/
> We use a ReplicatedMap, whose key is the Mac and value is the UUID of the port. ReplicatedMap as the name says is a map that is stored both in memory and in ZK. We load it when we initialize it and we keep it in sync with ZK.
> In our code any entry (Mac1, inPort1) in the Mac-learning table gets deleted when the flows count whose sourceMac = Mac1  and ingressPort = inPort1 reaches 0. My interpretation of permanent entries is that we don't modify them taking into account the flows count, hopefully I'm not wrong. 
> To make the entry permanent I'd add a boolean in the ReplicatedMap, isPermanent. If isPermanent=true then the entry cannot be removed.
I would hold off on the discussion of the API back-end implementation so we can focus on the API design. The API design is of interest to a wider audience than the back-end implementation, so I would have the latter discussion in a separate thread (and only after the API design has been agreed).

Caveat: I think it's reasonable that during the API design discussion someone says "That API won't work because there's no way the back-end can support it." But it becomes a question of feasibility, not converging on a specific back-end design.

> ------------------------------------------------------------------------------------------------------------------
> Feature description
> The API allows populating the virtual bridge's mac-learning table with permanent entries. This is used to avoid flooding the bridge for use-cases where the vport/mac pairs are known in advance. 
> Core team responsibilities
> - Propose API changes to expose the MAC-learning table for viewing and manipulating.
> - Design ZK changes (should be backward compatible)
> - Implement API server changes and Midolman changes. 
> Integration team responsibilities
> - Modify OpenStack integration to pass OS vport/mac pair information as Mac-table entries at instance launch. 
> GUI/management team
> - Define existing page that need to change (none?)
> - Define new pages - one to display the mac-table contents?
> - Implement the new pages. 
> QA team responsibilities
> - Normal vetting of a software version. The changes are not user-visible because this is an optimization. 
> Schedule
> - Agree on REST API changes by Feb. 11
> - Core team delivers implementation prototype by Feb. 18
> - Core team completes testing by Feb. 25.
> - Integration team completes changes to Grizzly/Diyari by Feb. 25.
> - QA team approves by March 1. 

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.midonet.org/pipermail/midonet-dev/attachments/20130206/5d3cd171/attachment.html>

More information about the MidoNet-dev mailing list