1# Redfish Aggregation 2 3With Redfish aggregation the host BMC aggregates resources from specified 4satellite BMCs. Aggregated resources are accessed in the same way as local 5resources. The only observable difference between local and aggregated resources 6is aggregated resources have a special prefix added to their URIs. 7 8The satellite BMCs are not aware that they are being aggregated. The aggregating 9BMC handles the additional processing required to allow the aggregating BMC and 10satellite BMCs to be observable as a singular combined BMC. 11 12## Configuration 13 14bmcweb by default is compiled with Redfish aggregation disabled. To enable it 15add the following to your local.conf. 16 17```bash 18EXTRA_OEMESON:pn-bmcweb:append = "-Dredfish-aggregation='enabled'" 19``` 20 21In addition to the compiler option, bmcweb requires a satellite config to be 22present on D-Bus. The config contains the necessary information to connect to a 23satellite BMC. The following is an example entity-manager json config for a 24satellite located at 160.80.40.20:80 25 26```bash 27{ 28 "Exposes": [ 29 { 30 "Hostname": "160.80.40.20", 31 "Port": "80", 32 "Name": "sat0", 33 "Type": "SatelliteController", 34 "AuthType": "None" 35 } 36 ], 37``` 38 39Note that the satellite config must specify a hostname, port, and authentication 40type. Currently the only type of supported authentication is "None". Bmcweb will 41reject satellite configs that do not comply with these requirements. 42 43## Satellite BMC Restrictions 44 45- HTTP only connection to satellite BMC 46- No authentication on satellite BMC 47- Each satellite BMC must have a unique "Name" property in its configuration 48 49## Supported Resources 50 51Aggregation is supported for all resources that are currently supported by 52bmcweb and appear under top level collections. A top level collection is the 53first collection reached when walking the path from the service root. The 54following are a few examples of top level collections: 55 56```bash 57/redfish/v1/Chassis 58/redfish/v1/TaskService/Tasks 59/redfish/v1/UpdateService/FirmwareInventory 60 61``` 62 63The only exception is `/redfish/v1/JsonSchemas`. We purposefully do not 64aggregate that collection since some of the schemas can be very large and their 65versions could differ from the schema versions on the aggregating BMC. Instead 66it is assumed that the schemas are compatible. 67 68Similarly, we do not aggregate any satellite `$metadata` which is available at 69`/redfish/v1/$metadata`. We make the assumption that the $metadata of the 70aggregating BMC is compatible with all aggregated satellite resources. 71 72Complete support needs to be added for all top level resource collections that 73are defined in the Redfish spec, but are not yet supported by bmcweb. Queries to 74these endpoints like `/redfish/v1/<unsupported_collection>` will return all 75resources on the satellite BMC, but a link for the unsupported collection will 76not appear when querying the Service Root. 77 78## Operation 79 80Aggregated resources will have a prefix appended to their URIs in order to 81distinguish them from resources that are local to the aggregating BMC. The 82prefix is derived from the "Name" property specified in the satellite BMC's 83configuration in Entity Manager. This allows for meaningful and unique prefixes 84for each satellite BMC. 85 86The general URI format for aggregated resources is 87 88```bash 89/redfish/v1/<resource_collection>/<name>_<resource_id> 90``` 91 92Where `<name>` is the value of the "Name" property from the satellite's 93configuration. For example, if a satellite is configured with `"Name": "sat0"`, 94its resources would appear as `/redfish/v1/Systems/sat0_system`. 95 96### Aggregating Collections 97 98Requests to top level collections are locally processed like normal by the 99aggregating BMC. In addition, the request is forwarded to the satellite BMCs as 100long as it was a GET request. Any other types of request is still handled 101locally, but the aggregator will not forward it to the satellites. 102 103The responses are processed by first adding the aggregation prefix to the URIs 104and then adding the URIs to the "Members" array in the response generated by the 105aggregating BMC. 106 107If the responses from the satellite responses do not contain a "Members" array 108then we assume the initial request was not actually for a top level collection 109and we do not attempt to add anything to the response generated by the 110aggregating BMC. Similarly, we ignore any satellite responses that do not return 111a 200 response code. 112 113The following example shows how aggregated resources are added to a top level 114collection 115 116```bash 117curl -k -H "X-Auth-Token: $token" https://${bmc}/redfish/v1/Systems 118{ 119 "@odata.id": "/redfish/v1/Systems", 120 "@odata.type": "#ComputerSystemCollection.ComputerSystemCollection", 121 "Members": [ 122 { 123 "@odata.id": "/redfish/v1/Systems/system" 124 }, 125 { 126 "@odata.id": "/redfish/v1/Systems/sat0_system" 127 }, 128 { 129 "@odata.id": "/redfish/v1/Systems/sat1_system" 130 } 131 ], 132 "Members@odata.count": 3, 133 "Name": "Computer System Collection" 134} 135``` 136 137### Aggregating a Resource 138 139When the request is for a singular satellite resource instead of a top level 140collection, the aggregator will forward all types of requests (GET, POST, 141DELETE, etc.). This is different from aggregating a collection where only GET 142requests are forwarded to satellites. 143 144Requests for aggregated resources are not fully processed by the aggregating 145BMC. These requests are identified by the presence of the aggregation prefix in 146the request's URI. 147 148The following steps are used to retrieve the requested aggregated resource: 149 1501. Determine the target satellite BMC based on the prefix 1512. Remove the prefix from the response URI 1523. Forward the request to the satellite BMC 1534. Where appropriate add the prefix to the URIs in the response 1545. Return the updated response from the satellite BMC 155 156```bash 157curl -k -H "X-Auth-Token: $token" https://${bmc}/redfish/v1/Systems/sat0_system 158 { 159 "@odata.id" : 160 "/redfish/v1/Systems/sat0_system", 161 ... "LogServices" : 162 {"@odata.id" : "/redfish/v1/Systems/sat0_system/LogServices"}, 163 "Memory" : 164 {"@odata.id" : "/redfish/v1/Systems/sat0_system/Memory"}, 165 ... 166 } 167``` 168 169We consider any response to be a valid response code from the satellite BMC. The 170aggregator will attempt to perform prefix fixing on the received response and 171then forward it to the client. It is up to the client to determine how to react 172to the received response (e.g. resend the request). A failure during the 173communication process will cause bmcweb to attempt to resend the request as per 174the retry policy. Exhausting the retry policy will result in the aggregating BMC 175returning a 502 response. 176 177## Remaining Work 178 179The long term goal is to have Redfish aggregation be enabled by default. There 180are some features that must still be implemented before that can happen. 181 1821. Add links to satellite only collections in responses from service root and 183 other appropriate locations 1842. Support HTTPS connection to satellite BMC 185 186Support for the following items should be added as well. However, their 187implementation is not a requirement to being able to enable Redfish aggregation 188by default. 189 1901. Support adding a Contains/ContainedBy relationship between local and 191 aggregated Chassis. 1922. Support Authentication with satellite BMCs 193