[api] Add endpoint to list external subnets attached to an instance (#9755)

## Summary

Adds `GET /v1/instances/{instance}/external-subnets` which returns all
external subnets currently attached to the specified instance.

## Changes

**Datastore layer**
(`nexus/db-queries/src/db/datastore/external_subnet.rs`):
- Add `instance_lookup_external_subnets()` function
- Authz check (`Action::Read` on instance) performed in datastore, close
to the SQL query
- Results ordered by ID for deterministic output
- Filters to only return attached, non-deleted subnets

**App layer** (`nexus/src/app/external_subnet.rs`):
- Add `instance_list_external_subnets()` function
- Additional authz check for `Action::ListChildren` on project (external
subnets are project-scoped)

**HTTP layer** (`nexus/src/external_api/http_entrypoints.rs`):
- Add `instance_external_subnet_list` handler
- No pagination (expect small number of attached subnets per instance;
TODO to add max limit)

**Tests**:
- Add `test_instance_external_subnet_list_empty` integration test
- Add endpoint to `endpoints.rs` for `test_unauthorized` coverage

## Test plan

- [x] `cargo nextest run -p omicron-nexus -E
'test(=integration_tests::unauthorized::test_unauthorized)'`
- [x] `cargo nextest run -p omicron-nexus -E
'test(=integration_tests::external_subnets::test_instance_external_subnet_list_empty)'`

Author: mergeconflict

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

@@ -31,6 +31,7 @@ use nexus_db_lookup::lookup;
 use nexus_db_model::ExternalSubnet;
 use nexus_db_model::ExternalSubnetIdentity;
 use nexus_db_model::ExternalSubnetUpdate;
+use nexus_db_model::IpAttachState;
 use nexus_db_model::IpNet;
 use nexus_db_model::IpVersion;
 use nexus_db_model::Name;
@@ -509,6 +510,25 @@ impl DataStore {
                 }
             })
     }
+
+    /// Fetch all external subnets attached to the provided instance.
+    pub async fn instance_lookup_external_subnets(
+        &self,
+        opctx: &OpContext,
+        authz_instance: &authz::Instance,
+    ) -> ListResultVec<ExternalSubnet> {
+        opctx.authorize(authz::Action::Read, authz_instance).await?;
+        use nexus_db_schema::schema::external_subnet::dsl;
+        dsl::external_subnet
+            .filter(dsl::instance_id.eq(authz_instance.id()))
+            .filter(dsl::time_deleted.is_null())
+            .filter(dsl::attach_state.eq(IpAttachState::Attached))
+            .order_by(dsl::id)
+            .select(ExternalSubnet::as_select())
+            .get_results_async(&*self.pool_connection_authorized(opctx).await?)
+            .await
+            .map_err(|e| public_error_from_diesel(e, ErrorHandler::Server))
+    }
 }
 
 #[cfg(test)]

nexus/external-api/output/nexus_tags.txt

@@ -113,6 +113,7 @@ instance_disk_list                       GET      /v1/instances/{instance}/disks
 instance_ephemeral_ip_attach             POST     /v1/instances/{instance}/external-ips/ephemeral
 instance_ephemeral_ip_detach             DELETE   /v1/instances/{instance}/external-ips/ephemeral
 instance_external_ip_list                GET      /v1/instances/{instance}/external-ips
+instance_external_subnet_list            GET      /v1/instances/{instance}/external-subnets
 instance_list                            GET      /v1/instances
 instance_network_interface_create        POST     /v1/network-interfaces
 instance_network_interface_delete        DELETE   /v1/network-interfaces/{interface}

nexus/external-api/src/lib.rs

@@ -77,6 +77,7 @@ api_versions!([
     // |  date-based version should be at the top of the list.
     // v
     // (next_yyyymmddnn, IDENT),
+    (2026013000, INSTANCES_EXTERNAL_SUBNETS),
     (2026012800, REMOVE_SUBNET_POOL_POOL_TYPE),
     (2026012300, DUAL_STACK_EPHEMERAL_IP),
     (2026012201, EXTERNAL_SUBNET_ALLOCATOR_UPDATE),
@@ -3904,6 +3905,21 @@ pub trait NexusExternalApi {
         query_params: Query<params::EphemeralIpDetachSelector>,
     ) -> Result<HttpResponseDeleted, HttpError>;
 
+    // Instance External Subnets
+
+    /// List external subnets attached to instance
+    #[endpoint {
+        method = GET,
+        path = "/v1/instances/{instance}/external-subnets",
+        tags = ["instances"],
+        versions = VERSION_INSTANCES_EXTERNAL_SUBNETS..,
+    }]
+    async fn instance_external_subnet_list(
+        rqctx: RequestContext<Self::Context>,
+        query_params: Query<params::OptionalProjectSelector>,
+        path_params: Path<params::InstancePath>,
+    ) -> Result<HttpResponseOk<ResultsPage<views::ExternalSubnet>>, HttpError>;
+
     // Instance Multicast Groups
 
     /// List multicast groups for an instance

nexus/src/app/external_subnet.rs

@@ -150,4 +150,24 @@ impl super::Nexus {
             .unimplemented_todo(opctx, Unimpl::ProtectedLookup(not_found))
             .await)
     }
+
+    pub(crate) async fn instance_list_external_subnets(
+        &self,
+        opctx: &OpContext,
+        instance_lookup: &lookup::Instance<'_>,
+    ) -> ListResultVec<views::ExternalSubnet> {
+        let (.., authz_project, authz_instance) =
+            instance_lookup.lookup_for(authz::Action::Read).await?;
+
+        // External subnets are project-scoped, so check ListChildren on project
+        opctx.authorize(authz::Action::ListChildren, &authz_project).await?;
+
+        Ok(self
+            .db_datastore
+            .instance_lookup_external_subnets(opctx, &authz_instance)
+            .await?
+            .into_iter()
+            .map(|subnet| subnet.into())
+            .collect())
+    }
 }

nexus/src/external_api/http_entrypoints.rs

@@ -4918,6 +4918,43 @@ impl NexusExternalApi for NexusExternalApiImpl {
         .await
     }
 
+    // Instance External Subnets
+
+    async fn instance_external_subnet_list(
+        rqctx: RequestContext<ApiContext>,
+        query_params: Query<params::OptionalProjectSelector>,
+        path_params: Path<params::InstancePath>,
+    ) -> Result<HttpResponseOk<ResultsPage<views::ExternalSubnet>>, HttpError>
+    {
+        let apictx = rqctx.context();
+        let handler = async {
+            let nexus = &apictx.context.nexus;
+            let path = path_params.into_inner();
+            let query = query_params.into_inner();
+            let opctx =
+                crate::context::op_context_for_external_api(&rqctx).await?;
+            let instance_selector = params::InstanceSelector {
+                project: query.project,
+                instance: path.instance,
+            };
+            let instance_lookup =
+                nexus.instance_lookup(&opctx, instance_selector)?;
+            let subnets = nexus
+                .instance_list_external_subnets(&opctx, &instance_lookup)
+                .await?;
+            // The number of external subnets attached to an instance is expected
+            // to be small, so pagination is not implemented.
+            // TODO: Add MAX_EXTERNAL_SUBNETS_PER_INSTANCE constant (similar to
+            // MAX_EXTERNAL_IPS_PER_INSTANCE) and enforce it in attach operations.
+            Ok(HttpResponseOk(ResultsPage { items: subnets, next_page: None }))
+        };
+        apictx
+            .context
+            .external_latencies
+            .instrument_dropshot_handler(&rqctx, handler)
+            .await
+    }
+
     // Instance Multicast Groups
 
     async fn instance_multicast_group_list(

nexus/tests/integration_tests/endpoints.rs

@@ -654,6 +654,13 @@ pub static DEMO_INSTANCE_EXTERNAL_IPS_URL: LazyLock<String> =
             *DEMO_INSTANCE_NAME, *DEMO_PROJECT_SELECTOR
         )
     });
+pub static DEMO_INSTANCE_EXTERNAL_SUBNETS_URL: LazyLock<String> =
+    LazyLock::new(|| {
+        format!(
+            "/v1/instances/{}/external-subnets?{}",
+            *DEMO_INSTANCE_NAME, *DEMO_PROJECT_SELECTOR
+        )
+    });
 pub static DEMO_INSTANCE_CREATE: LazyLock<params::InstanceCreate> =
     LazyLock::new(|| params::InstanceCreate {
         identity: IdentityMetadataCreateParams {
@@ -2730,6 +2737,13 @@ pub static VERIFY_ENDPOINTS: LazyLock<Vec<VerifyEndpoint>> = LazyLock::new(
                 unprivileged_access: UnprivilegedAccess::None,
                 allowed_methods: vec![AllowedMethod::Get],
             },
+            /* Instance external subnets */
+            VerifyEndpoint {
+                url: &DEMO_INSTANCE_EXTERNAL_SUBNETS_URL,
+                visibility: Visibility::Protected,
+                unprivileged_access: UnprivilegedAccess::None,
+                allowed_methods: vec![AllowedMethod::Get],
+            },
             VerifyEndpoint {
                 url: &DEMO_INSTANCE_EPHEMERAL_IP_URL,
                 visibility: Visibility::Protected,

nexus/tests/integration_tests/external_subnets.rs

@@ -14,9 +14,13 @@ use http::Method;
 use http::StatusCode;
 use nexus_test_utils::http_testing::AuthnMode;
 use nexus_test_utils::http_testing::NexusRequest;
+use nexus_test_utils::resource_helpers::create_default_ip_pools;
+use nexus_test_utils::resource_helpers::create_instance;
 use nexus_test_utils::resource_helpers::create_project;
+use nexus_test_utils::resource_helpers::objects_list_page_authz;
 use nexus_test_utils_macros::nexus_test;
 use nexus_types::external_api::params;
+use nexus_types::external_api::views;
 use omicron_common::api::external::IdentityMetadataCreateParams;
 
 type ControlPlaneTestContext =
@@ -44,6 +48,10 @@ fn external_subnet_detach_url(name: &str, project: &str) -> String {
     format!("/v1/external-subnets/{}/detach?project={}", name, project)
 }
 
+fn instance_external_subnets_url(instance: &str, project: &str) -> String {
+    format!("/v1/instances/{}/external-subnets?project={}", instance, project)
+}
+
 #[nexus_test]
 async fn test_external_subnet_list_unimplemented(
     cptestctx: &ControlPlaneTestContext,
@@ -215,3 +223,25 @@ async fn test_external_subnet_detach_unimplemented(
     .await
     .expect("failed to make request");
 }
+
+const INSTANCE_NAME: &str = "test-instance";
+
+#[nexus_test]
+async fn test_instance_external_subnet_list_empty(
+    cptestctx: &ControlPlaneTestContext,
+) {
+    let client = &cptestctx.external_client;
+
+    // Create default IP pools, project, and instance
+    create_default_ip_pools(client).await;
+    let _ = create_project(client, PROJECT_NAME).await;
+    let _ = create_instance(client, PROJECT_NAME, INSTANCE_NAME).await;
+
+    // List external subnets for the instance - should return empty list
+    let subnets = objects_list_page_authz::<views::ExternalSubnet>(
+        client,
+        &instance_external_subnets_url(INSTANCE_NAME, PROJECT_NAME),
+    )
+    .await;
+    assert!(subnets.items.is_empty());
+}