From a37378e8d50e074667a55784758790b2929d75a6 Mon Sep 17 00:00:00 2001 From: pedro Date: Thu, 31 Oct 2019 17:09:14 -0300 Subject: [PATCH] Add description field in port forwarding API MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 | 13 ++++++ api-ref/source/v2/parameters.yaml | 7 ++++ .../port-fowarding-create-request.json | 3 +- .../port-fowarding-create-response.json | 1 + .../port-fowarding-list-response.json | 2 + .../port-fowarding-show-response.json | 1 + .../port-fowarding-update-request.json | 3 +- .../port-fowarding-update-response.json | 1 + neutron_lib/api/definitions/__init__.py | 2 + neutron_lib/api/definitions/base.py | 1 + .../api/definitions/fip_pf_description.py | 41 +++++++++++++++++++ ...t_floating_ip_port_forwarding_extension.py | 21 ++++++++++ ...d-in-port-forwarding-9da781b1e38ca858.yaml | 5 +++ 13 files changed, 99 insertions(+), 2 deletions(-) create mode 100644 neutron_lib/api/definitions/fip_pf_description.py create mode 100644 neutron_lib/tests/unit/api/definitions/test_floating_ip_port_forwarding_extension.py create mode 100644 releasenotes/notes/add-description-field-in-port-forwarding-9da781b1e38ca858.yaml diff --git a/api-ref/source/v2/fip-port-forwarding.inc b/api-ref/source/v2/fip-port-forwarding.inc index 887816910..3ec0b861a 100644 --- 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 ---------------- diff --git a/api-ref/source/v2/parameters.yaml b/api-ref/source/v2/parameters.yaml index 82f4effff..309a0c984 100644 --- 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. diff --git 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 index 00c16c5a5..df58c07d0 100644 --- 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" } } diff --git 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 index 360f718b0..2d0df17fc 100644 --- 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" } } diff --git 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 index fa23bec56..6b2fa7576 100644 --- 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" } ] diff --git 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 index 360f718b0..2d0df17fc 100644 --- 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" } } diff --git 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 index 53a54617f..45f7db962 100644 --- 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" } } diff --git 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 index e14fc5df1..096c163d0 100644 --- 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" } } diff --git a/neutron_lib/api/definitions/__init__.py b/neutron_lib/api/definitions/__init__.py index a504a90d4..0f09d85dc 100644 --- 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, diff --git a/neutron_lib/api/definitions/base.py b/neutron_lib/api/definitions/base.py index 5897a3c05..f0e1e56e7 100644 --- 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', diff --git a/neutron_lib/api/definitions/fip_pf_description.py b/neutron_lib/api/definitions/fip_pf_description.py new file mode 100644 index 000000000..1505d4afe --- /dev/null +++ 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 = {} diff --git 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 new file mode 100644 index 000000000..a1b8d2e15 --- /dev/null +++ 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,) diff --git a/releasenotes/notes/add-description-field-in-port-forwarding-9da781b1e38ca858.yaml b/releasenotes/notes/add-description-field-in-port-forwarding-9da781b1e38ca858.yaml new file mode 100644 index 000000000..8d82465f5 --- /dev/null +++ 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. \ No newline at end of file