Merge pull request #2311 from sthaha/feat-redfish-better-api

refactor(redfish): enhance power reading with PowerSubsystem API support

Author: Sunil Thaha

docs/developer/proposal/EP_001-redfish-support.md

@@ -4,7 +4,7 @@
 - **Maturity**: Experimental
 - **Author**: Sunil Thaha
 - **Created**: 2025-08-14
-- **Updated**: 2025-08-28
+- **Updated**: 2025-09-03
 
 ## Summary
 
@@ -124,12 +124,16 @@ Implements standard Kepler patterns:
 
 ### Implementation Details
 
-**Simplified On-Demand Architecture with Caching:**
+**Hybrid PowerSubsystem with Power API Fallback Architecture:**
 
-- `Power()`: synchronous method returning detailed PowerControl readings from all chassis
+- `Power()`: synchronous method returning power readings from all chassis with automatic API selection
+- **Primary**: Modern Redfish PowerSubsystem API (PowerSupplies collection)
+- **Fallback**: Deprecated Power API (PowerControl array) for backward compatibility
+- Automatic fallback when PowerSubsystem is unavailable or returns errors
 - Simple staleness-based caching to reduce BMC API calls
-- Individual PowerControl entry exposure with detailed labeling (chassis_id, power_control_id, power_control_name)
+- Individual power source exposure with generic labeling (chassis_id, source_id, source_name, source_type)
 - BMC API calls only when cached data is stale or unavailable
+- Source type differentiation enables clear identification of API used
 
 **Service Lifecycle:**
 
@@ -223,17 +227,17 @@ The Redfish service implements a **on-demand collection with caching**:
 - Implements simple caching with staleness-based expiration to
  support multiple Prometheus scrapes in a short period (High Availability)
 - Returns cached data if available and fresh, otherwise collects fresh data
-- Returns all chassis with detailed PowerControl readings in a single call
-- Each PowerControl entry identified by `chassis_id`, `power_control_id`, and `power_control_name` for granular metric labeling
+- Returns all chassis with detailed power supply readings in a single call via PowerSubsystem
+- Each power supply entry identified by `chassis_id`, `source_id`, and `source_name` for granular metric labeling
 
-### Multiple Chassis and PowerControl Support
+### Multiple Chassis and PowerSupply Support
 
-- `Power()` method returns `*PowerReading` (single reading containing multiple chassis with detailed PowerControl data)
-- `PowerReading` struct contains `[]Chassis` slice, each with `ID` and `[]Reading` for individual PowerControl entries
-- Iterates through all available chassis on the BMC and their PowerControl arrays
-- Filters and returns only PowerControl entries with valid power readings
-- Each reading includes `ControlID`, `Name`, and `Power` for granular power domain monitoring
-- Exposes individual PowerControl entries as separate metrics (e.g., Server Power Control, CPU Sub-system Power, Memory Power)
+- `Power()` method returns `*PowerReading` (single reading containing multiple chassis with detailed power supply data via PowerSubsystem)
+- `PowerReading` struct contains `[]Chassis` slice, each with `ID` and `[]Reading` for individual power supply entries
+- Iterates through all available chassis on the BMC and their PowerSubsystem → PowerSupplies arrays
+- Filters and returns only power supply entries with valid power output readings
+- Each reading includes `SourceID`, `SourceName`, and `Power` for granular power supply monitoring
+- Exposes individual power supply entries as separate metrics (e.g., Power Supply 1, Power Supply 2, Power Supply Bay 1)
 
 ## Metrics
 
@@ -243,17 +247,17 @@ to workloads running on a node, platform metrics represent individual power doma
 the underlying bare metal server (via BMC), regardless of whether Kepler runs on bare
 metal or within a VM.
 
-**PowerControl Granularity**: Each PowerControl entry from the BMC's PowerControl array is
-exposed as an individual metric with detailed labels. This approach avoids making assumptions
-about power topology (whether PowerControl entries should be summed or represent independent
-power domains) and allows users to understand their specific hardware's power structure.
+**PowerSupply Granularity**: Each power supply from the BMC's PowerSubsystem → PowerSupplies collection is
+exposed as an individual metric with detailed labels. This approach provides direct visibility into
+individual power supply output and allows users to understand their hardware's power supply topology
+and redundancy configuration.
 
 This separation enables:
 
 - Multiple VMs on the same bare metal to report the same platform power
-- Clear distinction between attributed workload power and platform power domains
-- Granular monitoring of power subsystems (CPU, memory, storage, etc.)
-- Flexible aggregation based on understanding of specific hardware topology
+- Clear distinction between attributed workload power and platform power supplies
+- Granular monitoring of individual power supplies and their redundancy status
+- Direct visibility into power supply efficiency and utilization
 
 **Important**: This implementation uses a **power-only (Watts) approach**.
 Energy counters (`kepler_platform_joules_total`) are not supported because:
@@ -262,10 +266,14 @@ Energy counters (`kepler_platform_joules_total`) are not supported because:
 - Collection frequency varies based on demand and configuration
 
 ```prometheus
-# Platform power metrics (bare metal power consumption) - individual PowerControl entries exposed
-kepler_platform_watts{source="redfish",node_name="worker-1",bmc_id="bmc-1",chassis_id="System.Embedded.1",power_control_id="PC1",power_control_name="Server Power Control"} 450.5
-kepler_platform_watts{source="redfish",node_name="worker-1",bmc_id="bmc-1",chassis_id="System.Embedded.1",power_control_id="PC2",power_control_name="CPU Sub-system Power"} 85.2
-kepler_platform_watts{source="redfish",node_name="worker-1",bmc_id="bmc-1",chassis_id="Enclosure.Internal.0-1",power_control_id="PC1",power_control_name="Enclosure Power Control"} 125.3
+# Platform power metrics (bare metal power consumption) - hybrid API approach with source_type differentiation
+
+# Modern PowerSubsystem API (PowerSupplies)
+kepler_platform_watts{source="redfish",node_name="worker-1",bmc_id="bmc-1",chassis_id="System.Embedded.1",source_id="PS1",source_name="Power Supply 1",source_type="PowerSupply"} 245.0
+kepler_platform_watts{source="redfish",node_name="worker-1",bmc_id="bmc-1",chassis_id="System.Embedded.1",source_id="PS2",source_name="Power Supply 2",source_type="PowerSupply"} 0.0
+
+# Fallback Power API (PowerControl) when PowerSubsystem unavailable
+kepler_platform_watts{source="redfish",node_name="worker-1",bmc_id="bmc-1",chassis_id="System.Embedded.1",source_id="0",source_name="System Power Control",source_type="PowerControl"} 189.5
 
 # Existing node metrics unchanged (workload attribution)
 kepler_node_cpu_watts{zone="package",node_name="worker-1"} 125.2
@@ -289,12 +297,14 @@ kepler_node_cpu_watts{zone="package",node_name="worker-1"} 125.2
 
 **✅ Implemented and Available (Experimental):**
 
-1. **Core**: Full Gofish integration with simplified on-demand power collection and service interfaces
-2. **Metrics**: Platform collector integrated with Prometheus exporter
-3. **Configuration**: CLI flags and YAML configuration with automatic node ID resolution
-4. **Testing**: Unit tests with mock server covering multiple vendor scenarios
-5. **Caching**: Staleness-based caching to reduce BMC API calls
-6. **Multiple Chassis and PowerControl**: Support for collecting detailed power data from all chassis and individual PowerControl entries
+1. **Core**: Full Gofish integration with hybrid PowerSubsystem/Power API collection and service interfaces
+2. **API Hybrid Approach**: PowerSubsystem API (modern) with automatic fallback to Power API (deprecated) for backward compatibility
+3. **Metrics**: Platform collector with generic source_id/source_name/source_type labels for power data
+4. **Configuration**: CLI flags and YAML configuration with automatic node ID resolution
+5. **Testing**: Unit tests with mock server including PowerSubsystem, Power API, and fallback scenarios
+6. **Caching**: Staleness-based caching to reduce BMC API calls
+7. **Multiple Chassis and Sources**: Support for collecting detailed power data from all chassis via both APIs with source differentiation
+8. **Fallback Logic**: Automatic detection and fallback when PowerSubsystem is unavailable
 
 **Current State:**
 
@@ -314,13 +324,16 @@ kepler_node_cpu_watts{zone="package",node_name="worker-1"} 125.2
 
 **Implemented Testing:**
 
-- **Unit tests**: Full test coverage with mocked Redfish responses
-- **Mock server**: HTTP server simulating BMC Redfish API endpoints for different vendors
-- **Multi-vendor scenarios**: Dell, HPE, Lenovo, and Generic response variations
-- **Error conditions**: Connection failures, authentication errors, timeouts, missing chassis
+- **Unit tests**: Full test coverage with mocked PowerSubsystem and Power API responses
+- **Mock server**: HTTP server simulating BMC Redfish PowerSubsystem and Power API endpoints for different vendors
+- **PowerSupply fixtures**: Dell, HPE, Lenovo PowerSupply collection response variations
+- **PowerControl fixtures**: PowerControl array response variations for fallback testing
+- **Fallback scenarios**: Comprehensive testing of PowerSubsystem → Power API fallback logic
+- **Error conditions**: Connection failures, authentication errors, timeouts, missing chassis/power supplies/power subsystems
+- **Source type validation**: Testing proper source_type assignment for PowerSupply vs PowerControl
 - **Concurrency testing**: Race detection and thread safety validation
 - **Caching behavior**: Staleness-based caching and cache expiry testing
-- **Service lifecycle**: Complete Init, ChassisPower, and Shutdown testing
+- **Service lifecycle**: Complete Init, Power (hybrid approach), and Shutdown testing
 
 **Testing Infrastructure:**
 
@@ -375,7 +388,8 @@ kepler_node_cpu_watts{zone="package",node_name="worker-1"} 125.2
 - Power-only metrics (no energy counters due to intermittent BMC polling)
 - Basic staleness-based caching (more advanced cache management could be added)
 - BMC calls during Prometheus scrape when cache is stale (mitigated by built-in caching)
-- Tested with mock servers (Dell, HPE, Lenovo, Generic scenarios)
+- Optimal for modern Redfish implementations with PowerSubsystem support (gracefully falls back to deprecated Power API)
+- Tested with mock servers simulating both PowerSubsystem and Power API scenarios
 
 ## Future Enhancements
 

docs/user/metrics.md

@@ -263,14 +263,15 @@ These experimental metrics provide platform-level power information from BMC sou
 #### kepler_platform_watts
 
 - **Type**: GAUGE
-- **Description**: Current platform power consumption in watts from BMC PowerControl entries
+- **Description**: Current platform power in watts from BMC (PowerSubsystem or deprecated Power API)
 - **Labels**:
   - `source`
   - `node_name`
   - `bmc_id`
   - `chassis_id`
-  - `power_control_id`
-  - `power_control_name`
+  - `source_id`
+  - `source_name`
+  - `source_type`
 
 ---
 

go.mod

@@ -14,7 +14,7 @@ require (
 	github.com/prometheus/client_model v0.6.1
 	github.com/prometheus/exporter-toolkit v0.14.0
 	github.com/prometheus/procfs v0.15.1
-	github.com/stmcginnis/gofish v0.15.0
+	github.com/stmcginnis/gofish v0.20.0
 	github.com/stretchr/testify v1.10.0
 	go.uber.org/zap v1.26.0
 	golang.org/x/sync v0.12.0

go.sum

@@ -135,8 +135,8 @@ github.com/rogpeppe/go-internal v1.12.0 h1:exVL4IDcn6na9z1rAb56Vxr+CgyK3nn3O+epU
 github.com/rogpeppe/go-internal v1.12.0/go.mod h1:E+RYuTGaKKdloAfM02xzb0FW3Paa99yedzYV+kq4uf4=
 github.com/spf13/pflag v1.0.5 h1:iy+VFUOCP1a+8yFto/drg2CJ5u0yRoB7fZw3DKv/JXA=
 github.com/spf13/pflag v1.0.5/go.mod h1:McXfInJRrz4CZXVZOBLb0bTZqETkiAhM9Iw0y3An2Bg=
-github.com/stmcginnis/gofish v0.15.0 h1:8TG41+lvJk/0Nf8CIIYErxbMlQUy80W0JFRZP3Ld82A=
-github.com/stmcginnis/gofish v0.15.0/go.mod h1:BLDSFTp8pDlf/xDbLZa+F7f7eW0E/CHCboggsu8CznI=
+github.com/stmcginnis/gofish v0.20.0 h1:hH2V2Qe898F2wWT1loApnkDUrXXiLKqbSlMaH3Y1n08=
+github.com/stmcginnis/gofish v0.20.0/go.mod h1:PzF5i8ecRG9A2ol8XT64npKUunyraJ+7t0kYMpQAtqU=
 github.com/stretchr/objx v0.1.0/go.mod h1:HFkY916IF+rwdDfMAkV7OtwuqBVzrE8GR6GFx+wExME=
 github.com/stretchr/objx v0.4.0/go.mod h1:YvHI0jy2hoMjB+UWwv71VJQ9isScKT/TqJzVSSt89Yw=
 github.com/stretchr/objx v0.5.0/go.mod h1:Yh+to48EsGEfYuaHDzXPcE3xhTkx73EhmCGUpEOglKo=

hack/gen-metric-docs/main.go

@@ -66,24 +66,27 @@ func (m *MockRedfishService) Power() (*redfish.PowerReading, error) {
 				ID: "System.Embedded.1",
 				Readings: []redfish.Reading{
 					{
-						ControlID: "PC1",
-						Name:      "System Power Control",
-						Power:     245.0 * device.Watt, // Dell 245W scenario
+						SourceID:   "PC1",
+						SourceName: "System Power Control",
+						SourceType: redfish.PowerControlSource,
+						Power:      245.0 * device.Watt, // Dell 245W scenario
 					},
 				},
 			},
 			{
 				ID: "Enclosure.Internal.0-1",
 				Readings: []redfish.Reading{
 					{
-						ControlID: "PC1",
-						Name:      "Enclosure Power Control",
-						Power:     189.5 * device.Watt, // HPE 189W scenario
+						SourceID:   "PC1",
+						SourceName: "Enclosure Power Control",
+						SourceType: redfish.PowerControlSource,
+						Power:      189.5 * device.Watt, // HPE 189W scenario
 					},
 					{
-						ControlID: "PC2",
-						Name:      "CPU Sub-system Power",
-						Power:     167.8 * device.Watt, // Lenovo 167W scenario
+						SourceID:   "PC2",
+						SourceName: "CPU Sub-system Power",
+						SourceType: redfish.PowerControlSource,
+						Power:      167.8 * device.Watt, // Lenovo 167W scenario
 					},
 				},
 			},