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.