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

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
 ----------------

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.

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"
   }
 }

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"
   }
 }

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"
     }
   ]

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"
   }
 }

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"
   }
 }

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"
   }
 }

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,

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',

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 = {}

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,)

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.