[ip_version/pool allocation] Refactor IP pool selection to use tagged enums (type-safe API) (#9598)

This PR refactors `FloatingIpCreate`, `EphemeralIpCreate`, `ExternalIpCreate::Ephemeral`, and `ProbeCreate` to use tagged enums for pool selection, making invalid states unrepresentable at the type level.

Previously, these types used flat Option fields (`pool`, `ip_version`, `ip`) that required runtime validation to catch invalid combinations like `ip_version + pool` or `ip + ip_version`. The new design uses:

- `PoolSelector` enum with `Explicit { pool }` and `Auto { ip_version }` variants, used by `EphemeralIpCreate`, `ExternalIpCreate::Ephemeral`, and `ProbeCreate`
- `AddressSelector` enum with `Explicit { ip, pool }` and `Auto { pool_selector }` variants for `FloatingIpCreate`

This all ensures at the type level that...
- `ip_version` can only be specified when auto-selecting from a pool
- `ip_version` cannot be combined with an explicit IP address
- Explicit pools cannot accept `ip_version` (the pool determines available IPs)

Includes:

- The `Explicit { ip, pool }` combination remains valid for reserving a specific IP, validating that it exists in the given pool (pool is a constraint, not a selection method).

- When using `Auto` mode (or when the pool/address selector is omitted), the silo's default pool is used. If the silo has default pools for both IPv4 and IPv6, the request will fail unless `ip_version` is specified to disambiguate.

- API versioning: Added `v2026010300.rs` with the old flat types and `TryFrom` implementations that validate and convert to the new enum-based types for delegation. Older API versions continue to work via the existing conversion chain.

- `ProbeCreate` in the experimental API previously lacked `ip_version` support; this is now addressed using the `PoolSelector` enumerator.

Author: zeeshanlakhani

end-to-end-tests/src/bin/commtest.rs

@@ -8,8 +8,8 @@ use oxide_client::{
     ClientVpcsExt,
     types::{
         IpPoolCreate, IpPoolLinkSilo, IpPoolType, IpRange, IpVersion, Name,
-        NameOrId, PingStatus, ProbeCreate, ProbeInfo, ProjectCreate,
-        UsernamePasswordCredentials,
+        NameOrId, PingStatus, PoolSelector, ProbeCreate, ProbeInfo,
+        ProjectCreate, UsernamePasswordCredentials,
     },
 };
 use std::{
@@ -389,7 +389,9 @@ async fn launch_probes(
                     .project(Name::try_from("classone").unwrap())
                     .body(ProbeCreate {
                         description: format!("probe {i}"),
-                        ip_pool: Some("default".parse().unwrap()),
+                        pool_selector: PoolSelector::Explicit {
+                            pool: "default".parse().unwrap(),
+                        },
                         name: format!("probe{i}").parse().unwrap(),
                         sled,
                     })

end-to-end-tests/src/instance_launch.rs

@@ -7,7 +7,8 @@ use omicron_test_utils::dev::poll::{CondCheckError, wait_for_condition};
 use oxide_client::types::{
     ByteCount, DiskBackend, DiskCreate, DiskSource, ExternalIp,
     ExternalIpCreate, InstanceCpuCount, InstanceCreate, InstanceDiskAttachment,
-    InstanceNetworkInterfaceAttachment, InstanceState, IpVersion, SshKeyCreate,
+    InstanceNetworkInterfaceAttachment, InstanceState, IpVersion, PoolSelector,
+    SshKeyCreate,
 };
 use oxide_client::{ClientCurrentUserExt, ClientDisksExt, ClientInstancesExt};
 use russh::{ChannelMsg, Disconnect};
@@ -73,8 +74,9 @@ async fn instance_launch() -> Result<()> {
             network_interfaces:
                 InstanceNetworkInterfaceAttachment::DefaultDualStack,
             external_ips: vec![ExternalIpCreate::Ephemeral {
-                pool: None,
-                ip_version: Some(IpVersion::V4),
+                pool_selector: PoolSelector::Auto {
+                    ip_version: Some(IpVersion::V4),
+                },
             }],
             user_data: String::new(),
             ssh_public_keys: Some(vec![oxide_client::types::NameOrId::Name(

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

@@ -98,9 +98,15 @@ impl DataStore {
         ip_id: Uuid,
         probe_id: Uuid,
         pool: Option<authz::IpPool>,
+        ip_version: Option<IpVersion>,
     ) -> CreateResult<ExternalIp> {
         let authz_pool = self
-            .resolve_pool_for_allocation(opctx, pool, IpPoolType::Unicast, None)
+            .resolve_pool_for_allocation(
+                opctx,
+                pool,
+                IpPoolType::Unicast,
+                ip_version,
+            )
             .await?;
         let data = IncompleteExternalIp::for_ephemeral_probe(
             ip_id,

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

@@ -19,6 +19,7 @@ use nexus_db_errors::ErrorHandler;
 use nexus_db_errors::public_error_from_diesel;
 use nexus_db_lookup::LookupPath;
 use nexus_db_model::IncompleteNetworkInterface;
+use nexus_db_model::IpVersion;
 use nexus_db_model::Probe;
 use nexus_db_model::VpcSubnet;
 use nexus_types::external_api::params::PrivateIpStackCreate;
@@ -219,6 +220,7 @@ impl super::DataStore {
         authz_project: &authz::Project,
         probe: &Probe,
         ip_pool: Option<authz::IpPool>,
+        ip_version: Option<IpVersion>,
     ) -> CreateResult<Probe> {
         // TODO-correctness: These need to be in a transaction.
         // See https://github.com/oxidecomputer/omicron/issues/9340.
@@ -231,6 +233,7 @@ impl super::DataStore {
                 Uuid::new_v4(),
                 probe.id(),
                 ip_pool,
+                ip_version,
             )
             .await?;
 

nexus/external-api/src/lib.rs

@@ -39,6 +39,7 @@ mod v2025120300;
 mod v2025121200;
 mod v2025122300;
 mod v2026010100;
+mod v2026010300;
 
 api_versions!([
     // API versions are in the format YYYYMMDDNN.0.0, defined below as
@@ -68,6 +69,7 @@ api_versions!([
     // |  date-based version should be at the top of the list.
     // v
     // (next_yyyymmddnn, IDENT),
+    (2026010500, POOL_SELECTION_ENUMS),
     (2026010300, DUAL_STACK_NICS),
     (2026010100, SILO_PROJECT_IP_VERSION_AND_POOL_TYPE),
     (2025122300, IP_VERSION_AND_MULTIPLE_DEFAULT_POOLS),
@@ -1298,12 +1300,30 @@ pub trait NexusExternalApi {
         .await
     }
 
+    /// Create floating IP
+    #[endpoint {
+        operation_id = "floating_ip_create",
+        method = POST,
+        path = "/v1/floating-ips",
+        tags = ["floating-ips"],
+        versions = VERSION_IP_VERSION_AND_MULTIPLE_DEFAULT_POOLS
+            ..VERSION_POOL_SELECTION_ENUMS,
+    }]
+    async fn v2026010300_floating_ip_create(
+        rqctx: RequestContext<Self::Context>,
+        query_params: Query<params::ProjectSelector>,
+        floating_params: TypedBody<v2026010300::FloatingIpCreate>,
+    ) -> Result<HttpResponseCreated<views::FloatingIp>, HttpError> {
+        let floating_params = floating_params.try_map(TryInto::try_into)?;
+        Self::floating_ip_create(rqctx, query_params, floating_params).await
+    }
+
     /// Create floating IP
     #[endpoint {
         method = POST,
         path = "/v1/floating-ips",
         tags = ["floating-ips"],
-        versions = VERSION_IP_VERSION_AND_MULTIPLE_DEFAULT_POOLS..,
+        versions = VERSION_POOL_SELECTION_ENUMS..,
     }]
     async fn floating_ip_create(
         rqctx: RequestContext<Self::Context>,
@@ -1756,10 +1776,27 @@ pub trait NexusExternalApi {
 
     /// Create instance
     #[endpoint {
+        operation_id = "instance_create",
         method = POST,
         path = "/v1/instances",
         tags = ["instances"],
-        versions = VERSION_DUAL_STACK_NICS..,
+        versions = VERSION_DUAL_STACK_NICS..VERSION_POOL_SELECTION_ENUMS,
+    }]
+    async fn v2026010300_instance_create(
+        rqctx: RequestContext<Self::Context>,
+        query_params: Query<params::ProjectSelector>,
+        new_instance: TypedBody<v2026010300::InstanceCreate>,
+    ) -> Result<HttpResponseCreated<Instance>, HttpError> {
+        let new_instance = new_instance.try_map(TryInto::try_into)?;
+        Self::instance_create(rqctx, query_params, new_instance).await
+    }
+
+    /// Create instance
+    #[endpoint {
+        method = POST,
+        path = "/v1/instances",
+        tags = ["instances"],
+        versions = VERSION_POOL_SELECTION_ENUMS..,
     }]
     async fn instance_create(
         rqctx: RequestContext<Self::Context>,
@@ -3097,12 +3134,37 @@ pub trait NexusExternalApi {
         .await
     }
 
+    /// Allocate and attach ephemeral IP to instance
+    #[endpoint {
+        operation_id = "instance_ephemeral_ip_attach",
+        method = POST,
+        path = "/v1/instances/{instance}/external-ips/ephemeral",
+        tags = ["instances"],
+        versions = VERSION_IP_VERSION_AND_MULTIPLE_DEFAULT_POOLS
+            ..VERSION_POOL_SELECTION_ENUMS,
+    }]
+    async fn v2026010300_instance_ephemeral_ip_attach(
+        rqctx: RequestContext<Self::Context>,
+        path_params: Path<params::InstancePath>,
+        query_params: Query<params::OptionalProjectSelector>,
+        ip_to_create: TypedBody<v2026010300::EphemeralIpCreate>,
+    ) -> Result<HttpResponseAccepted<views::ExternalIp>, HttpError> {
+        let ip_to_create = ip_to_create.try_map(TryInto::try_into)?;
+        Self::instance_ephemeral_ip_attach(
+            rqctx,
+            path_params,
+            query_params,
+            ip_to_create,
+        )
+        .await
+    }
+
     /// Allocate and attach ephemeral IP to instance
     #[endpoint {
         method = POST,
         path = "/v1/instances/{instance}/external-ips/ephemeral",
         tags = ["instances"],
-        versions = VERSION_IP_VERSION_AND_MULTIPLE_DEFAULT_POOLS..,
+        versions = VERSION_POOL_SELECTION_ENUMS..,
     }]
     async fn instance_ephemeral_ip_attach(
         rqctx: RequestContext<Self::Context>,
@@ -4466,11 +4528,28 @@ pub trait NexusExternalApi {
         query_params: Query<params::ProjectSelector>,
     ) -> Result<HttpResponseOk<shared::ProbeInfo>, HttpError>;
 
+    /// Create instrumentation probe
+    #[endpoint {
+        operation_id = "probe_create",
+        method = POST,
+        path = "/experimental/v1/probes",
+        tags = ["experimental"], // system/probes: only one tag is allowed
+        versions = ..VERSION_POOL_SELECTION_ENUMS,
+    }]
+    async fn v2026010300_probe_create(
+        rqctx: RequestContext<Self::Context>,
+        query_params: Query<params::ProjectSelector>,
+        new_probe: TypedBody<v2026010300::ProbeCreate>,
+    ) -> Result<HttpResponseCreated<Probe>, HttpError> {
+        Self::probe_create(rqctx, query_params, new_probe.map(Into::into)).await
+    }
+
     /// Create instrumentation probe
     #[endpoint {
         method = POST,
         path = "/experimental/v1/probes",
         tags = ["experimental"], // system/probes: only one tag is allowed
+        versions = VERSION_POOL_SELECTION_ENUMS..,
     }]
     async fn probe_create(
         rqctx: RequestContext<Self::Context>,

nexus/external-api/src/v2025112000.rs

@@ -220,6 +220,7 @@ pub struct InstanceCreate {
     /// By default, all instances have outbound connectivity, but no inbound
     /// connectivity. These external addresses can be used to provide a fixed,
     /// known IP address for making inbound connections to the instance.
+    // Delegates through v2025121200 → params::ExternalIpCreate
     #[serde(default)]
     pub external_ips: Vec<v2025121200::ExternalIpCreate>,
 

nexus/external-api/src/v2025121200.rs

@@ -2,7 +2,7 @@
 // License, v. 2.0. If a copy of the MPL was not distributed with this
 // file, You can obtain one at https://mozilla.org/MPL/2.0/.
 
-//! Nexus external types that changed from 2025121200 to 2025601010.
+//! Nexus external types that changed from 2025121200 to 2026010100.
 //!
 //! Version 2025121200 types (before `ip_version` preference was added for
 //! default IP pool selection).
@@ -40,7 +40,11 @@ pub struct EphemeralIpCreate {
 
 impl From<EphemeralIpCreate> for params::EphemeralIpCreate {
     fn from(old: EphemeralIpCreate) -> params::EphemeralIpCreate {
-        params::EphemeralIpCreate { pool: old.pool, ip_version: None }
+        let pool_selector = match old.pool {
+            Some(pool) => params::PoolSelector::Explicit { pool },
+            None => params::PoolSelector::Auto { ip_version: None },
+        };
+        params::EphemeralIpCreate { pool_selector }
     }
 }
 
@@ -67,7 +71,11 @@ impl From<ExternalIpCreate> for params::ExternalIpCreate {
     fn from(old: ExternalIpCreate) -> params::ExternalIpCreate {
         match old {
             ExternalIpCreate::Ephemeral { pool } => {
-                params::ExternalIpCreate::Ephemeral { pool, ip_version: None }
+                let pool_selector = match pool {
+                    Some(pool) => params::PoolSelector::Explicit { pool },
+                    None => params::PoolSelector::Auto { ip_version: None },
+                };
+                params::ExternalIpCreate::Ephemeral { pool_selector }
             }
             ExternalIpCreate::Floating { floating_ip } => {
                 params::ExternalIpCreate::Floating { floating_ip }
@@ -93,12 +101,16 @@ pub struct FloatingIpCreate {
 
 impl From<FloatingIpCreate> for params::FloatingIpCreate {
     fn from(old: FloatingIpCreate) -> params::FloatingIpCreate {
-        params::FloatingIpCreate {
-            identity: old.identity,
-            ip: old.ip,
-            pool: old.pool,
-            ip_version: None,
-        }
+        let address_selector = match (old.ip, old.pool) {
+            (Some(ip), pool) => params::AddressSelector::Explicit { ip, pool },
+            (None, Some(pool)) => params::AddressSelector::Auto {
+                pool_selector: params::PoolSelector::Explicit { pool },
+            },
+            (None, None) => params::AddressSelector::Auto {
+                pool_selector: params::PoolSelector::Auto { ip_version: None },
+            },
+        };
+        params::FloatingIpCreate { identity: old.identity, address_selector }
     }
 }
 
@@ -120,6 +132,8 @@ pub struct InstanceCreate {
     #[serde(default)]
     pub network_interfaces: v2026010100::InstanceNetworkInterfaceAttachment,
     /// The external IP addresses provided to this instance.
+    // Uses local ExternalIpCreate (no ip_version field) → params::ExternalIpCreate
+    // (defaults ip_version to None in From impl)
     #[serde(default)]
     pub external_ips: Vec<ExternalIpCreate>,
     /// The multicast groups this instance should join.

nexus/external-api/src/v2026010100.rs

@@ -31,6 +31,8 @@ use serde::Serialize;
 use std::net::IpAddr;
 use uuid::Uuid;
 
+use crate::v2026010300;
+
 /// Describes an attachment of an `InstanceNetworkInterface` to an `Instance`,
 /// at the time the instance is created.
 // NOTE: VPC's are an organizing concept for networking resources, not for
@@ -81,7 +83,7 @@ impl TryFrom<InstanceNetworkInterfaceAttachment>
                 .collect::<Result<_, _>>()
                 .map(Self::Create),
             InstanceNetworkInterfaceAttachment::Default => {
-                Ok(Self::DefaultDualStack)
+                Ok(Self::DefaultIpv4)
             }
             InstanceNetworkInterfaceAttachment::None => Ok(Self::None),
         }
@@ -255,7 +257,7 @@ impl TryFrom<InstanceNetworkInterfaceCreate>
                         transit_ips: ipv6_transit_ips,
                     })
                 } else {
-                    PrivateIpStackCreate::auto_dual_stack()
+                    PrivateIpStackCreate::auto_ipv4()
                 }
             }
             Some(IpAddr::V4(ipv4)) => {
@@ -325,8 +327,9 @@ pub struct InstanceCreate {
     /// By default, all instances have outbound connectivity, but no inbound
     /// connectivity. These external addresses can be used to provide a fixed,
     /// known IP address for making inbound connections to the instance.
+    // Delegates through v2026010300 → params::ExternalIpCreate
     #[serde(default)]
-    pub external_ips: Vec<params::ExternalIpCreate>,
+    pub external_ips: Vec<v2026010300::ExternalIpCreate>,
 
     /// The multicast groups this instance should join.
     ///
@@ -418,7 +421,11 @@ impl TryFrom<InstanceCreate> for params::InstanceCreate {
             hostname: value.hostname,
             user_data: value.user_data,
             network_interfaces,
-            external_ips: value.external_ips,
+            external_ips: value
+                .external_ips
+                .into_iter()
+                .map(TryInto::try_into)
+                .collect::<Result<Vec<_>, _>>()?,
             multicast_groups: value.multicast_groups,
             disks: value.disks,
             boot_disk: value.boot_disk,