Add description field in port forwarding API

Problem Description =================== As users create and update theirs floating ip rules, the reason behind those rules might get lost throughout time. Moreover, in an environment with many people writing rules, it is important to track down the reason behind each one of the rules created/added in a floating IP port forwarding configuration. The addition of a description field would allow operators to determine the reason why a rule was created and help the users to know if the existence of a rule is still reasonable. Proposed Change =============== To address the described scenario, we propose to create a new “description” field in the Neutron’s Floating IP port forwarding rules API JSON. This new field will be a nullable String containing the description/reason why this new port forwarding rule is being created. Change-Id: If98a70011b187d2143a660f1f281ab197d21eb4d Implements: blueprint portforwarding-description Closes-Bug: #1850818
2019-10-31 17:09:14 -03:00 · 2019-10-31 17:09:14 -03:00 · a37378e8d5
commit a37378e8d5
parent 7e95f32e34
13 changed files with 99 additions and 2 deletions
--- a/api-ref/source/v2/fip-port-forwarding.inc
+++ b/api-ref/source/v2/fip-port-forwarding.inc
@ -7,6 +7,14 @@ Floating IPs port forwarding
 Lists, creates, shows details for, updates, and deletes floating IPs port
 forwardings.

+Port forwarding rule description
+=========================================
+
+The ``floating-ip-port-forwarding-description`` extension adds the
+``description`` attribute to the floating IP port forwardings.
+The value of the ``description`` attribute contains a text describing the rule,
+which helps users to manage/find easily theirs rules.
+
 Show port forwarding
 ====================

@ -43,6 +51,7 @@ Response Parameters
   - internal_port: internal_port
   - external_port: external_port
   - protocol: fip_port_forwarding_protocol-body
+   - description: fip_port_forwarding-description

 Response Example
 ----------------
@ -94,6 +103,7 @@ Response Parameters
   - internal_port: internal_port
   - external_port: external_port
   - protocol: fip_port_forwarding_protocol-body
+   - description: fip_port_forwarding-description

 Response Example
 ----------------
@ -171,6 +181,7 @@ Response Parameters
   - internal_port: internal_port
   - external_port: external_port
   - protocol: fip_port_forwarding_protocol-body
+   - description: fip_port_forwarding-description

 Response Example
 ----------------
@ -201,6 +212,7 @@ Request
   - internal_port: internal_port
   - external_port: external_port
   - protocol: fip_port_forwarding_protocol-body
+   - description: fip_port_forwarding-description

 Request Example
 ---------------
@ -220,6 +232,7 @@ Response Parameters
   - internal_port: internal_port
   - external_port: external_port
   - protocol: fip_port_forwarding_protocol-body
+   - description: fip_port_forwarding-description

 Response Example
 ----------------
--- a/api-ref/source/v2/parameters.yaml
+++ b/api-ref/source/v2/parameters.yaml
@ -2528,6 +2528,13 @@ fip_port_forwarding:
  in: body
  required: true
  type: object
+fip_port_forwarding-description:
+  description: |
+    A text describing the rule, which helps users to
+    manage/find easily theirs rules.
+  in: body
+  required: false
+  type: string
 fip_port_forwarding_id-body:
  description: |
    The ID of the floating IP port forwarding.
--- a/api-ref/source/v2/samples/port_forwardings/port-fowarding-create-request.json
+++ b/api-ref/source/v2/samples/port_forwardings/port-fowarding-create-request.json
@ -4,6 +4,7 @@
    "internal_ip_address": "10.0.0.11",
    "internal_port": 25,
    "internal_port_id": "1238be08-a2a8-4b8d-addf-fb5e2250e480",
-    "external_port": 2230
+    "external_port": 2230,
+    "description": "Some description"
  }
 }
--- a/api-ref/source/v2/samples/port_forwardings/port-fowarding-create-response.json
+++ b/api-ref/source/v2/samples/port_forwardings/port-fowarding-create-response.json
@ -5,6 +5,7 @@
    "internal_port": 25,
    "internal_port_id": "1238be08-a2a8-4b8d-addf-fb5e2250e480",
    "external_port": 2230,
+    "description": "Some description",
    "id": "725ade3c-9760-4880-8080-8fc2dbab9acc"
  }
 }
--- a/api-ref/source/v2/samples/port_forwardings/port-fowarding-list-response.json
+++ b/api-ref/source/v2/samples/port_forwardings/port-fowarding-list-response.json
@ -6,6 +6,7 @@
      "internal_port": 25,
      "internal_port_id": "070ef0b2-0175-4299-be5c-01fea8cca522",
      "external_port": 2229,
+      "description": "Some description",
      "id": "1798dc82-c0ed-4b79-b12d-4c3c18f90eb2"
    },
    {
@ -14,6 +15,7 @@
      "internal_port": 25,
      "internal_port_id": "1238be08-a2a8-4b8d-addf-fb5e2250e480",
      "external_port": 2230,
+      "description": "",
      "id": "e0a0274e-4d19-4eab-9e12-9e77a8caf3ea"
    }
  ]
--- a/api-ref/source/v2/samples/port_forwardings/port-fowarding-show-response.json
+++ b/api-ref/source/v2/samples/port_forwardings/port-fowarding-show-response.json
@ -5,6 +5,7 @@
    "internal_port": 25,
    "internal_port_id": "1238be08-a2a8-4b8d-addf-fb5e2250e480",
    "external_port": 2230,
+    "description": "Some description",
    "id": "725ade3c-9760-4880-8080-8fc2dbab9acc"
  }
 }
--- a/api-ref/source/v2/samples/port_forwardings/port-fowarding-update-request.json
+++ b/api-ref/source/v2/samples/port_forwardings/port-fowarding-update-request.json
@ -3,6 +3,7 @@
    "protocol": "udp",
    "internal_port": 37,
    "internal_port_id": "99889dc2-19a7-4edb-b9d0-d2ace8d1e144",
-    "external_port": 1960
+    "external_port": 1960,
+    "description": "Some description"
  }
 }
--- a/api-ref/source/v2/samples/port_forwardings/port-fowarding-update-response.json
+++ b/api-ref/source/v2/samples/port_forwardings/port-fowarding-update-response.json
@ -5,6 +5,7 @@
    "internal_port": 37,
    "internal_port_id": "99889dc2-19a7-4edb-b9d0-d2ace8d1e144",
    "external_port": 1960,
+    "description": "Some description",
    "id": "725ade3c-9760-4880-8080-8fc2dbab9acc"
  }
 }
--- a/neutron_lib/api/definitions/init.py
+++ b/neutron_lib/api/definitions/init.py
@ -39,6 +39,7 @@ from neutron_lib.api.definitions import extraroute
 from neutron_lib.api.definitions import extraroute_atomic
 from neutron_lib.api.definitions import filter_validation
 from neutron_lib.api.definitions import fip64
+from neutron_lib.api.definitions import fip_pf_description
 from neutron_lib.api.definitions import fip_port_details
 from neutron_lib.api.definitions import firewall
 from neutron_lib.api.definitions import firewall_v2
@ -152,6 +153,7 @@ _ALL_API_DEFINITIONS = {
    fip_port_details,
    flavors,
    floating_ip_port_forwarding,
+    fip_pf_description,
    floatingip_autodelete_internal,
    floatingip_pools,
    interconnection,
--- a/neutron_lib/api/definitions/base.py
+++ b/neutron_lib/api/definitions/base.py
@ -102,6 +102,7 @@ KNOWN_EXTENSIONS = (
    'fip-port-details',
    'flavors',
    'floating-ip-port-forwarding',
+    'floating-ip-port-forwarding-description',
    'floatingip-autodelete-internal',
    'floatingip-pools',
    'ip-substring-filtering',
--- a/neutron_lib/api/definitions/fip_pf_description.py
+++ b/neutron_lib/api/definitions/fip_pf_description.py
@ -0,0 +1,41 @@
+#    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 floating_ip_port_forwarding as pfw
+from neutron_lib.db import constants as db_const
+
+DESCRIPTION_FIELD = "description"
+
+ALIAS = 'floating-ip-port-forwarding-description'
+IS_SHIM_EXTENSION = False
+IS_STANDARD_ATTR_EXTENSION = False
+NAME = 'Floating IP Port Forwarding new attribute description'
+DESCRIPTION = 'Add a description field to Port Forwarding rules'
+UPDATED_TIMESTAMP = '2019-11-01T10:00:00-00:00'
+RESOURCE_ATTRIBUTE_MAP = {
+    pfw.COLLECTION_NAME: {
+        DESCRIPTION_FIELD: {'allow_post': True,
+                            'allow_put': True,
+                            'validate': {
+                                'type:string':
+                                    db_const.LONG_DESCRIPTION_FIELD_SIZE},
+                            'is_visible': True,
+                            'is_sort_key': False,
+                            'is_filter': True,
+                            'default': ''}
+    }
+}
+SUB_RESOURCE_ATTRIBUTE_MAP = {}
+ACTION_MAP = {}
+REQUIRED_EXTENSIONS = [pfw.ALIAS]
+OPTIONAL_EXTENSIONS = []
+ACTION_STATUS = {}
--- a/neutron_lib/tests/unit/api/definitions/test_floating_ip_port_forwarding_extension.py
+++ b/neutron_lib/tests/unit/api/definitions/test_floating_ip_port_forwarding_extension.py
@ -0,0 +1,21 @@
+#    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 fip_pf_description as pf_description
+from neutron_lib.api.definitions import floating_ip_port_forwarding as fip_pf
+from neutron_lib.tests.unit.api.definitions import base
+
+
+class FipPortForwardingNameAndDescriptionTestCase(base.DefinitionBaseTestCase):
+    extension_module = pf_description
+    extension_resources = (fip_pf.COLLECTION_NAME,)
+    extension_attributes = (pf_description.DESCRIPTION_FIELD,)
--- a/releasenotes/notes/add-description-field-in-port-forwarding-9da781b1e38ca858.yaml
+++ b/releasenotes/notes/add-description-field-in-port-forwarding-9da781b1e38ca858.yaml
@ -0,0 +1,5 @@
+---
+features:
+  - |
+    Add a new field ``description`` in floating ip portforwardings that
+    can be used to help users to manage/find easily theirs rules.