Add hashing model #939

atmanmehta · 2023-08-11T19:43:58Z

Change Scope

Introduce a hashing policy which can used to
- Select an implementation defined algorithm, offset and seed value
- Select which fields in a packet should be used as an input into a hash function for for load balancing
Add hashing-policy to interfaces to allow configuration of which algorithm to use on a per interface basis
Add hashing-policy to /system to allow configuration of an algorithm used by all the ports in an implementation
It is expected that implementations will vary widely in which specific options they support as these are hardware dependent. The goal is to define a what is operationally useful and supported by at least a subset of hardware. Other hardware may offer only partial support or even no support.
This change is backward compatible.

Implementations

Arista EOS - port-channel load-balance - defines a variety of configuration items which are specific to different hardware platforms. They include references to hash policies with attributes including hash polynomials, hash seeds, and hash fields
JunOS - per flow load balancing on hash values has partial support of the configuration. It defines a way to configure a hash seed on some hardware platforms. forwarding-options/hash-key allow configuration of per-prefix and mac address based balancing. There is no support for configuring different hash algorithms nor to configure per interface.
Cisco IOS-XR bundle-hash allows configuring the hash key based on a list of fixed options
- (L3/3-tuple or L4/7-tuple) (L3,L4).
- Single SA/DA pair (IPv4,IPv6) or range (IPv4 only).
- There is no support for configuring different hash algorithms.
Nokia SR Linux system/load-balancing/hash-options allows hash seed and some hash key configuration support. There doesn't appear to be support for configuring different hash algorithms.

Tree view

module: openconfig-hashing
  +--rw policies
     +--rw policy* [name]
        +--rw name                -> ../config/name
        +--rw config
        |  +--rw name?        string
        |  +--rw algorithm?   string
        |  +--rw offset?      uint64
        |  +--rw seed?        uint64
        +--ro state
        |  +--ro name?        string
        |  +--ro algorithm?   string
        |  +--ro offset?      uint64
        |  +--ro seed?        uint64
        +--rw hash-field-modes
           +--rw config
           |  +--rw ipv4?              hash-field-type-ipv4
           |  +--rw ipv6?              hash-field-type-ipv6
           |  +--rw transport-ports?   hash-field-type-transport
           +--ro state
              +--ro ipv4?              hash-field-type-ipv4
              +--ro ipv6?              hash-field-type-ipv6
              +--ro transport-ports?   hash-field-type-transport

module: openconfig-system
  +--rw system
     +--rw config
     |  +--rw hostname?         oc-inet:domain-name
     |  +--rw domain-name?      oc-inet:domain-name
     |  +--rw login-banner?     string
     |  +--rw motd-banner?      string
     |  +--rw hashing-policy?   -> /oc-hashing:policies/policy/name      <-- added
     +--ro state
     |  +--ro hostname?                       oc-inet:domain-name
     |  +--ro domain-name?                    oc-inet:domain-name
     |  +--ro login-banner?                   string
     |  +--ro motd-banner?                    string
     |  +--ro hashing-policy?                 -> /oc-hashing:policies/policy/name.     <-- added
     |  +--ro current-datetime?               oc-yang:date-and-time
     |  +--ro boot-time?                      oc-types:timeticks64
     |  +--ro software-version?               string
     |  +--ro last-configuration-timestamp?   oc-types:timeticks64

module: openconfig-interfaces
  +--rw interfaces
     +--rw interface* [name]
        +--rw name                   -> ../config/name
        +--rw config
        |  +--rw name?                          string
        |  +--rw type                           identityref
        |  +--rw mtu?                           uint16
        |  +--rw loopback-mode?                 oc-opt-types:loopback-mode-type
        |  +--rw hashing-policy?                -> /oc-hashing:policies/policy/name        <--- added
        |  +--rw description?                   string
        |  +--rw enabled?                       boolean
        |  +--rw oc-vlan:tpid?                  identityref
        |  +--rw oc-if-sdn:forwarding-viable?   boolean
        |  +--rw oc-p4rt:id?                    uint32
        +--ro state
        |  +--ro name?                              string
        |  +--ro type                               identityref
        |  +--ro mtu?                               uint16
        |  +--ro loopback-mode?                     oc-opt-types:loopback-mode-type
        |  +--ro hashing-policy?                    -> /oc-hashing:policies/policy/name      <--- added
        |  +--ro description?                       string
        |  +--ro enabled?                           boolean
        |  +--ro ifindex?                           uint32
        |  +--ro admin-status                       enumeration
        |  +--ro oper-status                        enumeration
        |  +--ro last-change?                       oc-types:timeticks64
        |  +--ro logical?                           boolean
        |  +--ro management?                        boolean
        |  +--ro cpu?                               boolean

…and system models to apply the policies for LAG and L3 ECMP.

OpenConfigBot · 2023-08-11T19:46:26Z

Major YANG version changes in commit f3f0110:

Remove trailing space

Add missing quotes

OpenConfigBot · 2023-08-11T19:51:40Z

Compatibility Report for commit f3f0110:
✅ pyangbind@6b85c2b

earies · 2023-08-11T20:04:49Z

Can you provide implementation references as is in the PR template and not delete that section

https://github.com/openconfig/public/blob/master/.github/pull_request_template.md

Especially with respect to configurable algorithms, seeds, policies and the application of these policies to other specific constructs

atmanmehta · 2023-08-11T20:11:35Z

@dplore mentioned he had some implementations references that he would help add here.

dplore · 2023-08-15T01:40:49Z

Moved implementation references to the first comment (description) of this PR.

earies · 2023-08-15T15:37:05Z

Thx for the references @dplore - looking across the implementation references, this PR is appearing to cater to a single implementation by enforcing user-defined hash policies with a superset (looks like some design patterns are off a bit here too w/ nested config/config and state/config containers).

I can't speak for all implementations but it appears various are going to be system wide parameters with only a subset of what is defined in here that is applicable.

Would be curious to hear from @rgwilton, @hellt, @jsterne on this one

jhaas-pfrc · 2023-08-15T18:42:10Z

@earies has already addressed some of my concerns that this is overly platform specific. Subsets of the parameters may be able to be generically modeled, but in many circumstances it seems likely that they'd be platform or even line-card specific. Given OC's dislike of if-feature, there's not a clean way to model such things generically.

A more specific bit of feedback is that the "algorithm" section is likely very implementation specific. "CRC" against what fields of the forwarding keys? What flavor of CRC? Etc.

For such a field, it'd be more likely to be able to be genericized if the type was an identity and it was implementation specific with explicit documentation as to what fields are being impacted.

For scenarios where a given algorithm was common across implementations, standardizing an identity in the base model would be better than multiple flavors of the same.

hellt · 2023-08-15T19:03:59Z

adding @LimeHat

release/models/hashing/openconfig-hashing.yang

nokia1adam · 2023-08-17T18:36:12Z

I agree with most of the comments that have already been made, in particular:

the objects against which the policies can be applied needs to be defined; the model should allow for a system-wide policy that can be potentially be overridden by policies applied on a more granular basis (to specific ports or linecards for example)
use of the groupings from openconfig-packet-match seems wrong for header field selection; @dplore has some better suggestions in his comments
+1 to all the comments that listing all the possible CRC flavors is unnecessary and unmaintainable

Finally, does hashing really deserve its own top-level directory? Doesn't this belong somewhere in the platform or system hierarchy?

…into the hashing-policy-config

…configLinter happy

This reverts commit 67cef07.

dplore · 2023-09-07T02:09:34Z

Thanks for the changes @atmanmehta . They address all the issues so far. I have added this PR to the OC Community meeting agenda and will present there to promote greater visibility.

rszarecki

In addition to all comments I make in-line, considering heavy dependency on INTEGRATED-CIRCUIT (ASIC, NPU) I would suggest that policy shouyld be attachable to:
/components/component/linecard/config/hashing-policy (chassis may have mix of ASICs)
/components/component/integrated-circuit/config/hashing-policy (to fight polarization)

Considering above, perhaps instead of /system/config/hashing-policy we should use /components/component/chassis/config/hashing-policy ?

Then all atachment,but per-ingress-interface, are under /component/components/.... And per-interface I do not see to be widly supported anyway.

release/models/hashing/openconfig-hashing.yang

rszarecki · 2023-09-07T06:09:30Z

release/models/hashing/openconfig-hashing.yang

+            type hash-field-type-transport;
+            description "The transport layer fields that should be used to
+                compute the hash.";
+        }


I would like to see additionaly:
IPv4_in_IPv4 and IPv6-in-IPv4 where each lement is again list of outher and inner fields:
ipv4_ipv4/outherfields/outherfield type hash-field-type-ipv4
ipv4_ipv4/innerfields/innerfield type hash-field-type-ipv4
ipv6_ipv4/outherfields/outherfield/ipv4 hash-field-type-ipv6
ipv6_ipv4/innerfields/innerfield/ipv6 hash-field-type-ipv6

Similiarly fot ip-over-GRE over IPv4/IPv6,
grev4/outherfields/outherfield type hash-field-type-ipv4
grev4/payloads/payload enum(ipv4 ipv6 mpls Eth) // use fields deviend for basic v4,v6,mpls,eth depending on GRE protocol. if not on list
grev6/outherfields/outherfield type hash-field-type-ipv6
grev6/payloads/payload enum(ipv4 ipv6 mpls Eth) // use fields deviend for basic v4,v6,mpls,eth depending on GRE protocol. if not on list

Also for MPLS
mpls/labels - number of labels to use
mpls/base enum bottom XOR top default top
mpls/payloads/payload enum (ipv4 ipv6 PWE3 ipv4_grev4 ipv6_grev6 ipv4_ipv4 ipv6_ipv4 ...)

Also Eth- usefull for PWE3 services or L2 switching devices
eth/fields/fild enum (srcMAC,dstMAC,Vlan-ID, EtherType/payload, ingress_subinterface)
eth/payloads/payload enum ((ipv4 ipv6 PWE3 ipv4_grev4 ipv6_grev6 ipv4_ipv4 ipv6_ipv4 ...)

For this PR we will only introduce the simple field selection which is targeted for gPINS release and is at least partially supported by the referenced implementations in this PR.

It is possible to add additional encapsulations in the future without breaking changes to the model by adding additional leafs to this hashing-inputs grouping. The additional leafs may be added to the public OC model in the future, or they can be vendor augments.

Since there are many constraints in hardware as to which encapsulations may be supported, especially for more complex use cases, we should leave open the option that vendors are expected to augment the model with the specific scenarios they support. These are often custom or one-off items that are not generally available and may also not be formally documented, which is a good reason to use a vendor provided augment. These 'custom' options may also not be very 'configurable'. For example, hardware may support only using a subset of the bits of some fields (ipv6 comes to mind). Which bits are used may not be configurable or even exposed to the user through the model, config or even the SDK. Using a vendor augment, a vendor can expose the ability to turn on or off these capabilities.

release/models/hashing/openconfig-hashing.yang

rszarecki · 2023-09-07T06:37:01Z

release/models/interfaces/openconfig-interfaces.yang

+        description "The hashing policy to be used when hashing packets coming
+            in on the interface.";
+    }
+


I only see that Arista allows for some hash configuration on per ingress interfaces basis. And it is not clear form referenced documentation on which platform/chipset.

The intent here is that this is a list of policies. We'll update the description to not reference 'packets coming in the interface'. gPINS will add support for multiple policies and Arista EOS is an existing implementation

Can you link to the documentation that shows this being configurable per ingress /interface/ please? It's not clear to me that this is widely supported.

Per interface is not widely supported. gPINS plans to add support for this to Sonic. Should we include this leaf in the model or only augment /interfaces in a gPINS/SONIC yang? Please follow up with comments at #959

rszarecki · 2023-09-07T06:57:58Z

There is one more area not explored.
When hash-function output is calculated it is a n-bit value. Say 16-bit. There is a mapping function from 2^16 potential values to N (weighted-)load-balanced forwarding-hops.
This could be 2 stage process with fixed buckets in between (say 1024). So 2^16 is mapped to 1000 bucket which then are mapped to N fwd-nh.
Some implementation alows to interfere with it. 2 simple example would be use 10 LSB of hash output or 10 MSB.

rszarecki · 2023-09-07T07:02:47Z

release/models/hashing/openconfig-hashing.yang

+            type uint64;
+            description
+              "The seed used to initialize the hash algorithm";
+        }


I would ass 2 boolena leafs:
symmetric - ensured that traffic of bi-dir session produce same hash. (e.g. src/dst fields are ordered before feeding hash function)
persistent - ensures that if fwd-nh (e.g. LAG member) fails, flows that was on other members are not re-hashed. only affected flows are re-distributed among remaining fwd-nh.

References to implementation needed for this?

rszarecki · 2023-09-07T07:07:44Z

release/models/hashing/openconfig-hashing.yang

+            description
+              "The seed used to initialize the hash algorithm";
+        }
+


Suggested change

leaf symmetric {

type boolean;

default false;

description

"Hash is sematrical - returns same value regardless of traffic direction of same flow/session. Also regardless of ingress interface";

}

leaf persistent {

type boolean;

default false;

description

"In case of output inteface/forwarding-nh failure/removal, only flows that have used this interface/nexthop are re-hashed";

}

References to implementation needed for this?

release/models/hashing/openconfig-hashing.yang

rszarecki · 2023-09-07T07:15:21Z

The reference to Cisco IOS-XR bundle-hash is wrong. This is just utility that alows execute hash against mocked-up packet and see what is result.
It is not a configuration of hash input not algorithm.

release/models/hashing/openconfig-hashing.yang

robshakir · 2023-09-15T18:10:48Z

release/models/interfaces/openconfig-interfaces.yang

+        description "The hashing policy to be used when hashing packets coming
+            in on the interface.";
+    }
+


Can you link to the documentation that shows this being configurable per ingress /interface/ please? It's not clear to me that this is widely supported.

release/models/system/openconfig-system.yang

release/models/hashing/openconfig-hashing.yang

robshakir · 2023-09-15T18:15:23Z

release/models/hashing/openconfig-hashing.yang

+                    destination addresses in the calculation of the
+                    hash.";
+            }
+            enum TARGET_DEFINED {


How does one test this configuration parameter?

A test would require target specific knowledge to create a test for this particular enum. Use of this enum is expected when the target contains some default or hardcoded selection of fields which are not described by the model.

For example, an asic may select only a portion of the bits in the src and dest ip address fields and port number fields. Which bits are used may not be exposed and may not be configurable by the user, by the NOS or by the ASIC SDK. Yet they are still "target defined" and don't match the other enums presented here.

If a target defined mode isn't available on an implementation, then the implementation should return an UNIMPLEMENTED (12) error.

We can update the description for this enum in #959

Continue the discussion here as desired: https://github.com/openconfig/public/pull/959/files#r1337998777

release/models/hashing/openconfig-hashing.yang

robshakir · 2023-09-15T18:17:07Z

release/models/hashing/openconfig-hashing.yang

+                    the device for calculating the hash.";
+            }
+        }
+        description "The trasport layer fields that should be used to


Suggested change

description "The trasport layer fields that should be used to

description "The transport layer fields that should be used to

dplore · 2023-10-04T17:51:20Z

Please refer to #959 for comments. Closing this PR as it is now stale.

atmanmehta and others added 6 commits September 20, 2022 18:14

Add ETH_400GBASE_PSM4 PMD type to openconfig-transport-types

6dc4d60

Add ETH_400GMSA_PSM4 PMD type to openconfig-transport-types

b91ca2b

Merge branch 'master' into master

103fd41

Update openconfig version

ac7e1fd

Merge branch 'master' of github.com:atmanmehta/public

fa31346

Add hashing model to OC. There will be leaf-refs added to interfaces …

7345700

…and system models to apply the policies for LAG and L3 ECMP.

atmanmehta requested a review from a team as a code owner August 11, 2023 19:43

Merge branch 'master' into master

67e6313

OpenConfigBot added the non-breaking label Aug 11, 2023

atmanmehta added 2 commits August 11, 2023 12:47

Update openconfig-transport-types.yang

02e8937

Remove trailing space

Update openconfig-hashing.yang

6aa5e44

Add missing quotes

atmanmehta added 2 commits August 11, 2023 12:57

Update openconfig-hashing.yang

0d3abf6

Update openconfig-hashing.yang

fc1a625

dplore self-assigned this Aug 11, 2023

dplore reviewed Aug 16, 2023

View reviewed changes

wenovus added 6 commits August 25, 2023 13:58

Trigger Build

54ef11a

Trigger Build

107157e

Trigger Build

3d718b7

Trigger Build

db80ecb

Trigger Build

917fb48

Trigger Build

9f14325

atmanmehta added 2 commits August 25, 2023 13:59

Rebase to master

5eca652

Address hashing model comments

67cef07

atmanmehta requested review from aashaikh and robshakir as code owners August 28, 2023 21:11

atmanmehta and others added 11 commits August 28, 2023 14:11

Merge branch 'openconfig:master' into master

0865108

Remove pyang files

454ef21

Update version for interfaces and system models

5c2fbda

Remove unnecessary list.

8e3df69

Add namespace to leafref path

cd5e0e4

Add description for hashing-policy leaf

1dc0d28

Add typedefs for enums

ed9d2a8

Fix linter errors

827694d

Move the hash-field-modes container from the hashing-inputs grouping …

7dfb276

…into the hashing-policy-config

Move hashing-inputs into it's own config/state container to make Open…

75591df

…configLinter happy

Move hash-field-modes ito the policy tree

f3f0110

atmanmehta requested a review from dplore August 29, 2023 21:59

atmanmehta added a commit to atmanmehta/public that referenced this pull request Aug 31, 2023

Revert changes from PR openconfig#939

a95dd47

This reverts commit 67cef07.

atmanmehta added a commit to atmanmehta/public that referenced this pull request Aug 31, 2023

Revert changes from PR openconfig#939

4bf67d0

This reverts commit 67cef07.

atmanmehta added a commit to atmanmehta/public that referenced this pull request Aug 31, 2023

Revert changes from PR openconfig#939

883fd7b

This reverts commit 67cef07.

atmanmehta added a commit to atmanmehta/public that referenced this pull request Aug 31, 2023

Revert changes from PR openconfig#939

000e949

This reverts commit 67cef07.

atmanmehta added a commit to atmanmehta/public that referenced this pull request Aug 31, 2023

Revert changes from PR openconfig#939

fe6d348

This reverts commit 67cef07.

rszarecki reviewed Sep 7, 2023

View reviewed changes

robshakir requested changes Sep 15, 2023

View reviewed changes

sallylsy mentioned this pull request Sep 21, 2023

Add hashing model #959

Merged

dplore closed this Oct 4, 2023

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add hashing model #939

Add hashing model #939

atmanmehta commented Aug 11, 2023 •

edited by dplore

Loading

OpenConfigBot commented Aug 11, 2023 •

edited

Loading

OpenConfigBot commented Aug 11, 2023 •

edited

Loading

earies commented Aug 11, 2023

atmanmehta commented Aug 11, 2023

dplore commented Aug 15, 2023 •

edited

Loading

earies commented Aug 15, 2023

jhaas-pfrc commented Aug 15, 2023

hellt commented Aug 15, 2023

nokia1adam commented Aug 17, 2023

dplore commented Sep 7, 2023

rszarecki left a comment •

edited

Loading

rszarecki Sep 7, 2023 •

edited

Loading

dplore Sep 13, 2023

rszarecki Sep 7, 2023

dplore Sep 13, 2023

robshakir Sep 15, 2023

dplore Sep 27, 2023

rszarecki commented Sep 7, 2023

rszarecki Sep 7, 2023

dplore Sep 13, 2023

rszarecki Sep 7, 2023

dplore Sep 13, 2023

rszarecki commented Sep 7, 2023 •

edited

Loading

robshakir Sep 15, 2023

robshakir Sep 15, 2023

dplore Sep 27, 2023

dplore Sep 27, 2023

dplore Sep 27, 2023

robshakir Sep 15, 2023

dplore commented Oct 4, 2023

+        leaf symmetric {
+            type boolean;
+            default false;
+            description
+              "Hash is sematrical - returns same value regardless of traffic direction of same flow/session. Also regardless of ingress interface";
+        }
+        leaf persistent {
+            type boolean;
+            default false;
+            description
+              "In case of output inteface/forwarding-nh failure/removal, only flows that have used this interface/nexthop are re-hashed";
+        }

	description "The trasport layer fields that should be used to
	description "The transport layer fields that should be used to

Add hashing model #939

Add hashing model #939

Conversation

atmanmehta commented Aug 11, 2023 • edited by dplore Loading

Change Scope

Implementations

Tree view

OpenConfigBot commented Aug 11, 2023 • edited Loading

OpenConfigBot commented Aug 11, 2023 • edited Loading

earies commented Aug 11, 2023

atmanmehta commented Aug 11, 2023

dplore commented Aug 15, 2023 • edited Loading

earies commented Aug 15, 2023

jhaas-pfrc commented Aug 15, 2023

hellt commented Aug 15, 2023

nokia1adam commented Aug 17, 2023

dplore commented Sep 7, 2023

rszarecki left a comment • edited Loading

Choose a reason for hiding this comment

rszarecki Sep 7, 2023 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

rszarecki commented Sep 7, 2023

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

rszarecki commented Sep 7, 2023 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

dplore commented Oct 4, 2023

atmanmehta commented Aug 11, 2023 •

edited by dplore

Loading

OpenConfigBot commented Aug 11, 2023 •

edited

Loading

OpenConfigBot commented Aug 11, 2023 •

edited

Loading

dplore commented Aug 15, 2023 •

edited

Loading

rszarecki left a comment •

edited

Loading

rszarecki Sep 7, 2023 •

edited

Loading

rszarecki commented Sep 7, 2023 •

edited

Loading