docs(switch): clarify mTLS service selection

crates/api-core/src/cfg/README.md

@@ -75,9 +75,9 @@ Use `site_explorer.dpu_policy` instead.
 | `vpc_prefix_state_controller` | `VpcPrefixStateControllerConfig` | *(see below)* | `networking` | VPC prefix state controller timing. |
 | `ib_partition_state_controller` | `IbPartitionStateControllerConfig` | *(see below)* | `hardware` | IB partition state controller timing. |
 | `dpa_interface_state_controller` | `DpaInterfaceStateControllerConfig` | *(see below)* | `networking` | DPA interface state controller timing. |
-| `rack_state_controller` | `RackStateControllerConfig` | *(see below)* | `hardware` | Rack state controller timing and optional firmware update during ingestion. |
+| `rack_state_controller` | `RackStateControllerConfig` | *(see below)* | `hardware` | Rack state controller timing, optional ingestion firmware update, and primary-switch mTLS service selection. |
 | `power_shelf_state_controller` | `PowerShelfStateControllerConfig` | *(see below)* | `hardware` | Power shelf state controller timing and optional rack firmware reprovisioning. |
-| `switch_state_controller` | `SwitchStateControllerConfig` | *(see below)* | `hardware` | Switch state controller timing. |
+| `switch_state_controller` | `SwitchStateControllerConfig` | *(see below)* | `hardware` | Switch state controller timing and per-switch mTLS service selection. |
 | `spdm_state_controller` | `SpdmStateControllerConfig` | *(see below)* | `security` | SPDM state controller timing. |
 | `host_models` | `HashMap<String, Firmware>` | `{}` | `machines` | Maps host model identifiers to firmware definitions. |
 | `firmware_global` | `FirmwareGlobal` | *(see below)* | `machines` | Global firmware update settings (see [FirmwareGlobal](#firmwareglobal)). |
@@ -440,6 +440,37 @@ partition, DPA interface, rack, power shelf, switch, SPDM).
 | `metric_emission_interval` | `Duration` | `60s` | How often aggregate metrics are recalculated. |
 | `metric_hold_time` | `Duration` | `5m` | How long per-object metrics are held before eviction. |
 
+### `RackStateControllerConfig`
+
+TOML section: `[rack_state_controller]`.
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `controller` | `StateControllerConfig` | *(default)* | Common state controller timing (see [StateControllerConfig](#statecontrollerconfig)). |
+| `nmx_cluster_switch_mtls_services` | `Vec<SwitchMtlsService>` | `scale_up_fabric_manager`, `scale_up_fabric_telemetry_interface` | mTLS certificate bindings applied to the primary switch before NMX cluster setup. A non-empty list replaces the default. Omission and `[]` both use the default. |
+
+### `SwitchStateControllerConfig`
+
+TOML section: `[switch_state_controller]`.
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `controller` | `StateControllerConfig` | *(default)* | Common state controller timing (see [StateControllerConfig](#statecontrollerconfig)). |
+| `switch_mtls_services` | `Vec<SwitchMtlsService>` | all four values below | mTLS certificate bindings applied by the per-switch certificate workflow. A non-empty list replaces the default. Omission and `[]` both use the default. |
+
+Both settings accept the same service names:
+
+| Value | Switch endpoint |
+|-------|-----------------|
+| `nvue_api` | NVUE REST API |
+| `scale_up_fabric_telemetry` | NMX-T cluster application (`nmx-telemetry`) |
+| `scale_up_fabric_manager` | NMX-C cluster application (`nmx-controller`) |
+| `scale_up_fabric_telemetry_interface` | NVOS gNMI server mTLS configuration |
+
+These lists select server-side certificate bindings. They do not enable the
+underlying service. For workflow scope, see
+[Switch Certificate Configuration](../../../../docs/architecture/state_machines/switch_configure_certificate.md).
+
 ### `ObservabilityConfig`
 
 TOML section: `[observability]`.

deploy/nico-base/api/config-files/carbide-api-config.toml

@@ -117,13 +117,13 @@ test_selection_mode = "EnableAll"
 
 # Per-site [component_manager] configures switch and power shelf backends.
 
-# Per-site [switch_state_controller] can configure switch_mtls_services, the
-# RMS SwitchService list passed by the switch state machine during certificate
-# configuration. When omitted, all supported services are used: nvue_api,
-# scale_up_fabric_telemetry, scale_up_fabric_manager,
-# scale_up_fabric_telemetry_interface.
-
-# Per-site [rack_state_controller] can configure nmx_cluster_switch_mtls_services,
-# the RMS SwitchService list passed during NMX cluster certificate configuration.
-# When omitted, scale_up_fabric_manager and scale_up_fabric_telemetry_interface
-# are used.
+# Optional per-site mTLS certificate bindings:
+# - [switch_state_controller].switch_mtls_services applies to each switch and
+#   defaults to all four SwitchMtlsService values.
+# - [rack_state_controller].nmx_cluster_switch_mtls_services applies to the
+#   primary switch and defaults to scale_up_fabric_manager and
+#   scale_up_fabric_telemetry_interface.
+# A non-empty list replaces its default; an omitted or empty list uses it.
+# Service selection does not enable the underlying service. See
+# docs/architecture/state_machines/switch_configure_certificate.md for service
+# values and workflow scope.

docs/architecture/state_machines/switch_configure_certificate.md

@@ -54,7 +54,7 @@ component manager while polling) transitions to `Error`.
 Job status values use `ConfigureSwitchCertificateState`: `Started`,
 `InProgress`, `Completed`, `Failed`.
 
-## Domain name (`domain_name`) and mTLS services
+## Domain name (`domain_name`) and mTLS service selection
 
 The switch state handler passes:
 
@@ -63,7 +63,27 @@ The switch state handler passes:
   when deciding whether certificate configuration can run.
 - `services` from `SwitchStateHandlerServices.switch_mtls_services`, sourced
   from `[switch_state_controller].switch_mtls_services` in site config. When
-  omitted or empty, all supported switch mTLS services are used.
+  omitted or empty, all four service values are used.
+
+NICo has two independent mTLS service lists:
+
+| Setting | Workflow and target | Omitted or empty behavior |
+|---------|---------------------|---------------------------|
+| `[switch_state_controller].switch_mtls_services` | Per-switch certificate configuration for every switch handled by the switch state controller. | Uses all four service values. |
+| `[rack_state_controller].nmx_cluster_switch_mtls_services` | Rack certificate configuration on the primary switch before NMX cluster setup. | Uses `scale_up_fabric_manager` and `scale_up_fabric_telemetry_interface`. |
+
+A non-empty list replaces the corresponding default. Omission or an empty list
+uses the default.
+
+| Service value | Binding target |
+|---------------|----------------|
+| `nvue_api` | NVUE REST API |
+| `scale_up_fabric_telemetry` | NMX-T cluster application (`nmx-telemetry`) |
+| `scale_up_fabric_manager` | NMX-C cluster application (`nmx-controller`) |
+| `scale_up_fabric_telemetry_interface` | NVOS gNMI server mTLS configuration |
+
+Service selection requests certificate bindings; it does not enable the
+underlying service. The target switch build must support each selected binding.
 
 | Condition | Behavior |
 |-----------|----------|
@@ -77,9 +97,7 @@ The switch state handler passes:
 | RMS job status is `Failed` | Transition to `Error` with the job error message. |
 | Component manager not configured while polling | Transition to `Error` (no job ID to resume). |
 
-Rack NMX cluster maintenance uses a separate service list:
-`[rack_state_controller].nmx_cluster_switch_mtls_services` (defaults to
-ScaleUpFabric manager and telemetry interface services). See
+Rack NMX cluster maintenance is documented in
 [Rack State Machine](rackstatemachine.md).
 
 ## Component Manager API