[docs] post-merge doc/comment cleanup

Author: zeeshanlakhani

Cargo.lock

@@ -441,6 +441,11 @@ task: "physical_disk_adoption"
     ensure new physical disks are automatically marked in-service
 
 
+task: "populate_switch_ports"
+    one-time population of the `switch_port` table containing all QSFP ports
+    managed by dendrite
+
+
 task: "probe_distributor"
     distributes networking probe zones to sleds
 
@@ -656,7 +661,7 @@ task: "bfd_manager"
   configured period: every <REDACTED_DURATION>s
   last completed activation: <REDACTED ITERATIONS>, triggered by <TRIGGERED_BY_REDACTED>
     started at <REDACTED_TIMESTAMP> (<REDACTED DURATION>s ago) and ran for <REDACTED DURATION>ms
-    last completion reported error: failed to resolve addresses for Dendrite services: proto error: no records found for Query { name: Name("_mgs._tcp.control-plane.oxide.internal."), query_type: SRV, query_class: IN }
+    last completion reported error: proto error: no records found for Query { name: Name("_mgd._tcp.control-plane.oxide.internal."), query_type: SRV, query_class: IN }
 
 task: "blueprint_planner"
   configured period: every <REDACTED_DURATION>m
@@ -727,6 +732,7 @@ task: "fm_analysis"
     started at <REDACTED_TIMESTAMP> (<REDACTED DURATION>s ago) and ran for <REDACTED DURATION>ms
     parent sitrep ID:                None
     current inventory collection ID: Some(..........<REDACTED_UUID>........... (collection))
+    ereport classes consumed:        (none)
     FAULT MANAGEMENT ANALYSIS SUMMARY
     =================================
 /!\ analysis failed: FM analysis is not yet implemented
@@ -887,7 +893,15 @@ task: "physical_disk_adoption"
   configured period: every <REDACTED_DURATION>s
   last completed activation: <REDACTED ITERATIONS>, triggered by <TRIGGERED_BY_REDACTED>
     started at <REDACTED_TIMESTAMP> (<REDACTED DURATION>s ago) and ran for <REDACTED DURATION>ms
-    last completion reported error: task disabled
+physical disks added: 0
+/!\ task disabled
+
+task: "populate_switch_ports"
+  configured period: every <REDACTED_DURATION>s
+  last completed activation: <REDACTED ITERATIONS>, triggered by <TRIGGERED_BY_REDACTED>
+    started at <REDACTED_TIMESTAMP> (<REDACTED DURATION>s ago) and ran for <REDACTED DURATION>ms
+switch0 failed: failed to look up dendrite clients: proto error: no records found for Query { name: Name("_dendrite._tcp.control-plane.oxide.internal."), query_type: SRV, query_class: IN }
+switch1 failed: failed to look up dendrite clients: proto error: no records found for Query { name: Name("_dendrite._tcp.control-plane.oxide.internal."), query_type: SRV, query_class: IN }
 
 task: "probe_distributor"
   configured period: every <REDACTED_DURATION>m
@@ -1002,6 +1016,7 @@ task: "sp_ereport_ingester"
   configured period: every <REDACTED_DURATION>s
   last completed activation: <REDACTED ITERATIONS>, triggered by <TRIGGERED_BY_REDACTED>
     started at <REDACTED_TIMESTAMP> (<REDACTED DURATION>s ago) and ran for <REDACTED DURATION>ms
+    SPs found via ignition:       0
     total ereports received:      <TOTAL_EREPORTS_RECEIVED_REDACTED>
       new ereports ingested:      <NEW_EREPORTS_INGESTED_REDACTED>
     total HTTP requests sent:     <TOTAL_HTTP_REQUESTS_SENT_REDACTED>
@@ -1342,7 +1357,7 @@ task: "bfd_manager"
   configured period: every <REDACTED_DURATION>s
   last completed activation: <REDACTED ITERATIONS>, triggered by <TRIGGERED_BY_REDACTED>
     started at <REDACTED_TIMESTAMP> (<REDACTED DURATION>s ago) and ran for <REDACTED DURATION>ms
-    last completion reported error: failed to resolve addresses for Dendrite services: proto error: no records found for Query { name: Name("_mgs._tcp.control-plane.oxide.internal."), query_type: SRV, query_class: IN }
+    last completion reported error: proto error: no records found for Query { name: Name("_mgd._tcp.control-plane.oxide.internal."), query_type: SRV, query_class: IN }
 
 task: "blueprint_planner"
   configured period: every <REDACTED_DURATION>m
@@ -1413,6 +1428,7 @@ task: "fm_analysis"
     started at <REDACTED_TIMESTAMP> (<REDACTED DURATION>s ago) and ran for <REDACTED DURATION>ms
     parent sitrep ID:                None
     current inventory collection ID: Some(..........<REDACTED_UUID>........... (collection))
+    ereport classes consumed:        (none)
     FAULT MANAGEMENT ANALYSIS SUMMARY
     =================================
 /!\ analysis failed: FM analysis is not yet implemented
@@ -1573,7 +1589,15 @@ task: "physical_disk_adoption"
   configured period: every <REDACTED_DURATION>s
   last completed activation: <REDACTED ITERATIONS>, triggered by <TRIGGERED_BY_REDACTED>
     started at <REDACTED_TIMESTAMP> (<REDACTED DURATION>s ago) and ran for <REDACTED DURATION>ms
-    last completion reported error: task disabled
+physical disks added: 0
+/!\ task disabled
+
+task: "populate_switch_ports"
+  configured period: every <REDACTED_DURATION>s
+  last completed activation: <REDACTED ITERATIONS>, triggered by <TRIGGERED_BY_REDACTED>
+    started at <REDACTED_TIMESTAMP> (<REDACTED DURATION>s ago) and ran for <REDACTED DURATION>ms
+switch0 failed: failed to look up dendrite clients: proto error: no records found for Query { name: Name("_dendrite._tcp.control-plane.oxide.internal."), query_type: SRV, query_class: IN }
+switch1 failed: failed to look up dendrite clients: proto error: no records found for Query { name: Name("_dendrite._tcp.control-plane.oxide.internal."), query_type: SRV, query_class: IN }
 
 task: "probe_distributor"
   configured period: every <REDACTED_DURATION>m
@@ -1688,6 +1712,7 @@ task: "sp_ereport_ingester"
   configured period: every <REDACTED_DURATION>s
   last completed activation: <REDACTED ITERATIONS>, triggered by <TRIGGERED_BY_REDACTED>
     started at <REDACTED_TIMESTAMP> (<REDACTED DURATION>s ago) and ran for <REDACTED DURATION>ms
+    SPs found via ignition:       0
     total ereports received:      <TOTAL_EREPORTS_RECEIVED_REDACTED>
       new ereports ingested:      <NEW_EREPORTS_INGESTED_REDACTED>
     total HTTP requests sent:     <TOTAL_HTTP_REQUESTS_SENT_REDACTED>
@@ -1970,13 +1995,14 @@ parent:    <none>
     read from::   SingleNode
 
  METADATA:
-    created by:::::::::::::   nexus-test-utils
-    created at:::::::::::::   <REDACTED_TIMESTAMP>
-    comment::::::::::::::::   initial test blueprint
-    internal DNS version:::   1
-    external DNS version:::   2
-    target release min gen:   1
-    nexus gen::::::::::::::   1
+    created by::::::::::::::   nexus-test-utils
+    created at::::::::::::::   <REDACTED_TIMESTAMP>
+    comment:::::::::::::::::   initial test blueprint
+    internal DNS version::::   1
+    external DNS version::::   2
+    target release min gen::   1
+    nexus gen:::::::::::::::   1
+    external networking gen:   1
 
  PENDING MGS-MANAGED UPDATES: 0
 
@@ -2116,13 +2142,14 @@ parent:    <none>
     read from::   SingleNode
 
  METADATA:
-    created by:::::::::::::   nexus-test-utils
-    created at:::::::::::::   <REDACTED_TIMESTAMP>
-    comment::::::::::::::::   initial test blueprint
-    internal DNS version:::   1
-    external DNS version:::   2
-    target release min gen:   1
-    nexus gen::::::::::::::   1
+    created by::::::::::::::   nexus-test-utils
+    created at::::::::::::::   <REDACTED_TIMESTAMP>
+    comment:::::::::::::::::   initial test blueprint
+    internal DNS version::::   1
+    external DNS version::::   2
+    target release min gen::   1
+    nexus gen:::::::::::::::   1
+    external networking gen:   1
 
  PENDING MGS-MANAGED UPDATES: 0
 
@@ -2177,8 +2204,6 @@ Reconfigurator config:
     modified time: <REDACTED_TIMESTAMP>
     tuf repo pruner enabled: true
     planner enabled: false
-    planner config:
-        add zones with mupdate override:   false
 ---------------------------------------------
 stderr:
 note: using Nexus URL http://127.0.0.1:REDACTED_PORT/
@@ -2258,21 +2283,6 @@ stdout:
 reconfigurator config updated to version 2:
     tuf repo pruner enabled:   true (unchanged)
 *   planner enabled:::::::::   false -> true
-    planner config:
-        add zones with mupdate override:   false (unchanged)
----------------------------------------------
-stderr:
-note: using Nexus URL http://127.0.0.1:REDACTED_PORT/
-=============================================
-EXECUTING COMMAND: omdb ["-w", "nexus", "reconfigurator-config", "set", "--add-zones-with-mupdate-override", "true"]
-termination: Exited(0)
----------------------------------------------
-stdout:
-reconfigurator config updated to version 3:
-    tuf repo pruner enabled:   true (unchanged)
-    planner enabled:::::::::   true (unchanged)
-    planner config:
-    *   add zones with mupdate override:   false -> true
 ---------------------------------------------
 stderr:
 note: using Nexus URL http://127.0.0.1:REDACTED_PORT/
@@ -2282,12 +2292,10 @@ termination: Exited(0)
 ---------------------------------------------
 stdout:
 Reconfigurator config:
-    version: 3
+    version: 2
     modified time: <REDACTED_TIMESTAMP>
     tuf repo pruner enabled: true
     planner enabled: true
-    planner config:
-        add zones with mupdate override:   true
 ---------------------------------------------
 stderr:
 note: using Nexus URL http://127.0.0.1:REDACTED_PORT/

dev-tools/omdb/tests/successes.out

@@ -66,7 +66,7 @@
 //!   the dataplane (e.g., instance stopping/stopped, explicit detach, delete)
 //!
 //! Migration note: during instance migration, membership is reconfigured in
-//! place—the reconciler removes configuration from the old sled and applies it
+//! place; the reconciler removes configuration from the old sled and applies it
 //! on the new sled without transitioning the member to "Left". In other words,
 //! migration is not considered leaving; the member generally remains "Joined"
 //! while its `sled_id` and dataplane configuration are updated.

nexus/db-model/src/multicast_group.rs

@@ -699,15 +699,11 @@ impl MulticastGroupReconciler {
             }
         }
 
-        // TODO: Add front port selection for egress traffic (instances →
-        // external). When transitioning groups to Active, we need to identify
-        // and validate front ports against DPD's QSFP topology (similar to
-        // `backplane_map` validation for rear ports). These uplink members use
-        // `Direction::External` and follow a different lifecycle - added when
-        // first instance joins, removed when last instance leaves.
-        // Should integrate with `switch_ports_with_uplinks` or
-        // equivalent front port discovery mechanism, which would be
-        // configurable, and later learned (i.e., via `mcastd`/IGMP).
+        // TODO: Front port selection for egress (instance → external) is
+        // not yet implemented. See RFD 488 (§sect-external-mcast) for the
+        // design. Uplink members will use `Direction::External` and
+        // validate against DPD's QSFP topology rather than the
+        // `backplane_map` used for rear-port underlay members.
 
         // Handle underlay group creation/linking (same logic as before)
         if !self.process_creating_group_inner(opctx, group).await? {

nexus/src/app/background/tasks/multicast/groups.rs

@@ -54,7 +54,7 @@
 //! - **Extensible processing**: Support for different member types (designed for
 //!   future extension)
 //!
-//! ## Separation of Concerns: RPW +/- Sagas
+//! ## Separation of Concerns: RPW and Sagas
 //!
 //! **Sagas:**
 //! - Instance create/start → member "Joining" state
@@ -959,26 +959,6 @@ impl MulticastGroupReconciler {
                     "error" => %e
                 );
 
-                // TODO: Use DDM as the primary source of truth for sled→port
-                // mapping, with inventory as cross-validation.
-                //
-                // Currently we trust inventory (MGS/SP topology) for sled→port
-                // mapping. DDM (maghemite/ddmd) on switches has authoritative
-                // knowledge of which sleds are reachable on which ports.
-                //
-                // Future approach:
-                //   1. Query DDM for operational sled→port mapping
-                //      // TODO: Add GET /peers endpoint to ddm-admin-client
-                //      // returning Map<peer_addr, PeerInfo> where PeerInfo
-                //      // includes port/interface field (requires maghemite change)
-                //   2. Use DDM mapping as primary source for multicast routing
-                //   3. Cross-validate against inventory to detect mismatches
-                //   4. On mismatch: invalidate cache, log warning, potentially
-                //      trigger inventory reconciliation
-                //
-                // This catches cases where inventory is stale or a sled moved
-                // but inventory hasn't updated yet.
-
                 let updated = self
                     .datastore
                     .multicast_group_member_set_state_if_current(
@@ -1436,7 +1416,7 @@ impl MulticastGroupReconciler {
 
         // Propagate M2P mappings and forwarding entries to all sleds.
         //
-        // Athis point, the member is now "Joined" in the database, so propagate
+        // At this point, the member is now "Joined" in the database, so propagate
         // includes this sled in forwarding next-hops. If propagation or
         // subscribe fails below, the member remains "Joined" with incomplete
         // sled state. The reconciler's next pass converges via
@@ -1543,19 +1523,8 @@ impl MulticastGroupReconciler {
             );
         }
 
-        // TODO: Add uplink (front port) members for egress traffic through to
-        // Dendrite.
-        //
-        // When this is the first instance joining the group, we should also add
-        // uplink members with `Direction::External` for multicast egress
-        // traffic out of the rack.
-        // These uplink members follow a different lifecycle:
-        // - Added when first instance joins (check group member count)
-        // - Removed when last instance leaves (would be handled in
-        //   `remove_member_from_dataplane`)
-        //
-        // Uplink ports are probably going to be a group-level configuration
-        // added by external params.
+        // TODO: Uplink (front port) members for egress traffic are not yet
+        // added here. See RFD 488 (§sect-external-mcast) for the design.
 
         info!(
             opctx.log,
@@ -2144,7 +2113,7 @@ impl MulticastGroupReconciler {
             }
         };
 
-        // Only prune stale ports if we successfully resolved All "Joined" members.
+        // Only prune stale ports if we successfully resolved all "Joined" members.
         // If we could not compute active member ports or if some members failed
         // to resolve, avoid removing anything to prevent disrupting other members.
         // We'll still proceed to ensure adding expected ports for this member.
@@ -2688,27 +2657,6 @@ impl MulticastGroupReconciler {
         )
     }
 
-    /// Refresh the sled-to-switch-port mapping cache using inventory data.
-    ///
-    /// Maps each sled to its physical rear (backplane) port on the switch by:
-    /// 1. Getting sled's baseboard serial/part from the sled record
-    /// 2. Looking up the service processor (SP) in inventory for that baseboard
-    ///    (SP information is collected from MGS by the inventory collector)
-    /// 3. Using `sp.sp_slot` (cubby number) to determine the rear port identifier
-    /// 4. Creating `PortId::Rear(RearPort::try_from(format!("rear{sp_slot}")))`
-    ///
-    /// On the Dendrite side (switch's DPD daemon), a similar  mapping is performed:
-    ///
-    /// ```rust,ignore
-    /// // From dendrite/dpd/src/port_map.rs rev_ab_port_map()
-    /// for entry in SIDECAR_REV_AB_BACKPLANE_MAP.iter() {
-    ///     let port = PortId::Rear(RearPort::try_from(entry.cubby).unwrap());
-    ///     inner.insert(port, Connector::QSFP(entry.tofino_connector.into()));
-    /// }
-    /// ```
-    ///
-    /// Where `entry.cubby` is the physical cubby/slot number (same as our `sp_slot`),
-    /// and this maps it to a `PortId::Rear` that DPD can program on the Tofino ASIC.
     /// Fetch the sled-to-port mapping from DDM peer topology.
     ///
     /// DDM peers provide live sled-to-port mapping via the `if_name`
@@ -2921,10 +2869,11 @@ impl MulticastGroupReconciler {
 /// rejects any non-rear `PortId`. In production, a sled's only
 /// physical path to a switch is the rack backplane.
 ///
-/// TODO: Egress (uplink) members are not yet implemented. When they
-/// land, they will come from group-level configuration applied
-/// directly via DPD rather than from DDM peer discovery. See the
-/// `TODO` in [`MulticastGroupReconciler::add_member_to_dataplane`].
+/// TODO: Egress (uplink) members are not yet implemented. They will
+/// not arrive via DDM peer discovery (which only covers intra-rack
+/// underlay members); see RFD 488 (§sect-external-mcast) for the
+/// design and remaining work. See also the `TODO` in
+/// [`MulticastGroupReconciler::add_member_to_dataplane`].
 fn parse_ddm_if_name_to_port(if_name: &str) -> Option<SwitchBackplanePort> {
     use std::str::FromStr;
 

nexus/src/app/background/tasks/multicast/members.rs

@@ -20,7 +20,7 @@
 //! - Instance lifecycle (start/stop/migrate affecting group membership)
 //! - Network topology (sled-to-switch mappings, port configurations)
 //!
-//! ## Architecture: RPW +/- Sagas
+//! ## Architecture: RPW and Sagas
 //!
 //! **Sagas handle immediate operations:**
 //! - Instance lifecycle events (start/stop/delete)
@@ -99,7 +99,8 @@
 //! 4. **OPTE decapsulation** removes Geneve/IPv6/Ethernet outer headers on target sleds
 //! 5. **Instance delivery** of inner (guest-facing) packet to guest
 //!
-//! TODO: Other traffic flows like egress from instances will be documented separately.
+//! TODO: Egress (instance → external) is not yet supported. See RFD 488
+//! (§sect-external-mcast) for the design.
 //!
 //! ## Reconciliation Components
 //!
@@ -237,7 +238,7 @@ pub(crate) struct MulticastGroupReconciler {
     member_concurrency_limit: usize,
     /// Maximum number of groups to process concurrently.
     group_concurrency_limit: usize,
-    /// Whether multicast functionality is enabled (or not).
+    /// Whether multicast functionality is enabled.
     enabled: bool,
 }
 

nexus/src/app/background/tasks/multicast/mod.rs

@@ -131,16 +131,11 @@ pub(crate) type MulticastDataplaneResult<T> = Result<T, Error>;
 /// This handles multicast group and member operations across all switches
 /// in the rack, with automatic error handling and rollback.
 ///
-/// TODO: Add `switch_port_uplinks` configuration to multicast groups for egress
-/// multicast traffic (instances → switches → external hosts).
-///
-/// Current implementation handles ingress (external → switches → instances)
-/// using rear ports with [`dpd_client::types::Direction::Underlay`]. For egress,
-/// we need:
-/// - Group-level uplink configuration (which front ports to use)
-/// - Uplink members with [`dpd_client::types::Direction::External`] added to
-///   underlay groups
-/// - Integration with existing `switch_ports_with_uplinks` for port discovery
+/// TODO: Egress (instance → external) is not yet supported. The current
+/// implementation only handles ingress (external → switches → instances)
+/// using rear ports with [`dpd_client::types::Direction::Underlay`]. See
+/// RFD 488 (§sect-external-mcast) for the egress design, which will use
+/// front-port uplink members with [`dpd_client::types::Direction::External`].
 pub(crate) struct MulticastDataplaneClient {
     dpd_clients: HashMap<SwitchSlot, dpd_client::Client>,
     log: Logger,

nexus/src/app/multicast/dataplane.rs

@@ -44,9 +44,10 @@ use crate::app::switch_zone_targets;
 /// so this client's direct-to-MGD path is intentional and should be preserved
 /// by the migration.
 ///
-/// If a future iteration tightens around  MRIB writes, the
-/// reconciler logic stays in Nexus and only the wire surface changes
-/// (Nexus calls a sled-agent endpoint that fronts MGD).
+/// If a follow-on to omicron#10167 routes MRIB writes through
+/// sled-agent, the reconciler logic stays in Nexus and only the wire
+/// surface changes: Nexus would call a sled-agent endpoint that fronts
+/// MGD instead of MGD directly.
 ///
 /// [`MulticastDataplaneClient`]: super::dataplane::MulticastDataplaneClient
 /// [omicron#10167]: https://github.com/oxidecomputer/omicron/issues/10167