This repository has been archived by the owner on Mar 31, 2023. It is now read-only.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
[MAC manager] Improve API consistency and impose retry limit #170
[MAC manager] Improve API consistency and impose retry limit #170
Changes from 50 commits
d933b0d
f6316b4
e4b5604
336e499
969841b
55d9c59
677cf6e
449d6e6
5886a77
feb5a20
c5dd021
391ba83
62957d3
935e57f
4d1f37a
ca953ae
00e766c
3f44896
33466fb
a86d141
6f05522
0d23506
7ca5df6
2137d4c
42e4ca5
e30c48c
0b852b2
3c223d9
6ac310e
3d3a0f4
f78c95e
e44d501
d1fc282
1dc52ed
d0745e7
44aef16
325720f
d23fd98
a11ec2e
3b7355d
2d0b7a9
5d4f0b8
a94f372
b81ade7
59f8837
a2c0c5b
6471dbc
9a3217a
3addc2e
485ff9e
d647d13
2200f24
27f8d72
a88e4fa
ec24cf4
60334f2
7aef537
4fbcbaf
a07e2fd
File filter
Filter by extension
Conversations
Jump to
There are no files selected for viewing
MAC Manager Design Specification
Overview
MAC manager is an Alcor microservice which manages the lifecycle of all MAC addresses. Its responsibilities include but not limited to, allocating a unique mac address for a given port, releasing the mac address when not needed, and onboarding a region-specific mac ranges. It interacts with Subnet Manager and Port Manager to allocate mac addresses for gateway ports and customer ports.
Service Requirements
Allocate virtual MAC address for all the tenants/vpcs, e.g., (VPC 1, Port 1) → MAC1
Release (port, MAC) association when a port is released
Guarantee uniqueness of MAC address in region scope. Each region has seperate Alcor controller.
Algorithm with random, but less conflict possibility
Reserved MAC address by IANA should be avoided [1]
Fall back mechanism if there is a conflict among MAC addresses
Allow onboarding a list of MAC ranges for a region
Delete a list of MAC ranges for a region.
APIs to activate and deactivate a MAC address. MAC address has 3 states such as "allocated & activated", "allocated & deactivated", and "free (= not allocated yet)"
Working together with other services including subnet manager and port manager.
Concurrency control mechanism should be provided to process multiple concurrent MAC allocation requests.
REST APIs
API Snapshot
Verify MAC State
GET
/macs/{mac}, /v4/macs/{mac}
mac state [sample]
Create MAC State
POST
/macs, /v4/macs
mac state [sample]
Activate MAC Address
PUT
/macs/{mac}, /v4/macs/{mac}
mac state [sample]
Deactivate MAC Address
PUT
/macs/{mac}, /v4/macs/{mac}
vpc state [sample]
Release MAC State
DELETE
/macs/{mac}, /v4/macs/{mac}
mac state [sample]
Create MAC Range
POST
/macs/range, /v4/macs/range
Oui state [sample]
Change MAC Range
PUT
/macs/range, /v4/macs/range
oui state [sample]
Verify MAC State
GET
/macs/{mac}, /v4/macs/{mac}
MAC state [sample]
Create MAC State
POST
/macs, /v4/macs
MAC state [sample]
Activate MAC Address
PUT
/macs/{mac}, /v4/macs/{mac}
MAC state [sample]
Deactivate MAC Address
PUT
/macs/{mac}, /v4/macs/{mac}
MAC state [sample]
Release MAC State
DELETE
/macs/{mac}, /v4/macs/{mac}
MAC state [sample]
Get MAC Range
GET
/macs/ranges/{rangeid}, /v4/macs/ranges/{rangeid}
MAC range state [sample]
List MAC Ranges
GET
/macs/ranges, /v4/macs/ranges
MAC range states [sample]
Create MAC Range
POST
/macs/ranges, /v4/macs/ranges
MAC range state [sample]
Update MAC Range
PUT
/macs/ranges/{rangeid}, /v4/macs/ranges/{rangeid}
MAC range state [sample]
Delete MAC Range
DELETE
/macs/ranges/{rangeid}, /v4/macs/ranges/{rangeid}
deleted MAC range id [sample]
API Specification
(1) Get/Verify MAC state by MAC address
Method:
GET
Request:
/macs/{mac}, /v4/macs/{mac}
Request Parameter:
@PathVariable String mac
Response: mac state
Normal response codes: 200
Error response codes: 400, 412, 500
Example
(2) Allocate MAC Address for Port
Method:
POST
Request:
"/macs", "/v4/macs"
Request Parameter:
Response:
mac state
Normal response codes: 201
Error response codes: 400, 409, 412, 500, 503
Example
(3) Activate MAC Address
Method:
PUT
Request:
/macsss/{mac}", "/v4/macs/{mac}
/macs/{mac}", "/v4/macs/{mac}
Request Parameter:
@PathVariable String mac
Response:
mac state
Normal response codes: 200
Error response codes: 400, 412, 500
Example
(4) Deactivate MAC Address
Method:
PUT
Request:
/macs/{mac}", "/v4/macs/{mac}
Request Parameter:
@PathVariable String mac
Response:
mac state
Normal response codes: 200
Error response codes: 400, 412, 500
Example
(5) Delete/Release MAC State By MAC Address
Method:
DELETE
Request:
/macs/{mac}", "/v4/macs/{mac}
Request Parameter:
@PathVariable String mac
Response:
mac state
Response: deleted MAC address
Normal response codes: 200
Error response codes: 400, 412, 500
Example
(6) Get MAC Range by MAC Range Id
Method:
GET
Request:
/macs/ranges/{rangeid}, /v4/macs/ranges/{rangeid}
Request Parameter:
@PathVariable String rangeid
Response: mac range state
Normal response codes: 200
Error response codes: 400, 412, 500
Example
(6) Onboard MAC Range(7) List All MAC RangesMethod:
POST
GET
Request:
/macs/range
Request:
/macs/ranges, /v4/macs/ranges
Request Parameter:
Response:
mac range state listmac range state
Normal response codes:
201200Error response codes: 400,
409, 412, 500, 503412, 500Example
(8) Onboard MAC Range
Method:
POST
Request:
/macs/ranges
Request Parameter:
Response:
mac range state
Normal response codes: 201
Error response codes: 400, 409, 412, 500, 503
Example
(9) Update MAC Range
Method:
PUT
Request:
/macs/ranges/rangeid
Request Parameter:
Response:
mac range state
Normal response codes: 201
Error response codes: 400, 409, 412, 500, 503
Example
(7) Remove MAC Range by Range Id(10) Remove MAC Range by Range IdMethod:
PUT
Method:
DELETE
Request:
/macs/range/range1
/macs/ranges/range1
Request Parameter:
Response:
`mac range state
mac range id
Normal response codes: 200
Error response codes: 400, 412, 500
Example
Database Data Schema
MAC Address State
One MAC address falls into one of three states:
Activated
MAC address is allocated to a port AND it is in use. This is default.
Deactivated
MAC address is allocated to a port AND it is NOT in use.
Free
MAC address is NOT allocated to a port yet.
Active
MAC address is allocated to a port AND it is in use. This is default.
Inactive
MAC address is allocated to a port AND it is NOT in use.
Free
MAC address is NOT allocated to a port yet.
MAC Range
MAC State
Figure 1. MAC data schema
Concurrency Handling
TBD
To handle concurrent MAC allocation requests, the following three things should be considered:
(1) Performance
MAC allocation time per request should be reasonable even if there are multiple simultaneous requests. For this purpose, this system performs MAC creation and MAC allocation processes in parallel using MAC pool as shown in [Figure 1]. In other words, it creates MAC addresses and stores them in MAC pool in advance. When there are MAC allocation requests, MAC pool provides pre-generated MAC addresses. During request processing, MAC creation keeps generating new MAC addresses.
(2) Uniqueness
Allocated MAC addresses should be unique in spite of concurrent MAC allocation requests. MAC manager achieves this goal by checking in two ways. First, it checks MAC address uniqueness when it creates a new MAC address. Second, it confirms the uniqueness when it allocates a MAC to a port. Additionally, MAC allocation is stored in a hash table whose key is MAC address. Therefore, the system can detect duplicated MAC addresses.
(3) Fallback
In case the uniqueness check for MAC address fails, it allocates new MAC addresses to deactivated ports first. If ports are active, it reallocates new MAC addresses to them until the conflict is resolved.
Comparison with OpenStack Neutron
TBD
Neutron creates a random MAC address when it creates port. There are 3 options to create a MAC address.
(1) Non DVR
When network is configured as non-distributed virtual router by default, Neutron uses 6 octets of base MAC address for VIFs. The first 3 octets of the base MAC address will remain unchanged. If the 4th octet is not 00, it will also be used. The other octets will be randomly generated [2].
(2) Distributed virtual router (enable_distributed_routing=True)
Every unique DVR those are instantiated by Neutron uses unique base MAC address, which is called ‘dvr_base_mac’. Similar to non DVR, the first 3 octets are unchanged. If the 4th octet is not 00, it is unchanged. The other octets are randomly generated. The ‘dvr_base_mac’ must be different from ‘base_mac’ to avoid mixing them up with MACs allocated for tenant ports [2].
(3) Static MAC address assigned by admin
When it creates new port, admin can assign MAC address along with other port information using the following option. Only admin can use this option because updating MAC can cause IP address loss [3].
References
[1] https://www.iana.org/assignments/ethernet-numbers/ethernet-numbers.xhtml
[2] https://wiki.openstack.org/wiki/Neutron/DVR_L2_Agent#get_dvr_mac_address_by_host_.28hostname.29
[3] https://specs.openstack.org/openstack/neutron-specs/specs/kilo/mac_addr_update.html