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


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

Enabling in Neutron
-------------------

To enable this plugin within neutron, append this pluging class to the
comma-delimited plugin list to the end of the **service_plugins** configuration
property within your neutron.conf file.

Example::

    service_plugins=router, network_ip_availability


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

.. code::

    {
        "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-tenant",
                "total_ips": 253,
                "used_ips": 3
            },
            {
                "network_id": "47035bae-4f29-4fef-be2e-2941b72528a8",
                "network_name": "net2",
                "subnet_ip_availability": [],
                "tenant_id": "test-tenant",
                "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-tenant",
                "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

.. code::

    {
        "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-tenant",
            "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
  tenant 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 tenant uuid
    GET /v2.0/network-ip-availabilities?ip_version=4&tenant_id=example-tenant-uuid

    # Fetch multiple networks by their ids
    GET /v2.0/network-ip-availabilities?network_id=uuid_sample_1&network_id=uuid_sample_2
