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- Can only aggregate a single satellite BMC 46- HTTP only connection to satellite BMC 47- No authentication on satellite BMC 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 82aggregation prefix is planned to be derived from the uuid of the aggregating 83BMC. This should result in the aggregation prefix being unique to each 84aggregating BMC. 85 86The general URI format for aggregated resources is 87 88```bash 89/redfish/v1/<resource_collection>/<prefix>_<resource_id> 90``` 91 92When support is added for aggregating more than one satellite BMC, then each 93satellite will be assigned its own unique satellite prefix. 94 95### Aggregating Collections 96 97Requests to top level collections are locally processed like normal by the 98aggregating BMC. In addition, the request is forwarded to the satellite BMCs as 99long as it was a GET request. Any other types of request is still handled 100locally, but the aggregator will not forward it to the satellites. 101 102The responses are processed by first adding the aggregation prefix to the URIs 103and then adding the URIs to the "Members" array in the response generated by the 104aggregating BMC. 105 106If the responses from the satellite responses do not contain a "Members" array 107then we assume the initial request was not actually for a top level collection 108and we do not attempt to add anything to the response generated by the 109aggregating BMC. Similarly, we ignore any satellite responses that do not return 110a 200 response code. 111 112The following example shows how aggregated resources are added to a top level 113collection 114 115```bash 116curl -k -H "X-Auth-Token: $token" https://${bmc}/redfish/v1/Systems 117{ 118 "@odata.id": "/redfish/v1/Systems", 119 "@odata.type": "#ComputerSystemCollection.ComputerSystemCollection", 120 "Members": [ 121 { 122 "@odata.id": "/redfish/v1/Systems/system" 123 }, 124 { 125 "@odata.id": "/redfish/v1/Systems/5B247A_system" 126 } 127 ], 128 "Members@odata.count": 2, 129 "Name": "Computer System Collection" 130} 131``` 132 133### Aggregating a Resource 134 135When the request is for a singular satellite resource instead of a top level 136collection, the aggregator will forward all types of requests (GET, POST, 137DELETE, etc.). This is different from aggregating a collection where only GET 138requests are forwarded to satellites. 139 140Requests for aggregated resources are not fully processed by the aggregating 141BMC. These requests are identified by the presence of the aggregation prefix in 142the request's URI. 143 144The following steps are used to retrieve the requested aggregated resource: 145 1461. Determine the target satellite BMC based on the prefix 1472. Remove the prefix from the response URI 1483. Forward the request to the satellite BMC 1494. Where appropriate add the prefix to the URIs in the response 1505. Return the updated response from the satellite BMC 151 152```bash 153curl -k -H "X-Auth-Token: $token" https://${bmc}/redfish/v1/Systems/5B247A_system 154{ 155 "@odata.id": "/redfish/v1/Systems/5B247A_system", 156 ... 157 "LogServices": { 158 "@odata.id": "/redfish/v1/Systems/5B247A_system/LogServices" 159 }, 160 "Memory": { 161 "@odata.id": "/redfish/v1/Systems/5B247A_system/Memory" 162 }, 163 ... 164} 165``` 166 167We consider any response to be a valid response code from the satellite BMC. The 168aggregator will attempt to perform prefix fixing on the received response and 169then forward it to the client. It is up to the client to determine how to react 170to the received response (e.g. resend the request). A failure during the 171communication process will cause bmcweb to attempt to resend the request as per 172the retry policy. Exhausting the retry policy will result in the aggregating BMC 173returning a 502 response. 174 175## Remaining Work 176 177The long term goal is to have Redfish aggregation be enabled by default. There 178are some features that must still be implemented before that can happen. 179 1801. Add links to satellite only collections in responses from service root and 181 other appropriate locations 1822. Generate aggregation prefix from uuid 1833. Aggregate more than one satellite BMC 1844. 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