Add operator APIs for manipulating system IP Pools #9225

bnaecker · 2025-10-15T19:17:30Z

Add Nexus endpoints for reserving IP Pools for Oxide use or for external customer Silos
Remove check used to hide internal IP Pools, since they're all visible to an operator now
Rename operator IP Pool endpoints by prefixing system_*, to avoid conflicts with previous "silo-scoped" endpoints.
Handle possibility of any number of Oxide-internal IP Pools in various places where we previously assumed exactly 2 of them.
Fixes Add external APIs to reserve IP Pools for Oxide services #8947
Fixes Rename project_ip_pool_list and project_ip_pool_view #8226

nexus/src/external_api/http_entrypoints.rs

- Add Nexus endpoints for reserving IP Pools for Oxide use or for external customer Silos - Remove check used to hide internal IP Pools, since they're all visible to an operator now - Rename operator IP Pool endpoints by prefixing `system_*`, to avoid conflicts with previous "silo-scoped" endpoints. - Handle possibility of any number of Oxide-internal IP Pools in various places where we previously assumed exactly 2 of them. - Fixes #8947 - Fixes #8226

bnaecker · 2025-10-16T16:04:03Z

We should probably hold this PR until after we cut the R17 release. I'm also adding a PR to the CLI repo handling these breaking changes.

rcgoodfellow

Thanks @bnaecker! Comments follow.

nexus/db-queries/src/db/datastore/deployment/external_networking.rs

nexus/db-queries/src/db/datastore/ip_pool.rs

nexus/db-queries/src/db/datastore/rack.rs

nexus/reconfigurator/preparation/src/lib.rs

nexus/types/src/external_api/shared.rs

nexus/reconfigurator/preparation/src/lib.rs

bnaecker · 2025-11-18T05:19:42Z

Thanks for y'all's patience. Now that R17 is out, this is ready for a proper review.

ahl · 2025-11-18T18:29:36Z

nexus/external-api/src/lib.rs

    ) -> Result<HttpResponseOk<views::IpPoolSiloLink>, HttpError>;

-    /// Fetch Oxide service IP pool
+    /// Reserve an IP Pool for use by specific resources.


I don't understand this comment, but I also don't understand networking beyond what you told me about it being like a series of tubes.

On second thought I think I understand this better. "Reserve" is a funny verb. I think we're saying "should we use this IP pool for like normal silo shit or should we use it for system services"

I imagine we considered using "link" to a "thing that takes the place of a silo" but it was too confusing because e.g. in general an ip pool can be "linked" to multiple silos, but can only be "reserved" as a (the?) system silo exclusive to use with silos.

ahl · 2025-11-18T18:40:32Z

nexus/external-api/src/lib.rs

-        // is_default }
    ) -> Result<HttpResponseOk<ResultsPage<views::IpPoolSiloLink>>, HttpError>;

    /// Link IP pool to silo


I find this to be confusing. I think the idea is that there are IP Pools and Silos; a "link" is an association between them. I could ask "for this silo, show me the linked ip pools" or "for this ip pool, show me the linked silos"

I'm suggesting this as alternative text to the text below that I can't comment on due to github

Linking an IP pool and a silo allows users within that silo to allocate IP addresses from that IP pool and assign them to instances. When linking an IP pool, one can designated that pool as the "default" for the silo. When a user of that silo allocates an IP address without specifying a pool, IP addresses are allocated from that default pool. A silo can have a most one default poo.

And I think we should say the following, but I'm not sure it's correct:

If there is no default pool, requests that allocate IP addresses must specify a particular pool (linked to that silo). Specifying that a linked IP pool should be the default replaces the existing default (if there is one). To modify a silo's default IP pool, use the update operation. [a bit oblique, but trying to make it agnostic between the CLI and API]

Do we also need to explain how this can only be used for IP pools that are "reserved" for instances?

ahl · 2025-11-18T18:45:04Z

nexus/external-api/src/lib.rs

        tags = ["system/ip-pools"],
    }]
-    async fn ip_pool_silo_update(
+    async fn system_ip_pool_silo_update(


I think the docs above could be improved

Modify whether a linked IP pool is the default for a silo.

ahl · 2025-11-18T18:46:24Z

nexus/external-api/src/lib.rs

-    ) -> Result<HttpResponseOk<views::IpPool>, HttpError>;
+    ) -> Result<HttpResponseOk<views::SystemIpPool>, HttpError>;

    /// Fetch IP pool utilization


Suggested change

/// Fetch IP pool utilization

/// View IP pool utilization

Enh.. we're about 60/40 fetch vs. view so whatever...

ahl · 2025-11-18T18:48:45Z

nexus/types/src/external_api/shared.rs

+#[derive(Clone, Copy, Debug, Deserialize, JsonSchema, PartialEq, Serialize)]
+#[serde(rename_all = "snake_case")]
+pub enum IpPoolReservationType {
+    /// The pool is reserved for use by external customer Silos.


External to what? Customer? This comment appears in the OpenAPI document; I think we should write it as external docs

ahl · 2025-11-18T18:49:54Z

nexus/types/src/external_api/shared.rs

    }
 }

+/// Indicates what resources an IP Pool is reserved for.


Suggested change

/// Indicates what resources an IP Pool is reserved for.

/// IP Pool designation as either for Instances or System Services

ahl · 2025-11-18T18:58:11Z

nexus/types/src/external_api/views.rs

    pub ip_version: IpVersion,
    /// Type of IP pool (unicast or multicast)
    pub pool_type: shared::IpPoolType,
+    /// Resources the IP Pool is reserved for.


this seems like an odd use of the term "reserve"

ahl · 2025-11-18T19:16:05Z

nexus/types/src/external_api/params.rs

+    /// Which resources the IP Pool is reserved for.
+    ///
+    /// The default is reserved for external silos.
+    #[serde(default = "IpPoolReservationType::external_silos")]
+    pub reservation_type: IpPoolReservationType,


do we expect people to change ip pools from one type to another?

bnaecker force-pushed the add-system-ip-pool-apis branch from 4a65598 to eed8606 Compare October 15, 2025 21:41

bnaecker commented Oct 15, 2025

View reviewed changes

nexus/src/external_api/http_entrypoints.rs Outdated Show resolved Hide resolved

bnaecker force-pushed the add-system-ip-pool-apis branch from eed8606 to 143f98a Compare October 15, 2025 23:09

bnaecker requested review from ahl, david-crespo, jgallagher and rcgoodfellow October 15, 2025 23:24

WIP: Developer-scoped endpoint for listing IP Pool Ranges

b8b6fab

bnaecker added console Web console networking Related to the networking. labels Oct 17, 2025

rcgoodfellow reviewed Oct 21, 2025

View reviewed changes

jgallagher reviewed Nov 11, 2025

View reviewed changes

nexus/reconfigurator/preparation/src/lib.rs Show resolved Hide resolved

bnaecker added 5 commits November 17, 2025 18:44

Rename Oxide internal to System internal

f2da2f2

Merge remote-tracking branch 'origin/main' into add-system-ip-pool-apis

1ee9ccd

Fixes after merging with main

1390ab1

More fixup, add non-system endpoint to list IP Pool ranges

dae5a94

More cleanup

528fbcf

ahl reviewed Nov 18, 2025

View reviewed changes

	/// Indicates what resources an IP Pool is reserved for.
	/// IP Pool designation as either for Instances or System Services

Add operator APIs for manipulating system IP Pools #9225

Are you sure you want to change the base?

Add operator APIs for manipulating system IP Pools #9225

Uh oh!

Conversation

bnaecker commented Oct 15, 2025

Uh oh!

Uh oh!

bnaecker commented Oct 16, 2025

Uh oh!

rcgoodfellow left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

bnaecker commented Nov 18, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants