Add API extension definition for QoS minimum pps rule

This patch adds a new API extension definition for QoS minimum
packet rate (pps) rule.

Related-Bug: #1922237
See-Also: https://review.opendev.org/785236
Change-Id: Ia03cebdd030dbfa489bccb3b104e5db71dac0aef

api-ref/source/v2/parameters.yaml

@@ -811,6 +811,12 @@ min_kbps-query:
   in: query
   required: false
   type: integer
+min_kpps-query:
+  description: |
+    Filter the list result by the min kpps (kilo packets per second) value.
+  in: query
+  required: false
+  type: integer
 min_prefixlen-query:
   description: |
     Filter the subnet pool list result by the smallest prefix that can be
@@ -1055,6 +1061,14 @@ qos-rule-direction-query:
   in: query
   required: false
   type: string
+qos-rule-minimum-packet-rate-direction-query:
+  description: |
+    Filter the list result by the direction of the traffic to which the QoS
+    minimum packet rule is applied. Valid values are ``any``, ``egress`` and
+    ``ingress``.
+  in: query
+  required: false
+  type: string
 qos-shared-query:
   description: |
     Filter the QoS policy list result based on whether this policy is shared
@@ -1116,6 +1130,18 @@ qos_minimum_bandwidth_rule-sort_key:
   in: query
   required: false
   type: string
+qos_minimum_packet_rate_rule-sort_key:
+  description: |
+    Sorts by a minimum packet rate rule attribute. You can specify multiple
+    pairs of sort key and sort direction query parameters. The sort keys are
+    limited to:
+
+    - ``direction``
+    - ``id``
+    - ``min_kpps``
+  in: query
+  required: false
+  type: string
 qos_packet_rate_limit_rule-sort_key:
   description: |
     Sorts by a packet rate limit rule attribute. You can specify multiple pairs
@@ -4123,6 +4149,18 @@ min_kbps-response:
   in: body
   required: true
   type: integer
+min_kpps:
+  description: |
+    The minimum kilo (1000) packets per second (kpps) value.
+  in: body
+  required: true
+  type: integer
+min_kpps-response:
+  description: |
+    The minimum kilo (1000) packets per second (kpps) value.
+  in: body
+  required: true
+  type: integer
 min_prefixlen:
   description: |
     The smallest prefix that can be allocated from a
@@ -4144,6 +4182,19 @@ minimum_bandwidth_rules:
   in: body
   required: true
   type: array
+minimum_packet_rate_rule:
+  description: |
+    A ``minimum_packet_rate_rule`` object.
+  in: body
+  required: true
+  type: object
+minimum_packet_rate_rules:
+  description: |
+    A list of ``minimum_packet_rate_rule`` objects associated with
+    the QoS policy.
+  in: body
+  required: true
+  type: array
 mtu:
   description: |
     The maximum transmission unit (MTU) value to
@@ -4887,6 +4938,16 @@ qos-rule-direction-update-response:
   in: body
   required: true
   type: string
+qos-rule-minimum-packet-rate-direction:
+  description: |
+    The direction of the traffic to which the QoS
+    minimum packet rate rule is applied, as seen
+    from the point of view of the ``port``. Valid
+    values are ``any``, ``egress`` and
+    ``ingress``.
+  in: body
+  required: true
+  type: string
 qos-rule-type:
   description: |
     The type of QoS rule.
@@ -4949,6 +5010,12 @@ qos_minimum_bandwidth_rule-id:
   in: body
   required: true
   type: string
+qos_minimum_packet_rate_rule-id:
+  description: |
+    The ID of the QoS minimum packet rate rule.
+  in: body
+  required: true
+  type: string
 qos_network_policy_id-port-response:
   description: |
     The ID of the QoS policy of the network where this port is plugged.

api-ref/source/v2/qos.inc

@@ -981,6 +981,215 @@ Response
 
 There is no body content for the response of a successful DELETE request.
 
+=============================
+QoS minimum packet rate rules
+=============================
+
+Lists, creates, deletes, shows information for, and updates QoS minimum packet
+rate rules.
+
+List minimum packet rate rules for QoS policy
+=============================================
+
+.. rest_method::  GET /v2.0/qos/policies/{policy_id}/minimum_packet_rate_rules
+
+Lists all minimum packet rate rules for a QoS policy.
+
+The list might be empty.
+
+You can control which response parameters are returned by using the
+fields query parameter. For information, see `Filtering and column
+selection <http://specs.openstack.org/openstack/neutron-
+specs/specs/api/networking_general_api_information.html#filtering-
+and-column-selection>`__.
+
+Normal response codes: 200
+
+Error response codes: 401, 404
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - policy_id: qos-policy-id-path
+   - min_kpps: min_kpps-query
+   - id: id-query
+   - direction: qos-rule-minimum-packet-rate-direction-query
+   - sort_dir: sort_dir
+   - sort_key: qos_minimum_packet_rate_rule-sort_key
+
+Response Parameters
+-------------------
+
+.. rest_parameters:: parameters.yaml
+
+   - minimum_packet_rate_rules: minimum_packet_rate_rules
+   - min_kpps: min_kpps-response
+   - id: qos_minimum_packet_rate_rule-id
+   - direction: qos-rule-minimum-packet-rate-direction
+   - tags: tags
+
+Response Example
+----------------
+
+.. literalinclude:: samples/qos/minimum_packet_rate_rules-list-response.json
+   :language: javascript
+
+Create minimum packet rate rule
+===============================
+
+.. rest_method::  POST /v2.0/qos/policies/{policy_id}/minimum_packet_rate_rules
+
+Creates a minimum packet rate rule for a QoS policy.
+
+Normal response codes: 201
+
+Error response codes: 400, 401, 404, 409
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - policy_id: qos-policy-id-path
+   - minimum_packet_rate_rule: minimum_packet_rate_rule
+   - min_kpps: min_kpps
+   - direction: qos-rule-minimum-packet-rate-direction
+
+Request Example
+---------------
+
+.. literalinclude:: samples/qos/minimum_packet_rate_rule-create-request.json
+   :language: javascript
+
+Response Parameters
+-------------------
+
+.. rest_parameters:: parameters.yaml
+
+   - minimum_packet_rate_rule: minimum_packet_rate_rule
+   - min_kpps: min_kpps-response
+   - id: qos_minimum_packet_rate_rule-id
+   - direction: qos-rule-minimum-packet-rate-direction
+   - tags: tags
+
+Response Example
+----------------
+
+.. literalinclude:: samples/qos/minimum_packet_rate_rule-create-response.json
+   :language: javascript
+
+Show minimum packet rate rule details
+=====================================
+
+.. rest_method::  GET /v2.0/qos/policies/{policy_id}/minimum_packet_rate_rules/{rule_id}
+
+Shows details for a minimum packet rate rule for a QoS policy.
+
+Normal response codes: 200
+
+Error response codes: 401, 404
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - policy_id: qos-policy-id-path
+   - rule_id: qos-rule_id
+
+Response Parameters
+-------------------
+
+.. rest_parameters:: parameters.yaml
+
+   - minimum_packet_rate_rule: minimum_packet_rate_rule
+   - min_kpps: min_kpps-response
+   - id: qos_minimum_packet_rate_rule-id
+   - direction: qos-rule-minimum-packet-rate-direction
+   - tags: tags
+
+Response Example
+----------------
+
+.. literalinclude:: samples/qos/minimum_packet_rate_rule-show-response.json
+   :language: javascript
+
+Update minimum packet rate rule
+===============================
+
+.. rest_method::  PUT /v2.0/qos/policies/{policy_id}/minimum_packet_rate_rules/{rule_id}
+
+Updates a minimum packet rate rule for a QoS policy.
+
+If the request is valid, the service returns the ``Accepted (202)``
+response code.
+
+Note that the rule cannot be updated, and the update is rejected with error
+code 501, if there is any bound port referring to the rule via the qos policy.
+
+Normal response codes: 202
+
+Error response codes: 400, 401, 404, 501
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - policy_id: qos-policy-id-path
+   - rule_id: qos-rule_id
+   - minimum_packet_rate_rule: minimum_packet_rate_rule
+   - min_kpps: min_kpps
+
+Request Example
+---------------
+
+.. literalinclude:: samples/qos/minimum_packet_rate_rule-update-request.json
+   :language: javascript
+
+Response Parameters
+-------------------
+
+.. rest_parameters:: parameters.yaml
+
+   - minimum_packet_rate_rule: minimum_packet_rate_rule
+   - min_kpps: min_kpps-response
+   - id: qos_minimum_packet_rate_rule-id
+   - direction: qos-rule-minimum-packet-rate-direction
+   - tags: tags
+
+Response Example
+----------------
+
+.. literalinclude:: samples/qos/minimum_packet_rate_rule-update-response.json
+   :language: javascript
+
+Delete minimum packet rate rule
+===============================
+
+.. rest_method::  DELETE /v2.0/qos/policies/{policy_id}/minimum_packet_rate_rules/{rule_id}
+
+Deletes a minimum packet rate rule for a QoS policy.
+
+Normal response codes: 204
+
+Error response codes: 400, 401, 404
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - policy_id: qos-policy-id-path
+   - rule_id: qos-rule_id
+
+Response
+--------
+
+There is no body content for the response of a successful DELETE request.
+
 ===========================
 QoS packet rate limit rules
 ===========================

api-ref/source/v2/samples/qos/minimum_packet_rate_rule-create-request.json

@@ -0,0 +1,6 @@
+{
+    "minimum_packet_rate_rule": {
+        "min_kpps": 1000,
+        "direction": "any"
+    }
+}

api-ref/source/v2/samples/qos/minimum_packet_rate_rule-create-response.json

@@ -0,0 +1,7 @@
+{
+    "minimum_packet_rate_rule": {
+        "id": "5f126d84-551a-4dcf-bb01-0e9c0df0c793",
+        "min_kpps": 1000,
+        "direction": "any"
+    }
+}

api-ref/source/v2/samples/qos/minimum_packet_rate_rule-show-response.json

@@ -0,0 +1,7 @@
+{
+    "minimum_packet_rate_rule": {
+        "id": "5f126d84-551a-4dcf-bb01-0e9c0df0c793",
+        "min_kpps": 1000,
+        "direction": "egress"
+    }
+}

api-ref/source/v2/samples/qos/minimum_packet_rate_rule-update-request.json

@@ -0,0 +1,5 @@
+{
+    "minimum_packet_rate_rule": {
+        "min_kpps": 2000
+    }
+}

api-ref/source/v2/samples/qos/minimum_packet_rate_rule-update-response.json

@@ -0,0 +1,7 @@
+{
+    "minimum_packet_rate_rule": {
+        "id": "5f126d84-551a-4dcf-bb01-0e9c0df0c794",
+        "min_kpps": 2000,
+        "direction": "any"
+    }
+}

api-ref/source/v2/samples/qos/minimum_packet_rate_rules-list-response.json

@@ -0,0 +1,9 @@
+{
+    "minimum_packet_rate_rules": [
+        {
+            "id": "5f126d84-551a-4dcf-bb01-0e9c0df0c793",
+            "min_kpps": 1000,
+            "direction": "egress"
+        }
+    ]
+  }

neutron_lib/api/definitions/__init__.py

@@ -93,6 +93,7 @@ from neutron_lib.api.definitions import qos_bw_minimum_ingress
 from neutron_lib.api.definitions import qos_default
 from neutron_lib.api.definitions import qos_gateway_ip
 from neutron_lib.api.definitions import qos_port_network_policy
+from neutron_lib.api.definitions import qos_pps_minimum_rule
 from neutron_lib.api.definitions import qos_pps_rule
 from neutron_lib.api.definitions import qos_rule_type_details
 from neutron_lib.api.definitions import qos_rules_alias
@@ -219,6 +220,7 @@ _ALL_API_DEFINITIONS = {
     qos_default,
     qos_gateway_ip,
     qos_port_network_policy,
+    qos_pps_minimum_rule,
     qos_pps_rule,
     qos_rule_type_details,
     qos_rules_alias,

neutron_lib/api/definitions/qos_pps_minimum_rule.py

@@ -0,0 +1,65 @@
+# Copyright (c) 2021 Ericsson Software Technology
+#
+#    Licensed under the Apache License, Version 2.0 (the "License"); you may
+#    not use this file except in compliance with the License. You may obtain
+#    a copy of the License at
+#
+#         http://www.apache.org/licenses/LICENSE-2.0
+#
+#    Unless required by applicable law or agreed to in writing, software
+#    distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+#    WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+#    License for the specific language governing permissions and limitations
+#    under the License.
+
+from neutron_lib.api import converters
+from neutron_lib.api.definitions import qos as qos_apidef
+from neutron_lib import constants
+from neutron_lib.db import constants as db_const
+from neutron_lib.services.qos import constants as qos_constants
+
+
+ALIAS = 'qos-pps-minimum'
+IS_SHIM_EXTENSION = False
+IS_STANDARD_ATTR_EXTENSION = False
+RESOURCE_NAME = 'minimum_packet_rate_rule'
+COLLECTION_NAME = RESOURCE_NAME + 's'
+NAME = 'QoS minimum packet rate rule'
+API_PREFIX = '/' + qos_apidef.ALIAS
+DESCRIPTION = ("Allow to configure QoS minimum packet rate rule.")
+UPDATED_TIMESTAMP = '2021-07-14T10:00:00-00:00'
+RESOURCE_ATTRIBUTE_MAP = {}
+SUB_RESOURCE_ATTRIBUTE_MAP = {
+    COLLECTION_NAME: {
+        'parent': qos_apidef._PARENT,
+        'parameters': {
+            **qos_apidef._QOS_RULE_COMMON_FIELDS,
+            qos_constants.MIN_KPPS: {
+                'allow_post': True,
+                'allow_put': True,
+                'convert_to': converters.convert_to_int,
+                'is_visible': True,
+                'is_filter': True,
+                'is_sort_key': True,
+                'validate': {
+                    'type:range': [0, db_const.DB_INTEGER_MAX_VALUE]}
+            },
+            qos_constants.DIRECTION: {
+                'allow_post': True,
+                'allow_put': False,
+                'is_visible': True,
+                'default': None,
+                'is_filter': True,
+                'is_sort_key': True,
+                'validate': {
+                    'type:values': constants.VALID_DIRECTIONS_AND_ANY,
+                }
+            }
+        }
+    }
+}
+
+ACTION_MAP = {}
+REQUIRED_EXTENSIONS = [qos_apidef.ALIAS]
+OPTIONAL_EXTENSIONS = []
+ACTION_STATUS = {}

neutron_lib/constants.py

@@ -363,6 +363,7 @@ EGRESS_DIRECTION = 'egress'
 # Used only for QoS minimum guaranteed packet rate
 ANY_DIRECTION = 'any'
 VALID_DIRECTIONS = (INGRESS_DIRECTION, EGRESS_DIRECTION)
+VALID_DIRECTIONS_AND_ANY = (ANY_DIRECTION, *VALID_DIRECTIONS)
 
 PROVISIONAL_IPV6_PD_PREFIX = '::/64'
 

neutron_lib/services/qos/constants.py

@@ -30,6 +30,7 @@ DSCP_MARK = "dscp_mark"
 
 # Names of pps rules' attributes
 MAX_KPPS = "max_kpps"
+MIN_KPPS = "min_kpps"
 MAX_BURST_KPPS = "max_burst_kpps"
 
 QOS_POLICY_ID = 'qos_policy_id'

neutron_lib/tests/unit/api/definitions/test_qos_pps_minimum_rule.py

@@ -0,0 +1,26 @@
+# Copyright (c) 2021 Ericsson Software Technology
+#
+#    Licensed under the Apache License, Version 2.0 (the "License"); you may
+#    not use this file except in compliance with the License. You may obtain
+#    a copy of the License at
+#
+#         http://www.apache.org/licenses/LICENSE-2.0
+#
+#    Unless required by applicable law or agreed to in writing, software
+#    distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+#    WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+#    License for the specific language governing permissions and limitations
+#    under the License.
+
+from neutron_lib.api.definitions import qos as qos_apidef
+from neutron_lib.api.definitions import qos_pps_minimum_rule
+from neutron_lib.services.qos import constants as qos_constants
+from neutron_lib.tests.unit.api.definitions import base
+
+
+class QoSPPSMinimumRuleDefinitionTestCase(base.DefinitionBaseTestCase):
+    extension_module = qos_pps_minimum_rule
+
+    extension_resources = (qos_apidef.POLICIES,)
+    extension_subresources = (qos_pps_minimum_rule.COLLECTION_NAME,)
+    extension_attributes = (qos_constants.MIN_KPPS, qos_constants.DIRECTION)

releasenotes/notes/qos-pps-minimum-1f9a5433d7d4fecd.yaml

@@ -0,0 +1,4 @@
+---
+features:
+  - |
+    Added API definition for QoS minimum packet rate rule.