[nexus] Clean up API versioning: chain conversions, fix module docs

This PR refactors a set of versioned type conversions to properly follow the
[API versioning guide's](https://github.com/oxidecomputer/dropshot-api-manager/blob/main/guides/new-version.md)
recommendations, including chaining through consecutive versions, ordering
conventions, and aligning types to correctly match the ranges and
where they should be defined.

Changes:
  - Chain InstanceCreate conversions: v2025122300 → v2026010300 →
    v2026010500 → params
  - Update endpoint handlers to delegate through the version chain
  - Add per-section validity docs for modules where types have different
    supersession versions
  - Remove empty v2026011501.rs after types moved to v2026010500

Author: zeeshanlakhani

nexus/external-api/src/lib.rs

@@ -41,7 +41,6 @@ mod v2025122300;
 mod v2026010100;
 mod v2026010300;
 mod v2026010500;
-mod v2026011501;
 
 #[cfg(test)]
 mod test_utils;
@@ -1610,8 +1609,8 @@ pub trait NexusExternalApi {
         floating_params: TypedBody<v2026010300::FloatingIpCreate>,
     ) -> Result<HttpResponseCreated<views::FloatingIp>, HttpError> {
         let floating_params =
-            floating_params.try_map(v2026011501::FloatingIpCreate::try_from)?;
-        Self::v2026011501_floating_ip_create(
+            floating_params.try_map(v2026010500::FloatingIpCreate::try_from)?;
+        Self::v2026010500_floating_ip_create(
             rqctx,
             query_params,
             floating_params,
@@ -1627,10 +1626,10 @@ pub trait NexusExternalApi {
         tags = ["floating-ips"],
         versions = VERSION_POOL_SELECTION_ENUMS..VERSION_RENAME_ADDRESS_SELECTOR_TO_ADDRESS_ALLOCATOR,
     }]
-    async fn v2026011501_floating_ip_create(
+    async fn v2026010500_floating_ip_create(
         rqctx: RequestContext<Self::Context>,
         query_params: Query<params::ProjectSelector>,
-        floating_params: TypedBody<v2026011501::FloatingIpCreate>,
+        floating_params: TypedBody<v2026010500::FloatingIpCreate>,
     ) -> Result<HttpResponseCreated<views::FloatingIp>, HttpError> {
         Self::floating_ip_create(
             rqctx,
@@ -2172,7 +2171,7 @@ pub trait NexusExternalApi {
         query_params: Query<params::ProjectSelector>,
         new_instance: TypedBody<v2025112000::InstanceCreate>,
     ) -> Result<HttpResponseCreated<Instance>, HttpError> {
-        Self::v2025121200_instance_create(
+        Self::v2025120300_instance_create(
             rqctx,
             query_params,
             new_instance.map(Into::into),
@@ -2188,12 +2187,12 @@ pub trait NexusExternalApi {
         tags = ["instances"],
         versions = VERSION_LOCAL_STORAGE..VERSION_IP_VERSION_AND_MULTIPLE_DEFAULT_POOLS,
     }]
-    async fn v2025121200_instance_create(
+    async fn v2025120300_instance_create(
         rqctx: RequestContext<Self::Context>,
         query_params: Query<params::ProjectSelector>,
-        new_instance: TypedBody<v2025121200::InstanceCreate>,
+        new_instance: TypedBody<v2025120300::InstanceCreate>,
     ) -> Result<HttpResponseCreated<Instance>, HttpError> {
-        Self::v2026010100_instance_create(
+        Self::v2025122300_instance_create(
             rqctx,
             query_params,
             new_instance.map(Into::into),
@@ -2210,13 +2209,17 @@ pub trait NexusExternalApi {
         versions =
             VERSION_IP_VERSION_AND_MULTIPLE_DEFAULT_POOLS..VERSION_DUAL_STACK_NICS,
     }]
-    async fn v2026010100_instance_create(
+    async fn v2025122300_instance_create(
         rqctx: RequestContext<Self::Context>,
         query_params: Query<params::ProjectSelector>,
-        new_instance: TypedBody<v2026010100::InstanceCreate>,
+        new_instance: TypedBody<v2025122300::InstanceCreate>,
     ) -> Result<HttpResponseCreated<Instance>, HttpError> {
-        let new_instance = new_instance.try_map(TryInto::try_into)?;
-        Self::instance_create(rqctx, query_params, new_instance).await
+        Self::v2026010300_instance_create(
+            rqctx,
+            query_params,
+            new_instance.try_map(TryInto::try_into)?,
+        )
+        .await
     }
 
     /// Create instance
@@ -2232,8 +2235,12 @@ pub trait NexusExternalApi {
         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
+        Self::v2026010500_instance_create(
+            rqctx,
+            query_params,
+            new_instance.try_map(TryInto::try_into)?,
+        )
+        .await
     }
 
     /// Create instance

nexus/external-api/src/v2025112000.rs

@@ -2,9 +2,10 @@
 // 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 2025112000 to 2025120300
+//! Nexus external types that changed from 2025112000 (INITIAL) to 2025120300
+//! (LOCAL_STORAGE).
 
-use crate::v2025121200;
+use crate::v2025120300;
 use crate::v2026010100;
 use nexus_types::external_api::params;
 use omicron_common::api::external;
@@ -220,9 +221,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 v2025121200 → params::ExternalIpCreate
+    // Delegates through v2025120300 → params::ExternalIpCreate
     #[serde(default)]
-    pub external_ips: Vec<v2025121200::ExternalIpCreate>,
+    pub external_ips: Vec<v2025120300::ExternalIpCreate>,
 
     /// The multicast groups this instance should join.
     ///
@@ -302,9 +303,9 @@ pub struct InstanceCreate {
     pub cpu_platform: Option<external::InstanceCpuPlatform>,
 }
 
-impl From<InstanceCreate> for v2025121200::InstanceCreate {
-    fn from(old: InstanceCreate) -> v2025121200::InstanceCreate {
-        v2025121200::InstanceCreate {
+impl From<InstanceCreate> for v2025120300::InstanceCreate {
+    fn from(old: InstanceCreate) -> v2025120300::InstanceCreate {
+        v2025120300::InstanceCreate {
             identity: old.identity,
             ncpus: old.ncpus,
             memory: old.memory,

nexus/external-api/src/v2025120300.rs

@@ -2,14 +2,34 @@
 // 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 2025120300 to 2025121200
+//! Nexus external types introduced in 2025120300 (LOCAL_STORAGE).
+//!
+//! This version introduced local storage support for instances.
+//!
+//! ## Instance Creation Types
+//!
+//! Valid until 2025122300 (IP_VERSION_AND_MULTIPLE_DEFAULT_POOLS).
+//!
+//! [`InstanceCreate`] and [`ExternalIpCreate`] are defined here for use
+//! by the `instance_create` endpoint in this version. These types don't
+//! have the `ip_version` field that was added in later versions.
+//!
+//! ## BGP Types
+//!
+//! Valid until 2025121200 (BGP_PEER_COLLISION_STATE).
+//!
+//! [`BgpPeerStatus`] and [`BgpPeerState`] are older versions without the
+//! `collision_state` field added in `BGP_PEER_COLLISION_STATE`.
 
 use std::net::IpAddr;
 
+use nexus_types::external_api::params;
 use omicron_common::api::external;
 use schemars::JsonSchema;
 use serde::{Deserialize, Serialize};
 
+use crate::{v2025122300, v2026010100, v2026010300};
+
 /// The current status of a BGP peer.
 #[derive(Clone, Debug, Deserialize, JsonSchema, Serialize, PartialEq)]
 pub struct BgpPeerStatus {
@@ -59,3 +79,172 @@ pub enum BgpPeerState {
     /// messages with peers.
     Established,
 }
+
+/// The type of IP address to attach to an instance during creation.
+#[derive(Clone, Debug, Deserialize, Serialize, JsonSchema)]
+#[serde(tag = "type", rename_all = "snake_case")]
+pub enum ExternalIpCreate {
+    /// An IP address providing both inbound and outbound access.
+    /// The address is automatically assigned from the provided IP pool
+    /// or the default IP pool if not specified.
+    Ephemeral {
+        /// Name or ID of the IP pool to use. If unspecified, the
+        /// default IP pool will be used.
+        pool: Option<external::NameOrId>,
+    },
+    /// A floating IP address.
+    Floating {
+        /// The name or ID of the floating IP address to attach.
+        floating_ip: external::NameOrId,
+    },
+}
+
+impl From<ExternalIpCreate> for v2026010300::ExternalIpCreate {
+    fn from(old: ExternalIpCreate) -> v2026010300::ExternalIpCreate {
+        match old {
+            ExternalIpCreate::Ephemeral { pool } => {
+                v2026010300::ExternalIpCreate::Ephemeral {
+                    pool,
+                    ip_version: None,
+                }
+            }
+            ExternalIpCreate::Floating { floating_ip } => {
+                v2026010300::ExternalIpCreate::Floating { floating_ip }
+            }
+        }
+    }
+}
+
+/// Create-time parameters for an `Instance`
+#[derive(Clone, Debug, Deserialize, Serialize, JsonSchema)]
+pub struct InstanceCreate {
+    #[serde(flatten)]
+    pub identity: external::IdentityMetadataCreateParams,
+    /// The number of vCPUs to be allocated to the instance
+    pub ncpus: external::InstanceCpuCount,
+    /// The amount of RAM (in bytes) to be allocated to the instance
+    pub memory: external::ByteCount,
+    /// The hostname to be assigned to the instance
+    pub hostname: external::Hostname,
+
+    /// User data for instance initialization systems (such as cloud-init).
+    /// Must be a Base64-encoded string, as specified in RFC 4648 § 4 (+ and /
+    /// characters with padding). Maximum 32 KiB unencoded data.
+    #[serde(default, with = "params::UserData")]
+    pub user_data: Vec<u8>,
+
+    /// The network interfaces to be created for this instance.
+    #[serde(default)]
+    pub network_interfaces: v2026010100::InstanceNetworkInterfaceAttachment,
+
+    /// The external IP addresses provided to this instance.
+    ///
+    /// 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.
+    #[serde(default)]
+    pub external_ips: Vec<ExternalIpCreate>,
+
+    /// The multicast groups this instance should join.
+    ///
+    /// The instance will be automatically added as a member of the specified
+    /// multicast groups during creation, enabling it to send and receive
+    /// multicast traffic for those groups.
+    #[serde(default)]
+    pub multicast_groups: Vec<external::NameOrId>,
+
+    /// A list of disks to be attached to the instance.
+    ///
+    /// Disk attachments of type "create" will be created, while those of type
+    /// "attach" must already exist.
+    ///
+    /// The order of this list does not guarantee a boot order for the instance.
+    /// Use the boot_disk attribute to specify a boot disk. When boot_disk is
+    /// specified it will count against the disk attachment limit.
+    #[serde(default)]
+    pub disks: Vec<params::InstanceDiskAttachment>,
+
+    /// The disk the instance is configured to boot from.
+    ///
+    /// This disk can either be attached if it already exists or created along
+    /// with the instance.
+    ///
+    /// Specifying a boot disk is optional but recommended to ensure predictable
+    /// boot behavior. The boot disk can be set during instance creation or
+    /// later if the instance is stopped. The boot disk counts against the disk
+    /// attachment limit.
+    ///
+    /// An instance that does not have a boot disk set will use the boot
+    /// options specified in its UEFI settings, which are controlled by both the
+    /// instance's UEFI firmware and the guest operating system. Boot options
+    /// can change as disks are attached and detached, which may result in an
+    /// instance that only boots to the EFI shell until a boot disk is set.
+    #[serde(default)]
+    pub boot_disk: Option<params::InstanceDiskAttachment>,
+
+    /// An allowlist of SSH public keys to be transferred to the instance via
+    /// cloud-init during instance creation.
+    ///
+    /// If not provided, all SSH public keys from the user's profile will be sent.
+    /// If an empty list is provided, no public keys will be transmitted to the
+    /// instance.
+    pub ssh_public_keys: Option<Vec<external::NameOrId>>,
+
+    /// Should this instance be started upon creation; true by default.
+    #[serde(default = "params::bool_true")]
+    pub start: bool,
+
+    /// The auto-restart policy for this instance.
+    ///
+    /// This policy determines whether the instance should be automatically
+    /// restarted by the control plane on failure. If this is `null`, no
+    /// auto-restart policy will be explicitly configured for this instance, and
+    /// the control plane will select the default policy when determining
+    /// whether the instance can be automatically restarted.
+    ///
+    /// Currently, the global default auto-restart policy is "best-effort", so
+    /// instances with `null` auto-restart policies will be automatically
+    /// restarted. However, in the future, the default policy may be
+    /// configurable through other mechanisms, such as on a per-project basis.
+    /// In that case, any configured default policy will be used if this is
+    /// `null`.
+    #[serde(default)]
+    pub auto_restart_policy: Option<external::InstanceAutoRestartPolicy>,
+
+    /// Anti-Affinity groups which this instance should be added.
+    #[serde(default)]
+    pub anti_affinity_groups: Vec<external::NameOrId>,
+
+    /// The CPU platform to be used for this instance. If this is `null`, the
+    /// instance requires no particular CPU platform; when it is started the
+    /// instance will have the most general CPU platform supported by the sled
+    /// it is initially placed on.
+    #[serde(default)]
+    pub cpu_platform: Option<external::InstanceCpuPlatform>,
+}
+
+impl From<InstanceCreate> for v2025122300::InstanceCreate {
+    fn from(old: InstanceCreate) -> v2025122300::InstanceCreate {
+        v2025122300::InstanceCreate {
+            identity: old.identity,
+            ncpus: old.ncpus,
+            memory: old.memory,
+            hostname: old.hostname,
+            user_data: old.user_data,
+            network_interfaces: old.network_interfaces,
+            external_ips: old
+                .external_ips
+                .into_iter()
+                .map(Into::into)
+                .collect(),
+            multicast_groups: old.multicast_groups,
+            disks: old.disks,
+            boot_disk: old.boot_disk,
+            ssh_public_keys: old.ssh_public_keys,
+            start: old.start,
+            auto_restart_policy: old.auto_restart_policy,
+            anti_affinity_groups: old.anti_affinity_groups,
+            cpu_platform: old.cpu_platform,
+        }
+    }
+}