Comment 9 for bug 1467120

Here are my current thoughts on what this may look like in MAAS 1.9; feedback appreciated. This isn't set in stone, as I'm still iterating with the team. But stakeholder feedback would be great.

Use cases (2) and (3), I think, are optional. But (3) would be nice to have for support/troubleshooting purposes.

I added the address_family parameter because I don't think this makes a lot of sense for IPv6. And on second thought, reserving a typical IPv6 range could entail adding a few billion addresses to the database in the current design, so that won't work. (So maybe we should make these APIs IPv4-only for now; with the possible exception of "find_reserved_ip_addresses".)

Use cases:

(1) As a MAAS API user, I want to determine which IP ranges within a specific MAAS-managed subnet are free.

# maas <profile> subnet find_unused_ip_ranges <subnet_id> [address_family=<all|ipv4|ipv6>]
[
    {
        "start": "10.0.0.2"
        "end": "10.0.0.49"
        "num_addresses": 48
    },
    {
        "start": "10.0.0.151"
        "end": "10.0.0.253"
        "num_addresses": 103
    }
]

(2) As a MAAS API user, I want to determine which IP ranges are unused across the system.

# maas <profile> subnets find_unused_ip_ranges [address_family=<all|ipv4|ipv6>]
[
    {
        "subnet": <Subnet>,
        "management": <unmanaged|dhcp|dhcp-and-dns>,
        "ranges": [<see-above>]
    }
]

(3) As a MAAS API user, I want to determine which IP addresses are in use for a particular subnet, and why.

# maas <profile> subnet find_reserved_ip_addresses <subnet_id> [address_family=<all|ipv4|ipv6>]
[
    {
        "start": "10.0.0.1",
        "end": "10.0.0.1",
        "num_addresses": 1,
        "reason": "gateway"
    },
    {
        "start": "10.0.0.50",
        "end": "10.0.0.99",
        "num_addresses": 49,
        "reason": "maas-managed-dynamic"
    },
    {
        "start": "10.0.0.100",
        "end": "10.0.0.150",
        "num_addresses": 49,
        "reason": "maas-managed-static"
    },
    {
        "start": "10.0.0.254",
        "end": "10.0.0.254",
        "num_addresses": 1,
        "reason": "dns"
    },
]

(4) As a MAAS API user, I want to reserve a range of IP addresses.

# maas <profile> subnet reserve_ip_range <subnet_id> start=<start_address> end=<end_address> num_addresses=<num_addresses>