Skip to content

Commit aea14df

Browse files
Merge pull request #13 from att/doc-updates
Doc updates
2 parents 922b8be + 77e4a65 commit aea14df

File tree

3 files changed

+104
-0
lines changed

3 files changed

+104
-0
lines changed

doc/APIVersioning.md

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
# OpenOffload API Versioning
2+
3+
## Introduction
4+
OpenOffload follows a similar versioning model for its gRPC API as Kubernetes, see Reference 1. The intent is to enable the evolution of the OpenOffload API while enabling developers of OpenOffload devices to have a stable APi to develop and deliver against.
5+
6+
The naming convention will be as follows:
7+
8+
**Alpha** /openoffload/v1/alpha1, this would be the first alpha of API version 1.
9+
10+
**Beta** /openoffload/v1/beta1, this would be the first beta of API version 1
11+
12+
**Release** /openoffload/v1, this would be the released and supported of API version 1
13+
14+
## Mapping to Product Release Versions
15+
OpenOffload device developers are free to select any released version for their product. They are not required to use the most current version just the version that has the necessary features for their product.
16+
17+
## Version Definitions
18+
19+
### Alpha Version
20+
Alpha versions are by definition unstable and the API definitions can change between versions.
21+
- No guarentees of API stability (minimal testing)
22+
- No guarentees features will be supported moving forward.
23+
- Goal of Alpha is to solicit feedback, which may result in significant changes to API.
24+
### Beta Version
25+
Beta verions have been tested and the API/features reviewed.
26+
- A Beta version implies that the API/Features will be delivered.
27+
- Only minor changes (bug fixes) to the API/Feature will be committed.
28+
### Release Version
29+
Released versions will be supported for a specific period or time (or number of release versions).
30+
- Released versions will never change the interface, bugs will be fixed and the versions will be incremented.
31+
- Release versions will always be backwards compatible.
32+
- No Methods will be removed.
33+
- No fields will be removed only added.
34+
35+
## References
36+
37+
1. [Kubernetes API and Versioning](https://kubernetes.io/docs/concepts/overview/kubernetes-api/)
38+
39+
40+
## Todo
41+
- [ ] Define the support timeframe for released APIs
42+
- [ ] Bug fixing strategy and versioning

doc/GeneveOpenOffload.md

Lines changed: 62 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,62 @@
1+
# Draft Open Offload Geneve Format
2+
3+
## Problem Statement
4+
The goal is to steer traffic to a network function that supports OpenOffload from a network element without requiring the network function to paticipate in dynamic routing in a service provider network. The apporach selected is to encapsulate the original packet and deliver it to the network function using a UDP tunneling protocol.
5+
6+
This approach preserves the original source/destination in the inner packet. The ingress and egress interfaces on the router/switch are also included in the metadata. This enables the application of policy or other network function logic on the original packet/session.
7+
8+
## Requirements
9+
Requirements for the tunneling protocol
10+
1. The encapsulation protocol SHOULD be an IETF standard.
11+
2. The encapsulation protocol MUST enable the inner flows to be delivered to the firewall unchanged for classification and inspection.
12+
3. The encapsulation protocol SHOULD be defined as a fixed header format to make inspection efficient by software and hardware.
13+
4. The encapsulation protocol SHOULD have an identifier to enable the firewall to identify that it is a specific encapsulation format.
14+
5. The encapsulation protocol MUST be extensible to carry additional metadata such as zone information (ingress/egress interface).
15+
6. The encapsulation protocol MUST support IPV6 and IPV4.
16+
17+
## Discussion
18+
Three possibilities for the encapsulation format were considered.
19+
20+
### VXLAN
21+
VXLAN while a popular standard does not have any extension mechanisms, VXLAN-GPE is designed to enable other embedded protocols, the only one currently defined is VXLAN-GPE with NSH. NSH is designed for service chaining and as such is fairly complex.
22+
23+
### Geneve
24+
Geneve is another option, it is designed to be a flexible protocol with the ability to register a fixed format with ICAN. Its extensibility allows the definition of a new protocol while using a standard header and well known port. The extensions can be registered with ICAN to identify a specific set of extensions.
25+
26+
### Custom Protocol
27+
A custom protocol was considered and evaluated but after developing it, there were not a lot of differences between the custom protocol and the Geneve extensions. The custom protocol could have used fewer bits, but the required information required was the same.
28+
29+
## Comparisons
30+
While all three approaches would work, VXLAN-GPE was discarded as it would have required defining a new embedded protocol or trying to make NSH work. The custom protocol is more compact but had a similar disadvantage of defining a new proprietary protocol. Geneve was selected as it was sufficiently expressive and the format could be fixed to make it simpler for hardware to process
31+
32+
## Proposed Geneve Format
33+
This section describes the proposed Geneve header for OpenOffload. The standard Geneve header fields are not defined here as they are already well defined in Reference 1.
34+
35+
The diagram below shows the proposed format for the fixed length Geneve Header. There are 96 bits of option fields defined.
36+
37+
![](images/geneve_openoffoad.png)
38+
39+
The fields are as follows:
40+
41+
**In-LIF:** A 32 identifier defining the logical interface for incoming traffic. This value is set by the transmitting network element. The receiver of the encapsulated packet uses the identifier to map to a policy element to be applied to the packet.
42+
43+
**Out-LIF:** A 32 identifier defining the logical interface for outgoing traffic. This value is set by the transmitting network element. The receiver of the encapsulated packet uses the identifier to map to a policy element to be applied to the packet.
44+
45+
**Hardware Opaque Key:** This a unique 32 bit hardware key set by the transmitting network element and is not used by the receiving service.
46+
47+
For this Geneve extension there will be a new Option Class requested. The current Option Classes are listed in Reference 2 and the form to request a new Option Class is in Reference 3.
48+
49+
## Optimizations
50+
Geneve has the option of encapsulating the original packet to either include the Ethernet header or exclude it and encapsulate the original packet starting at the IP header. The ability to determine whether the ethernet header is included or not in the inner packet is set by the "Protocol Type" field in the Geneve header. The "Protocol Type" is defined as the by IEEE-802 as documented in Reference 4.
51+
52+
Just encapsulating the packet at the IP header will save 14 bytes, however the choice of implementation is left to the hardware as the cost and complexity of the encapsulation is most likely the highest impact, rather than the bandwidth.
53+
54+
55+
56+
## References
57+
1. Geneve: Generic Network Virtualization Encapsulation
58+
2. IANA Network Virtualization Overlay (NVO3) Assignments
59+
3. Form to Request an Assignment from IANA for NVO3
60+
4. [IEEE-802 Numbers](https://www.iana.org/assignments/ieee-802-numbers/ieee-802-numbers.xhtml)
61+
62+

doc/images/geneve_openoffoad.png

40.4 KB
Loading

0 commit comments

Comments
 (0)