[nexus] List allocated IPs in a VPC subnet

This is a summary of a discussion we had in chat about replacing /v1/vpc-subnets/{subnet}/network-interfaces with something better.

/v1/vpc-subnets/{subnet}/network-interfaces for lists network interfaces associated with a VPC subnet.[^1] The parent collection of a network interface is an instance, so as you would expect, the top-level /v1/network-interfaces endpoint takes an instance selector in the query params in accordance with the patterns established in RFD 322. That endpoint cannot list NICs by subnet.

Why does /v1/vpc-subnets/{subnet}/network-interfaces exist? You can take this question two ways.

1. Why /v1/vpc-subnets/{subnet}/network-interfaces instead of /v1/network-interfaces?subnet={subnet}?

Assuming we want to list NICs for a subnet, why does the endpoint have this route instead of being implemented as a subnet filter on /v1/network-interfaces? The simple answer is that we don't have any other endpoints that support multiple kinds of parent filter. The query params would have to look something like this:

struct NetworkInterfaceParentSelector {
  organization: Option<NameOrId>,
  project: Option<NameOrId>,
  instance: Option<NameOrId>,
  vpc: Option<NameOrId>,
  subnet: Option<NameOrId>,
}

But only combinations that can uniquely determine either an instance or a VPC subnet would be valid. We may to do things like this in the future, but right now it would be both difficult to implement and difficult to explain.

2. Why do we want to list network interfaces for a subnet at all?

The other way of asking why this endpoint exists is to ask why we want to list network interfaces associated with a subnet at all? This has a more interesting answer and points toward what I think is the better medium-term solution. When you ask for the list of NICs associated with a subnet, generally what you really want to know is what IPs are allocated in this subnet. It just so happens that internal IPs do not have their own table and NICs are the only thing that they can be allocated for, so NICs are the most natural thing to list. They helpfully also tell you the instance ID they're associated with, so you can also answer the question of what instance is using each IP.

However, in the future we intend to have more things that can get IPs in a subnet — internet gateways, load balances, VPNs — things like that. So in that situation, what you really want to do is ask for all the IPs allocated within a subnet, and each one would tell you something about the thing it's allocated for: picture a kind (currently only network interface) and an ID for the thing, and possibly other metadata about the thing if we want to be really helpful.

[^1]: Well, it will once #2472 is merged. We also have a legacy-style endpoint doing the same thing, but it's about to be deleted.

Start with the linked Matrix discussion and compare the mentioned /v1/vpc-subnets/{subnet}/network-interfaces and /v1/network-interfaces endpoints, along with RFD 322. The issue describes a possible replacement for listing allocated IPs but does not identify files, tests, an implementation entry point, or a concrete definition of done.