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