Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

DASH pipeline packet flow update proposal. #449

Merged
merged 55 commits into from
Nov 8, 2023
Merged
Show file tree
Hide file tree
Changes from 53 commits
Commits
Show all changes
55 commits
Select commit Hold shift + click to select a range
71e2d66
Packet flow.
r12f Oct 2, 2023
c334aef
Update packet flows.
r12f Oct 3, 2023
bfbc581
minor update.
r12f Oct 3, 2023
74923c9
minor fix.
r12f Oct 3, 2023
d9d016f
Update.
r12f Oct 4, 2023
336971f
Update.
r12f Oct 5, 2023
a21a9a5
update.
r12f Oct 5, 2023
fcf361b
More defined descriptions and examples.
r12f Oct 5, 2023
7d7fe27
more examples.
r12f Oct 5, 2023
16a7237
minor update.
r12f Oct 5, 2023
3500975
Adding packet format section.
r12f Oct 5, 2023
d4535b0
minor update.
r12f Oct 5, 2023
4065dbc
minor update.
r12f Oct 5, 2023
b011179
adding asymmetrical encap.
r12f Oct 5, 2023
ca86bad
Update on conntrack updates and more examples.
r12f Oct 5, 2023
cb45077
Adding placeholder for flow resimulation.
r12f Oct 5, 2023
fca58aa
Update the object schema to avoid confusion with SONiC DASH object.
r12f Oct 5, 2023
3d80636
Making stage more generic.
r12f Oct 6, 2023
d58a7df
More update on pipeline profile.
r12f Oct 6, 2023
c4f3577
adding data path logical architecture stack.
r12f Oct 6, 2023
5c70cf2
minor update on graph.
r12f Oct 6, 2023
567ad10
fix typo and update wordlist
r12f Oct 6, 2023
444db5f
adding parameter support for stage transitions.
r12f Oct 7, 2023
f6e07bd
Updating transition type and be more specific on routing type paramet…
r12f Oct 9, 2023
15ff98d
Meter update stage.
r12f Oct 9, 2023
7ece805
spellcheck.
r12f Oct 9, 2023
d353fef
Multi layer chaining.
r12f Oct 9, 2023
76ef307
minor fix.
r12f Oct 9, 2023
a0e5ef1
Stateless decap and stateful decap.
r12f Oct 9, 2023
ae9e2fe
minor fix.
r12f Oct 9, 2023
414675d
Adding routing action definitions.
r12f Oct 9, 2023
8bcca54
fix spellcheck.
r12f Oct 9, 2023
c82c9a2
fix spellcheck.
r12f Oct 9, 2023
83031d7
Adding DSCP and TTL handling (from sonic-dash-hld) and reverse tunnel…
r12f Oct 11, 2023
a71a354
tunnel from encap action.
r12f Oct 11, 2023
133dad6
Adding encap preservation section.
r12f Oct 11, 2023
a753d41
addressing comment.
r12f Oct 11, 2023
56820c0
Update tunnel dscp fields.
r12f Oct 11, 2023
a4f90ac
Adding scale numbers.
r12f Oct 13, 2023
a977e1a
Minor update on the metadata to be SAI compatiable.
r12f Oct 26, 2023
ba3fd81
fix spelling.
r12f Oct 30, 2023
e731789
More update on multi-encap handling.
r12f Oct 30, 2023
304d483
minor update.
r12f Oct 30, 2023
a9083bc
fix spelling.
r12f Oct 30, 2023
745c533
Rename tunnel 1 and tunnel 2 to underlay 1 and underlay 2 per feedback.
r12f Oct 30, 2023
8b612e5
Adding dedicated packet parsing stage.
r12f Oct 31, 2023
08320a8
Update load balancer example with VTEP support.
r12f Oct 31, 2023
de77703
fix spelling.
r12f Nov 1, 2023
8efca3b
Update documentation/general/dash-sai-pipeline-packet-flow.md
r12f Nov 1, 2023
2585c53
Apply suggestions from code review
r12f Nov 1, 2023
18c0497
fix typo.
r12f Nov 1, 2023
79e561d
addressing comments.
r12f Nov 1, 2023
8dac5a9
Apply suggestions from code review
r12f Nov 1, 2023
8f62eb5
Apply suggestions from code review
r12f Nov 3, 2023
c6f43c4
Apply suggestions from code review
r12f Nov 3, 2023
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
16 changes: 16 additions & 0 deletions .wordlist.txt
Original file line number Diff line number Diff line change
Expand Up @@ -90,7 +90,9 @@ conf
CONFDB
confgen
config
configurated
configs
Conntrack
Containerlab
CP
CreatedHalfOpenFlow
Expand Down Expand Up @@ -134,6 +136,9 @@ de
deallocating
Decap
decap
decap'ed
decap'ing
decaps
deliverables
DemoDays
designator
Expand Down Expand Up @@ -199,6 +204,7 @@ DUT's
EasyCLA
ECMP
encap
encaps
ENI
eni
Eni
Expand All @@ -208,6 +214,7 @@ entrypoints
enum
EPUs
EPYC
ethernet
executables
ExpressRoute
failover
Expand Down Expand Up @@ -267,6 +274,7 @@ INET
INIT
Init
initializer
initialization
integrations
integrators
interoperable
Expand Down Expand Up @@ -324,6 +332,7 @@ Makefile
Makefiles
makefiles
MAPs
maprouting
MatchedHalfOpenFlow
MatchedOtherFlow
MatchedTcpFlow
Expand All @@ -346,7 +355,9 @@ MTU
MUX
MUXes
natively
nat
natted
NAT'ing
nb
nd
netdevs
Expand All @@ -358,6 +369,7 @@ noautoconsole
NonSynStateful
NorthBound
Novus
NPL
NPUS
NSG
NSGs
Expand All @@ -367,6 +379,7 @@ NVA
NVidia
nvgre
Nvgre
NvGRE
NVMe
observability
OCP
Expand Down Expand Up @@ -447,6 +460,7 @@ qos
QoS
qos
Radv
recirculation
rdpty
reachability
reconvergence
Expand All @@ -459,6 +473,7 @@ redis
renderer
repo
repos
resimulated
resimulation
responder
Resttapi
Expand Down Expand Up @@ -578,6 +593,7 @@ TcpSynPacket
TDI
Teamd
teardown
techonology
templating
TEP
testbed
Expand Down
239 changes: 239 additions & 0 deletions documentation/dataplane/dash-routing-actions.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,239 @@
# DASH routing actions

As [DASH packet flow HLD](../general/dash-sai-pipeline-packet-flow.md) describes, routing actions are the fundamental building blocks that describe the packet transformations and form the high level scenarios in DASH. And this doc is used to describe the routing action definitions in details.

1. [Overview](#overview)
2. [Stage transition actions](#stage-transition-actions)
1. [Basic stage transition actions](#basic-stage-transition-actions)
1. [`drop` action](#drop-action)
2. [`trap` action](#trap-action)
2. [Matching stage transition actions](#matching-stage-transition-actions)
1. [IP-based stage transition actions](#ip-based-stage-transition-actions)
1. [`lpmrouting` action](#lpmrouting-action)
2. [`maprouting` action](#maprouting-action)
2. [Port-based stage transition actions](#port-based-stage-transition-actions)
1. [`portmaprouting` action](#portmaprouting-action)
3. [Packet transformation actions](#packet-transformation-actions)
1. [`staticencap` action](#staticencap-action)
2. [`tunnel` action](#tunnel-action)
3. [`tunnel_from_encap` action](#tunnel_from_encap-action)
4. [`reverse_tunnel` action](#reverse_tunnel-action)
5. [`4to6` action](#4to6-action)
6. [`6to4` action](#6to4-action)
7. [`nat` action](#nat-action)

## Overview

On high level, there are 2 types of routing actions:

- Packet transformation actions:
- These actions are used to transform the packet header fields, such as modify the packet fields, adding encaps, etc.
- These actions can only be used in the routing types that specified in the `routing_type` field in each match stage entry.
- Stage transition actions:
- These actions are used to describe the stage transitions in the DASH pipeline, such as transit to maprouting stage.
- This actions can only be used in the routing types that specified in the `transition` field in each match stage entry.

For how routing action works, please refer to the ["Routing action and routing types" section in DASH packet flow HLD](../general/dash-sai-pipeline-packet-flow.md#57-routing-actions-and-routing-types).

## Stage transition actions

### Basic stage transition actions

#### `drop` action

- Actions:
- Drop the packet after the entry is matched.

#### `trap` action

- Actions:
- Trap the packet to CPU after the entry is matched.

### Matching stage transition actions

All matching stage transition actions will support the following parameters:

- `default_routing_type`: If no entry is found, use this routing type to route the packet. If `default_routing_type` is not set, the packet will be dropped by default.
- `stage_index`: If there are multiple stage of the same stage type, use this field to specify which stage to transit to. The index is starting from 0 and by default 0.
r12f marked this conversation as resolved.
Show resolved Hide resolved

#### IP-based stage transition actions

All IP-based stage transition actions will support the following parameters:

- `use_src_ip`: Use source IP in routing and mapping stages.
- `ip_mask`: IP mask to apply before matching the entries.

##### `lpmrouting` action

- Actions:
- The packet will be routed to the next LPM routing stage specified by the `stage_index` field.

The port mapping entries can be described as below:
ashutosh-agrawal marked this conversation as resolved.
Show resolved Hide resolved

```json
// Key Format: DASH_SAI_ROUTE_TABLE|<ENI ID>|<Stage Index>|<IP Cidr>
"DASH_SAI_ROUTE_TABLE|123456789012|0|10.0.1.0/24": {
"transition": "some_transition",
"routing_type": "do_somethng",

// Metadata properties ...
}
```

##### `maprouting` action

- Actions:
- The packet will be routed to the next map routing stage specified by the `stage_index` field.

A map routing entry can be described as below:

```json
// Key Format: DASH_VNET_MAPPING_TABLE|<VNET ID>|<Stage Index>|<IP>
"DASH_VNET_MAPPING_TABLE|Vnet1|0|10.0.1.1": {
"transition": "some_transition",
"routing_type": "do_somethng",

// Metadata properties ...
}
```

#### Port-based stage transition actions

##### `portmaprouting` action

- Actions:
- The packet will be routed to the next stage with TCP or UDP port mapping.

The port mapping entries can be described as below:

```json
// Key Format: DASH_SAI_PORT_MAPPING_TABLE|<Port Mapping Id>
"DASH_SAI_PORT_MAPPING_TABLE|portmapping-0": [
// ...
{
"transition": "some_transition",
"routing_type": "do_something",

// Port range to match
"src_port_min": 0,
"src_port_max": 65535,
"dst_port_min": 2000,
"dst_port_max": 2099,

// Metadata properties ...
}
// ...
]
```

## Packet transformation actions

### `staticencap` action

- Metadata parameters:
- `underlay_dip`: Destination IP used in encap.
- `underlay_sip`: Source IP used in encap.
- `encap_type`: Encap type: "nvgre|vxlan"
- `encap_key`: GRE key in NvGRE or VNI in VxLAN.
- `tunnel_dscp_mode`: DSCP handling mode: "preserve|pipe"
- `tunnel_dscp_value`: DSCP value to set in the encap header.
- Actions:
- Enable the underlay encap header based on the encap type.
- Update the underlay encap header with `encap_key`, `underlay_dip`, `underlay_sip`.
- If `underlay_dip` / `underlay_sip` is not set, use the original IP.
r12f marked this conversation as resolved.
Show resolved Hide resolved

### `tunnel` action

- Action parameters:
- `target` = "underlay0|underlay1|underlay2|..."
- Metadata Parameters:
- `(underlay0|underlay1|underlay2|...)_tunnel_id`: The ID of the tunnel we are going to use.
- The definition of the tunnel can be found below.
- The ECMP hash is calculated based on the 5 tuple of the inner-most (overlay) packet.
- `tunnel_dscp_mode`: DSCP handling mode: "preserve|pipe"
- `tunnel_dscp_value`: DSCP value to set in the encap header.
- Actions:
- Enable the encap header based on the target tunnel and encap_type.
- Update the encap information with the `encap_key`, `dip` and `sip`.

A tunnel entry can be described as below:

```json
"DASH_SAI_TUNNEL_TABLE|<TUNNEL_ID>":{
"name": "tunnel-123",
"dips": "100.0.1.1",
"sip": "2.2.2.1",
"encap_type": "vxlan",
"encap_key": 101
}
```

### `tunnel_from_encap` action

- Parameters from action:
- `source`: "underlay0|underlay1|underlay2|..."
- `target`: "underlay0|underlay1|underlay2|..."
- Parameters from metadata:
- `tunnel_from_encap_(underlay0|underlay1|underlay2)_sip`: overrides the source ip in the specified target encap
- `tunnel_from_encap_(underlay0|underlay1|underlay2)_dip`: overrides the destination ip in the specified target encap
- Action:
- Enable the target encap by copying the information from the source encap.
- Copy the DSCP value and TTL value from the source encap.
- When overrides exists, uses the overridden one.

### `reverse_tunnel` action

- Action parameters:
- `target` = "underlay0|underlay1|underlay2|..."
- Metadata Parameters:
- `(underlay0|underlay1|underlay2|...)_tunnel_id`: The ID of the tunnel we are going to use.
- The definition of the tunnel can be found below.
- The ECMP hash is calculated based on the 5 tuple of the inner-most (overlay) packet.
- Actions:
- No packet transformation should be done on the packet.
- When creating the flow, in the reverse flow,
- Enable the encap header based on the target tunnel and encap_type.
- Update the encap information with the `encap_key`, `dip` and `sip`.

The tunnel entry is the same as the one in `tunnel` action.

### `4to6` action

- Metadata parameters:
- `4to6_sip_encoding_value`: "value_bits"
- `4to6_sip_encoding_mask`: "mask_bits"
- `4to6_dip_encoding_value`: "value_bits"
- `4to6_dip_encoding_mask`: "mask_bits"
- Metadata merging in parameter evaluation:
- When same metadata is found during route action parameter evaluation process, value_bits and mask_bits will be reduced into one with following operation:
- new_value_bits = (old_value_bits & !mask_bits) | value_bits
- new_mask_bits = old_mask_bits | mask_bits
- Actions:
- New SIP/DIP v6 = (SIP/DIP v4 & !4to6_sip/dip_encoding_mask) | 4to6_sip/dip_encoding_value.

### `6to4` action

- Metadata parameters:
- `6to4_sip_encoding_value`: "value_bits"
- `6to4_sip_encoding_mask`: "mask_bits"
- `6to4_dip_encoding_value`: "value_bits"
- `6to4_dip_encoding_mask`: "mask_bits"
- Metadata merging in parameter evaluation:
- When same metadata is found during route action parameter evaluation process, value_bits and mask_bits will be reduced into one with following operation:
- new_value_bits = (old_value_bits & !mask_bits) | value_bits
- new_mask_bits = old_mask_bits | mask_bits
- Actions:
- New SIP/DIP = (SIP/DIP v6 with higher bits removed & !6to4_sip/dip_encoding_mask) | 6to4_sip/dip_encoding_value.

### `nat` action

- Metadata parameters:
- `nat_dip` / `nat_sip`: The destination / source IP that we need to update to.
- `nat_dport` / `nat_sport`: The destination / source port that we need to update to.
- `nat_dport_base` / `nat_sport_base`: The destination / source port that we use as the base port for NAT'ing.
- Action:
- `nat` action always works on the overlay (inner most) packet.
- It updates the IP and Port based on the metadata parameters:
- IP will be directly assigned without change.
- Port assignment: `dport/sport = (dport/sport - nat_dport/sport_base) + nat_dport/sport`.
- If IP version doesn’t match, this action will fail and acting as no-op.
Loading