From b7dd86ea0c6857f48010af63941766281b5a4570 Mon Sep 17 00:00:00 2001 From: jimin3-shin Date: Fri, 24 Oct 2025 20:17:25 +0900 Subject: [PATCH] Add information to network ip availabilities The change[0] provides full information on the number of ips in the subnet from the response of GET ``/v2.0/network-ip-availabilites`` - the number of ips in the subnet cidr, in the allocation pools, used ips in the subnet cidr, and used ips in the allocation pools. This change is for adding fields to the api result. [0] https://review.opendev.org/c/openstack/neutron/+/965083 [1] https://review.opendev.org/c/openstack/neutron-specs/+/947826 Related-Bug: #2107316 Change-Id: Ia6e264c8318636f22ae26c60589054944df66542 Signed-off-by: Jimin Shin --- api-ref/source/v2/network-ip-availability.inc | 10 ++++ api-ref/source/v2/parameters.yaml | 13 +++++ .../network-ip-availability-list.json | 56 +++++++++++++++---- .../network-ip-availability-show.json | 26 +++++++-- neutron_lib/api/definitions/__init__.py | 2 + .../network_ip_availability_details.py | 41 ++++++++++++++ .../test_network_ip_availability_details.py | 25 +++++++++ ...-availability-detail-5cb384b0decf347f.yaml | 7 +++ 8 files changed, 166 insertions(+), 14 deletions(-) create mode 100644 neutron_lib/api/definitions/network_ip_availability_details.py create mode 100644 neutron_lib/tests/unit/api/definitions/test_network_ip_availability_details.py create mode 100644 releasenotes/notes/add-extension-network-ip-availability-detail-5cb384b0decf347f.yaml diff --git a/api-ref/source/v2/network-ip-availability.inc b/api-ref/source/v2/network-ip-availability.inc index b555f7f2a..a10ce90c3 100644 --- a/api-ref/source/v2/network-ip-availability.inc +++ b/api-ref/source/v2/network-ip-availability.inc @@ -8,6 +8,14 @@ The extension ``network-ip-availability`` allows users to list and show the network IP usage stats of all networks or of a specified network. By default policy configuration, only administrative users can use this API. +Network IP availability detail +============================== + +The ``network-ip-availability-detail`` extension adds the +``ip_availability_details`` attribute to network IP availabilities. The value +of this attribute contains detailed information about the network IP usage +statistics. + Show Network IP Availability ============================ @@ -43,6 +51,7 @@ Response Parameters - project_id: project_id - total_ips: total_ips - used_ips: used_ips + - ip_availability_details: ip_availability_details - subnet_ip_availability: subnet_ip_availability - subnet_id: network_ip_availability-subnet_id - subnet_name: subnet_name @@ -94,6 +103,7 @@ Response Parameters - project_id: project_id - total_ips: total_ips - used_ips: used_ips + - ip_availability_details: ip_availability_details - subnet_ip_availability: subnet_ip_availability - subnet_id: network_ip_availability-subnet_id - subnet_name: subnet_name diff --git a/api-ref/source/v2/parameters.yaml b/api-ref/source/v2/parameters.yaml index e50870f3d..e68abc0f5 100644 --- a/api-ref/source/v2/parameters.yaml +++ b/api-ref/source/v2/parameters.yaml @@ -4249,6 +4249,19 @@ ip_allocation: in: body required: true type: string +ip_availability_details: + description: | + The detailed information of IP availability for a network. This field + includes the following attributes: ``total_ips_in_subnet`` is the number + of available IPs in the subnet cidr, ``total_ips_in_allocation_pool`` is + the sum of available IPs in each allocation pool (0 if there are no + allocation pools), ``used_ips_in_subnet`` is the number of used IPs in the + subnet (does not consider allocation pools), and + ``used_ips_in_allocation_pool`` is the sum of used IPs in each allocation + pool (0 if there are no allocation pools). + in: body + required: true + type: dict ip_version: description: | The IP protocol version. Valid value is ``4`` or diff --git a/api-ref/source/v2/samples/network-ip-availability/network-ip-availability-list.json b/api-ref/source/v2/samples/network-ip-availability/network-ip-availability-list.json index 80007cbac..6fac354d3 100644 --- a/api-ref/source/v2/samples/network-ip-availability/network-ip-availability-list.json +++ b/api-ref/source/v2/samples/network-ip-availability/network-ip-availability-list.json @@ -9,8 +9,14 @@ "ip_version": 6, "subnet_id": "ca3f46c4-c6ff-4272-9be4-0466f84c6077", "subnet_name": "ipv6-public-subnet", - "total_ips": 18446744073709552000, - "used_ips": 1 + "total_ips": 18446744073709551000, + "used_ips": 1, + "ip_availability_details": { + "total_ips_in_subnet": 18446744073709551616, + "total_ips_in_allocation_pool": 18446744073709551000, + "used_ips_in_subnet": 1, + "used_ips_in_allocation_pool": 1 + } }, { "cidr": "172.24.4.0/24", @@ -18,13 +24,25 @@ "subnet_id": "cc02efc1-9d47-46bd-bab6-760919c836b5", "subnet_name": "public-subnet", "total_ips": 253, - "used_ips": 1 + "used_ips": 1, + "ip_availability_details": { + "total_ips_in_subnet": 254, + "total_ips_in_allocation_pool": 253, + "used_ips_in_subnet": 1, + "used_ips_in_allocation_pool": 1 + } } ], "project_id": "1a02cc95f1734fcc9d3c753818f03002", "tenant_id": "1a02cc95f1734fcc9d3c753818f03002", - "total_ips": 18446744073709552253, - "used_ips": 2 + "total_ips": 18446744073709551253, + "used_ips": 2, + "ip_availability_details": { + "total_ips_in_subnet": 18446744073709551870, + "total_ips_in_allocation_pool": 18446744073709551253, + "used_ips_in_subnet": 2, + "used_ips_in_allocation_pool": 2 + } }, { "network_id": "6801d9c8-20e6-4b27-945d-62499f00002e", @@ -36,21 +54,39 @@ "subnet_id": "44e70d00-80a2-4fb1-ab59-6190595ceb61", "subnet_name": "private-subnet", "total_ips": 253, - "used_ips": 2 + "used_ips": 2, + "ip_availability_details": { + "total_ips_in_subnet": 254, + "total_ips_in_allocation_pool": 253, + "used_ips_in_subnet": 2, + "used_ips_in_allocation_pool": 1 + } }, { "ip_version": 6, "cidr": "fdbf:ac66:9be8::/64", "subnet_id": "a90623df-00e1-4902-a675-40674385d74c", "subnet_name": "ipv6-private-subnet", - "total_ips": 18446744073709552000, - "used_ips": 2 + "total_ips": 18446744073709551000, + "used_ips": 2, + "ip_availability_details": { + "total_ips_in_subnet": 18446744073709551616, + "total_ips_in_allocation_pool": 18446744073709551000, + "used_ips_in_subnet": 2, + "used_ips_in_allocation_pool": 1 + } } ], "project_id": "d56d3b8dd6894a508cf41b96b522328c", "tenant_id": "d56d3b8dd6894a508cf41b96b522328c", - "total_ips": 18446744073709552253, - "used_ips": 4 + "total_ips": 18446744073709551253, + "used_ips": 4, + "ip_availability_details": { + "total_ips_in_subnet": 18446744073709551870, + "total_ips_in_allocation_pool": 18446744073709551253, + "used_ips_in_subnet": 4, + "used_ips_in_allocation_pool": 2 + } } ] } diff --git a/api-ref/source/v2/samples/network-ip-availability/network-ip-availability-show.json b/api-ref/source/v2/samples/network-ip-availability/network-ip-availability-show.json index 026cef6f5..20db07fd2 100644 --- a/api-ref/source/v2/samples/network-ip-availability/network-ip-availability-show.json +++ b/api-ref/source/v2/samples/network-ip-availability/network-ip-availability-show.json @@ -8,7 +8,13 @@ "subnet_name": "private-subnet", "ip_version": 4, "cidr": "10.0.0.0/24", - "total_ips": 253 + "total_ips": 253, + "ip_availability_details": { + "total_ips_in_subnet": 254, + "total_ips_in_allocation_pool": 253, + "used_ips_in_subnet": 2, + "used_ips_in_allocation_pool": 1 + } }, { "used_ips": 2, @@ -16,13 +22,25 @@ "subnet_name": "ipv6-private-subnet", "ip_version": 6, "cidr": "fdbf:ac66:9be8::/64", - "total_ips": 18446744073709552000 + "total_ips": 18446744073709551000, + "ip_availability_details": { + "total_ips_in_subnet": 18446744073709551616, + "total_ips_in_allocation_pool": 18446744073709551000, + "used_ips_in_subnet": 2, + "used_ips_in_allocation_pool": 1 + } } ], "network_id": "6801d9c8-20e6-4b27-945d-62499f00002e", "project_id": "d56d3b8dd6894a508cf41b96b522328c", "tenant_id": "d56d3b8dd6894a508cf41b96b522328c", - "total_ips": 18446744073709552253, - "network_name": "private" + "total_ips": 18446744073709551253, + "network_name": "private", + "ip_availability_details": { + "total_ips_in_subnet": 18446744073709551870, + "total_ips_in_allocation_pool": 18446744073709551253, + "used_ips_in_subnet": 4, + "used_ips_in_allocation_pool": 2 + } } } diff --git a/neutron_lib/api/definitions/__init__.py b/neutron_lib/api/definitions/__init__.py index 15004757c..b95cf9a42 100644 --- a/neutron_lib/api/definitions/__init__.py +++ b/neutron_lib/api/definitions/__init__.py @@ -84,6 +84,7 @@ from neutron_lib.api.definitions import network_availability_zone from neutron_lib.api.definitions import network_cascade_delete from neutron_lib.api.definitions import network_ha from neutron_lib.api.definitions import network_ip_availability +from neutron_lib.api.definitions import network_ip_availability_details from neutron_lib.api.definitions import network_mtu from neutron_lib.api.definitions import network_mtu_writable from neutron_lib.api.definitions import network_segment_range @@ -249,6 +250,7 @@ _ALL_API_DEFINITIONS = { network_cascade_delete, network_ha, network_ip_availability, + network_ip_availability_details, network_mtu, network_mtu_writable, network_segment_range, diff --git a/neutron_lib/api/definitions/network_ip_availability_details.py b/neutron_lib/api/definitions/network_ip_availability_details.py new file mode 100644 index 000000000..85da42d65 --- /dev/null +++ b/neutron_lib/api/definitions/network_ip_availability_details.py @@ -0,0 +1,41 @@ +# Copyright 2025 Samsung SDS. All Rights Reserved +# +# 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 network_ip_availability + + +IP_AVAILABILITY_DETAILS = "ip_availability_details" + +ALIAS = 'network-ip-availability-details' +IS_SHIM_EXTENSION = False +IS_STANDARD_ATTR_EXTENSION = False +NAME = 'Network IP Availability Details Extension' +DESCRIPTION = ('Add ip_availability_details attribute to' + ' network-ip-availabilities resource.') +UPDATED_TIMESTAMP = '2025-10-31T00:00:00-00:00' + +RESOURCE_ATTRIBUTE_MAP = { + network_ip_availability.RESOURCE_PLURAL: { + IP_AVAILABILITY_DETAILS: { + 'allow_post': False, 'allow_put': False, + 'is_visible': True + } + } +} +SUB_RESOURCE_ATTRIBUTE_MAP = {} +ACTION_MAP = {} +REQUIRED_EXTENSIONS = [network_ip_availability.ALIAS] +OPTIONAL_EXTENSIONS = [] +ACTION_STATUS = {} diff --git a/neutron_lib/tests/unit/api/definitions/test_network_ip_availability_details.py b/neutron_lib/tests/unit/api/definitions/test_network_ip_availability_details.py new file mode 100644 index 000000000..e6dd47df9 --- /dev/null +++ b/neutron_lib/tests/unit/api/definitions/test_network_ip_availability_details.py @@ -0,0 +1,25 @@ +# Copyright 2025 Samsung SDS. All Rights Reserved +# +# 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 network_ip_availability +from neutron_lib.api.definitions import network_ip_availability_details +from neutron_lib.tests.unit.api.definitions import base + + +class NetworkIPAvailabilityDetailsDefinitionTestCase( + base.DefinitionBaseTestCase): + extension_module = network_ip_availability_details + extension_resources = (network_ip_availability.RESOURCE_PLURAL,) + extension_attributes = ( + network_ip_availability_details.IP_AVAILABILITY_DETAILS,) diff --git a/releasenotes/notes/add-extension-network-ip-availability-detail-5cb384b0decf347f.yaml b/releasenotes/notes/add-extension-network-ip-availability-detail-5cb384b0decf347f.yaml new file mode 100644 index 000000000..a5c2c3c9d --- /dev/null +++ b/releasenotes/notes/add-extension-network-ip-availability-detail-5cb384b0decf347f.yaml @@ -0,0 +1,7 @@ +--- +features: + - | + Add a new API extension, ``network-ip-availability-details``, that adds + the ``ip_availability_details`` attribute to network IP availabilities. + The value of this attribute contains detailed information about the + network IP usage statistics.