Add ingress policer to qos overview

[dplore]

Adding documentation on how to use the /qos model to create an ingress policer

[OpenConfigBot]

No major YANG version changes in commit 3f91434

[dplore]

@robshakir ready for your re-review

[LimeHat]

I don't think this is the appropriate way to describe a canonical ingress policer.

While the scheduling typically supports rate-limiting mechanisms, in many implementations, there are separate policer entities (often implemented in HW) that are independent of schedulers; i.e., those are two different mechanisms.

The fake queuing/ingress scheduling approach feels more like a workaround for implementations where true ingress policers are not available (or they never implement "real" ingress scheduling and can perform this config translation into policing in native yang/cli model).
IMO it is fine if you want to describe that use case here, but stating that this is the (only) canonical way severely limits the range of covered scenarios and use cases.

In my view, the clearer approach is to introduce a new hierarchy to be used specifically to define standalone policers (e.g. /qos/policer-policies). This avoids any ambiguity w.r.t fake ingress queuing and allows for better extensibility.

[dplore]

@robshakir Ready for your next review

[robshakir]

Suggested change

	or software to implement in ingress queue. To satisfy the OC schema
	or software to implement in ingress queue. To allow a consistent representation to be used across different architectures

[robshakir]

Not sure what this term field that is set to null is -- the JSON here seems incorrect:

{
  "qos": {
    "classifiers": {
      "classifier": [
        {
          "name": "Dest_A",
          "config": {
            "name": "Dest_A"
          },
          "terms": {
            "term": [
              {
                "id": "foo"
              }
            ]
          }
        }
      ]
    }
  }
}

I suggest that this is generated using pyangbind, ygot, or your-favourite-YANG-thingy -- you can also write it by hand and validate it using something like govalidate (although this needs some maintenance to add some new modules and update the docs).

[robshakir]

FYI, the above JSON validates:

[2:47] robjs@aardvark:oc-tools/validate/govalidate   master ✔                                                                       242d ⚑ ◒  ⍉
▶ ./govalidate -fn foo.json && echo $? 
0

[robshakir]

Same problem here as in classifiers.

[robshakir]

Ditto, same issue w.r.t a list that is being set to null.