Network IP Availability Extension¶
This extension is an information-only API that allows a user or process to determine the amount of IPs that are consumed across networks and their subnets’ allocation pools. Each network and embedded subnet returns with values for used_ips and total_ips making it easy to determine how much of your network’s IP space is consumed.
This API provides the ability for network administrators to periodically list usage (manual or automated) in order to preemptively add new network capacity when thresholds are exceeded.
Important Note:
This API tracks a network’s “consumable” IPs. What’s the distinction? After a network and its subnets are created, consumable IPs are:
- Consumed in the subnet’s allocations (derives used IPs)
- Consumed from the subnet’s allocation pools (derives total IPs)
This API tracks consumable IPs so network administrators know when their subnet’s IP pools (and ultimately a network’s) IPs are about to run out. This API does not account reserved IPs such as a subnet’s gateway IP or other reserved or unused IPs of a subnet’s cidr that are consumed as a result of the subnet creation itself.
API Specification¶
Availability for all networks¶
GET /v2.0/network-ip-availabilities
Request to url: v2.0/network-ip-availabilities
headers: {'content-type': 'application/json', 'X-Auth-Token': 'SOME_AUTH_TOKEN'}
Example response
Response:
HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
{
"network_ip_availabilities": [
{
"network_id": "f944c153-3f46-417b-a3c2-487cd9a456b9",
"network_name": "net1",
"subnet_ip_availability": [
{
"cidr": "10.0.0.0/24",
"ip_version": 4,
"subnet_id": "46b1406a-8373-454c-8eb8-500a09eb77fb",
"subnet_name": "",
"total_ips": 253,
"used_ips": 3
}
],
"tenant_id": "test-project",
"total_ips": 253,
"used_ips": 3
},
{
"network_id": "47035bae-4f29-4fef-be2e-2941b72528a8",
"network_name": "net2",
"subnet_ip_availability": [],
"tenant_id": "test-project",
"total_ips": 0,
"used_ips": 0
},
{
"network_id": "2e3ea0cd-c757-44bf-bb30-42d038687e3f",
"network_name": "net3",
"subnet_ip_availability": [
{
"cidr": "40.0.0.0/24",
"ip_version": 4,
"subnet_id": "aab6b35c-16b5-489c-a5c7-fec778273495",
"subnet_name": "",
"total_ips": 253,
"used_ips": 2
}
],
"tenant_id": "test-project",
"total_ips": 253,
"used_ips": 2
}
]
}
Availability by network ID¶
GET /v2.0/network-ip-availabilities/{network_uuid}
Request to url: /v2.0/network-ip-availabilities/aba3b29b-c119-4b45-afbd-88e500acd970
headers: {'content-type': 'application/json', 'X-Auth-Token': 'SOME_AUTH_TOKEN'}
Example response
Response:
HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
{
"network_ip_availability": {
"network_id": "f944c153-3f46-417b-a3c2-487cd9a456b9",
"network_name": "net1",
"subnet_ip_availability": [
{
"cidr": "10.0.0.0/24",
"ip_version": 4,
"subnet_name": "",
"subnet_id": "46b1406a-8373-454c-8eb8-500a09eb77fb",
"total_ips": 253,
"used_ips": 3
}
],
"tenant_id": "test-project",
"total_ips": 253,
"used_ips": 3
}
}
Supported Query Filters¶
This API currently supports the following query parameters:
- network_id: Returns availability for the network matching the network ID. Note: This query (?network_id={network_id_guid})is roughly equivalent to Availability by network ID section except it returns the plural response form as a list rather than as an item.
- network_name: Returns availability for network matching the provided name
- tenant_id: Returns availability for all networks owned by the provided project ID.
- ip_version: Filters network subnets by those supporting the supplied ip version. Values can be either 4 or 6.
Query filters can be combined to further narrow results and what is returned will match all criteria. When a parameter is specified more than once, it will return results that match both. Examples:
# Fetch IPv4 availability for a specific project uuid
GET /v2.0/network-ip-availabilities?ip_version=4&tenant_id=example-project-uuid
# Fetch multiple networks by their ids
GET /v2.0/network-ip-availabilities?network_id=uuid_sample_1&network_id=uuid_sample_2
Except where otherwise noted, this document is licensed under Creative Commons Attribution 3.0 License. See all OpenStack Legal Documents.