Add hashing model

[sallylsy]

This PR replaces #939

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.

• SONIC ecmp/lag hash contains configuration for selecting packet fields for hash computation. These are set at a global level.

Tree View

Without augment for vendor

module: openconfig-system
  +--rw system
     +--rw oc-hashing:hashing
        +--rw oc-hashing:algorithms
        |  +--rw oc-hashing:vendor
        +--rw oc-hashing:hashing-policies
           +--rw oc-hashing:hashing-policy* [name]
              +--rw oc-hashing:name                -> ../config/name
              +--rw oc-hashing:config
              |  +--rw oc-hashing:name?        string
              |  +--rw oc-hashing:seed?        uint64
              |  +--rw oc-hashing:algorithm?   string
              +--ro oc-hashing:state
              |  +--ro oc-hashing:name?        string
              |  +--ro oc-hashing:seed?        uint64
              |  +--ro oc-hashing:algorithm?   string
              +--rw oc-hashing:hash-field-modes
                 +--rw oc-hashing:config
                 |  +--rw oc-hashing:ingress-interface?   boolean
                 |  +--rw oc-hashing:ip-protocol-type?    boolean
                 +--ro oc-hashing:state
                 |  +--ro oc-hashing:ingress-interface?   boolean
                 |  +--ro oc-hashing:ip-protocol-type?    boolean
                 +--rw oc-hashing:ipv4
                 |  +--rw oc-hashing:config
                 |  |  +--rw oc-hashing:src-addr?   boolean
                 |  |  +--rw oc-hashing:dst-addr?   boolean
                 |  |  +--rw oc-hashing:src-port?   boolean
                 |  |  +--rw oc-hashing:dst-port?   boolean
                 |  +--ro oc-hashing:state
                 |     +--ro oc-hashing:src-addr?   boolean
                 |     +--ro oc-hashing:dst-addr?   boolean
                 |     +--ro oc-hashing:src-port?   boolean
                 |     +--ro oc-hashing:dst-port?   boolean
                 +--rw oc-hashing:ipv6
                    +--rw oc-hashing:config
                    |  +--rw oc-hashing:src-addr?     boolean
                    |  +--rw oc-hashing:dst-addr?     boolean
                    |  +--rw oc-hashing:src-port?     boolean
                    |  +--rw oc-hashing:dst-port?     boolean
                    |  +--rw oc-hashing:flow-label?   boolean
                    +--ro oc-hashing:state
                       +--ro oc-hashing:src-addr?     boolean
                       +--ro oc-hashing:dst-addr?     boolean
                       +--ro oc-hashing:src-port?     boolean
                       +--ro oc-hashing:dst-port?     boolean
                       +--ro oc-hashing:flow-label?   boolean

With augment for vendor

  +--rw system
     +--rw oc-hashing:hashing
        +--rw oc-hashing:algorithms
        |  +--rw oc-hashing:vendor
        |     +--rw google-pins-hashing:broadcom
        |        +--rw google-pins-hashing:broadcom-family
        |           +--ro google-pins-hashing:hashing-algorithms
        |              +--ro google-pins-hashing:hashing-algorithm* [name]
        |                 +--ro google-pins-hashing:name     -> ../state/name
        |                 +--ro google-pins-hashing:state
        |                    +--ro google-pins-hashing:name?          string
        |                    +--ro google-pins-hashing:description?   string
        +--rw oc-hashing:hashing-policies
           +--rw oc-hashing:hashing-policy* [name]
              +--rw oc-hashing:name                -> ../config/name
              +--rw oc-hashing:config
              |  +--rw oc-hashing:name?              string
              |  +--rw oc-hashing:seed?              uint64
              |  +--rw oc-hashing:algorithm?         string
              |  +--rw google-pins-hashing:offset?   uint64
              +--ro oc-hashing:state
              |  +--ro oc-hashing:name?              string
              |  +--ro oc-hashing:seed?              uint64
              |  +--ro oc-hashing:algorithm?         string
              |  +--ro google-pins-hashing:offset?   uint64
              +--rw oc-hashing:hash-field-modes
                 +--rw oc-hashing:config
                 |  +--rw oc-hashing:ingress-interface?   boolean
                 |  +--rw oc-hashing:ip-protocol-type?    boolean
                 +--ro oc-hashing:state
                 |  +--ro oc-hashing:ingress-interface?   boolean
                 |  +--ro oc-hashing:ip-protocol-type?    boolean
                 +--rw oc-hashing:ipv4
                 |  +--rw oc-hashing:config
                 |  |  +--rw oc-hashing:src-addr?   boolean
                 |  |  +--rw oc-hashing:dst-addr?   boolean
                 |  |  +--rw oc-hashing:src-port?   boolean
                 |  |  +--rw oc-hashing:dst-port?   boolean
                 |  +--ro oc-hashing:state
                 |     +--ro oc-hashing:src-addr?   boolean
                 |     +--ro oc-hashing:dst-addr?   boolean
                 |     +--ro oc-hashing:src-port?   boolean
                 |     +--ro oc-hashing:dst-port?   boolean
                 +--rw oc-hashing:ipv6
                    +--rw oc-hashing:config
                    |  +--rw oc-hashing:src-addr?     boolean
                    |  +--rw oc-hashing:dst-addr?     boolean
                    |  +--rw oc-hashing:src-port?     boolean
                    |  +--rw oc-hashing:dst-port?     boolean
                    |  +--rw oc-hashing:flow-label?   boolean
                    +--ro oc-hashing:state
                       +--ro oc-hashing:src-addr?     boolean
                       +--ro oc-hashing:dst-addr?     boolean
                       +--ro oc-hashing:src-port?     boolean
                       +--ro oc-hashing:dst-port?     boolean
                       +--ro oc-hashing:flow-label?   boolean

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:hashing-policies/hashing-policy/name     <-- added
        +--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:hashing-policies/hashing-policy/name     <-- added

[OpenConfigBot]

No major YANG version changes in commit 5c1353e

[OpenConfigBot]

Compatibility Report for commit 10215ae:
✅ pyangbind@88db69c

[dplore]

Note: Added reference in the PR description to include SONIC ecmp/lag hash.

[sallylsy]

A potential alternative is a registered set of identities where common patterns are managed within the repository in a fashion similar to IETF's IANA function. Thus, when a particular behavior is registered in that module, all implementations with that behavior have a common configuration item. Since it would be an identity, vendor augmentation can happen when necessary.

We could specify a container which implementations are expected to augment containing a flat list of yang identities for "hash algorithms". This would be something like a "distributed registry" where the user must resolve which yang files to include in their configuration generation.

OC first introduced this pattern in the pipeline counters with the container at /components/component/integrated-circuit/pipeline-counters/drop/vendor.

Ref: Vendor Counter Guide . (Note there is also a PR in progress with more verbose description of the intent for these pipeline counters)

Hashing algorithms subtree as been updated as per the suggestion

[dplore]

Couple of extra containers recommended to encapsulate all the hashing configurating into '/system/hashing' and to limit the scope of vendor augments to '/system/hashing/algorithms'

[dplore]

LGTM. This was reviewed again in Nov 21, 2023 OC operators meeting without objection. Thank you for the model and all the changes.