Rename project_ip_pools_list and _view

[david-crespo]

Just an idea, not married to it. Figured it was just as easy to PR as to write an issue.

---

These endpoints were named when we thought IP pools might be project-scoped, but they are not; they are silo-scoped, with no plans I can see to change that. So it would be cool if we could get project_ out of the endpoint names. However, there are complications that make it hard to pick a natural alternative. There are three (3) different IP pool list endpoints:

Op ID	Path	Description	Used for
ip_pool_list	/v1/system/ip-pools	All IP pools in fleet	IP pools list (operator)
silo_ip_pool_list	/v1/system/silos/{silo}/ip-pools	Pools linked to specified silo	Silo detail IP pools tab (operator)
project_ip_pool_list	/v1/ip-pools	Pools linked to user's current silo	End-user IP pool picking

Usually we treat the silo-scoped endpoint as the conceptual default and therefore leave off a qualifier (which would mean adding system_ to the fleet-scoped list and view). But in this case, there are a bunch of other system-level IP pool endpoints that will never have analogues inside the silo and which it feels silly to add system_ to.

omicron/nexus/tests/output/nexus_tags.txt

Lines 154 to 172 in 76e140b

	API operations found with tag "system/networking"
	OPERATION ID METHOD URL PATH
	ip_pool_create POST /v1/system/ip-pools
	ip_pool_delete DELETE /v1/system/ip-pools/{pool}
	ip_pool_list GET /v1/system/ip-pools
	ip_pool_range_add POST /v1/system/ip-pools/{pool}/ranges/add
	ip_pool_range_list GET /v1/system/ip-pools/{pool}/ranges
	ip_pool_range_remove POST /v1/system/ip-pools/{pool}/ranges/remove
	ip_pool_service_range_add POST /v1/system/ip-pools-service/ranges/add
	ip_pool_service_range_list GET /v1/system/ip-pools-service/ranges
	ip_pool_service_range_remove POST /v1/system/ip-pools-service/ranges/remove
	ip_pool_service_view GET /v1/system/ip-pools-service
	ip_pool_silo_link POST /v1/system/ip-pools/{pool}/silos
	ip_pool_silo_list GET /v1/system/ip-pools/{pool}/silos
	ip_pool_silo_unlink DELETE /v1/system/ip-pools/{pool}/silos/{silo}
	ip_pool_silo_update PUT /v1/system/ip-pools/{pool}/silos/{silo}
	ip_pool_update PUT /v1/system/ip-pools/{pool}
	ip_pool_utilization_view GET /v1/system/ip-pools/{pool}/utilization
	ip_pool_view GET /v1/system/ip-pools/{pool}

So I want to add the qualifier to the silo-scoped endpoint. Because silo_ip_pool_list already exists, I went with renaming project_ip_pool_list to current_silo_ip_pool_list.

[karencfv]

I'm a bit confused by all of this 😅 Would there be much harm in leaving the system and silo endpoints as they are, and changing project_ip_pool_list to ip_pool_list_local or something like that? Or am I making it even more confusing?

[david-crespo]

I think I would prefer that too if we can come up with a decent name. Since silo_ip_pool_list is taken, maybe current_silo_ip_pool_list.

[karencfv]

I like current_silo_ip_pool_list

[ahl]

I'm going to argue separately for the current status quo, but first against current_silo_*:

1. From the perspective of the user, all (most?) operations pertain to the current silo. In fact, users won't typically be aware of the multi-tenant nature of the environment. I don't think it's a good idea to start using current_silo_ as a distinguishing prefix. We already use system_ to indicate the other direction. If we introduce this alternate convention, we could end up with a mish-mash of system_foo and current_silo_bar.

2. Agreed on this "they are silo-scoped, with no plans I can see to change that". But might we get requests to change this in the near-future? Seems possible if not likely.

However! If we're going to change these endpoints, I'd suggest we first want to move them into the "silos" tag (i.e. out of the current "projects" tag). I think there a couple of options to consider. First, note that half of the operations in the "networking" tag start with networking_--might we change the ip_pool_* ones to be networking_ip_pool_* or change them all to have a system_* prefix?

This is all to say 1. there's some cleanup that might be warranted and 2. it might be best to kick this can further down the road.

[david-crespo]

Sympathetic to all points, definitely tempted to punt. My counter-feeling is that "project_" is straight up wrong, so there has to be something we change it to that's better than straight up wrong.

[ahl]

Sympathetic to all points, definitely tempted to punt.

You know that's my go-to move.

My counter-feeling is that "project_" is straight up wrong, so there has to be something we change it to that's better than straight up wrong.

I'm less convinced that it's wrong, but if we're going to change something I'd suggest we change the system-level endpoints to have a prefix and leave the silo-context ones as ip_pools_{list,view}

[david-crespo]

I think you're succeeding at getting me to just give up here. I guess project_ is not so bad. 🙃

---

I considered putting the prefix on the fleet ones, but I was surprised to find that we only have the system_ prefix on 3 endpoints.

https://github.com/oxidecomputer/omicron/blob/c36ada99955f4f7ff8378cb29a349110e3212f1c/nexus/tests/output/nexus_tags.txt

It felt a bit heavy to put the prefix on like 15 endpoints here.

omicron/nexus/tests/output/nexus_tags.txt

Lines 154 to 172 in c36ada9

	API operations found with tag "system/networking"
	OPERATION ID METHOD URL PATH
	ip_pool_create POST /v1/system/ip-pools
	ip_pool_delete DELETE /v1/system/ip-pools/{pool}
	ip_pool_list GET /v1/system/ip-pools
	ip_pool_range_add POST /v1/system/ip-pools/{pool}/ranges/add
	ip_pool_range_list GET /v1/system/ip-pools/{pool}/ranges
	ip_pool_range_remove POST /v1/system/ip-pools/{pool}/ranges/remove
	ip_pool_service_range_add POST /v1/system/ip-pools-service/ranges/add
	ip_pool_service_range_list GET /v1/system/ip-pools-service/ranges
	ip_pool_service_range_remove POST /v1/system/ip-pools-service/ranges/remove
	ip_pool_service_view GET /v1/system/ip-pools-service
	ip_pool_silo_link POST /v1/system/ip-pools/{pool}/silos
	ip_pool_silo_list GET /v1/system/ip-pools/{pool}/silos
	ip_pool_silo_unlink DELETE /v1/system/ip-pools/{pool}/silos/{silo}
	ip_pool_silo_update PUT /v1/system/ip-pools/{pool}/silos/{silo}
	ip_pool_update PUT /v1/system/ip-pools/{pool}
	ip_pool_utilization_view GET /v1/system/ip-pools/{pool}/utilization
	ip_pool_view GET /v1/system/ip-pools/{pool}