diff options
author | Carson Labrado <clabrado@google.com> | 2022-10-14 01:43:57 +0300 |
---|---|---|
committer | Ed Tanous <ed@tanous.net> | 2023-03-01 03:28:05 +0300 |
commit | a88562de3928f88e71505e629b640adfc00c2b62 (patch) | |
tree | e7c51faa757295c137b0eec827f8db2c667af1bc | |
parent | ca165b9944a1472f9c6ddf0e222f571da92b8133 (diff) | |
download | bmcweb-a88562de3928f88e71505e629b640adfc00c2b62.tar.xz |
Aggregation: Document Redfish aggregation
Adds documentation on Redfish aggregation. Includes an overview of its
current capabilities as well as how to enable and use the feature.
Signed-off-by: Carson Labrado <clabrado@google.com>
Change-Id: Ife8dae921e2d9772e7676dc927b41f7dfc00c047
-rw-r--r-- | AGGREGATION.md | 192 | ||||
-rw-r--r-- | README.md | 6 |
2 files changed, 198 insertions, 0 deletions
diff --git a/AGGREGATION.md b/AGGREGATION.md new file mode 100644 index 0000000000..9fa4b7ea08 --- /dev/null +++ b/AGGREGATION.md @@ -0,0 +1,192 @@ +# Redfish Aggregation + +With Redfish aggregation the host BMC aggregates resources from specified +satellite BMCs. Aggregated resources are accessed in the same way as local +resources. The only observable difference between local and aggregated resources +is aggregated resources have a special prefix added to their URIs. + +The satellite BMCs are not aware that they are being aggregated. The aggregating +BMC handles the additional processing required to allow the aggregating BMC and +satellite BMCs to be observable as a singular combined BMC. + +## Configuration + +bmcweb by default is compiled with Redfish aggregation disabled. To enable it +add the following to your local.conf. + +```bash +EXTRA_OEMESON:pn-bmcweb:append = "-Dredfish-aggregation='enabled'" +``` + +In addition to the compiler option, bmcweb requires a satellite config to be +present on D-Bus. The config contains the necessary information to connect to a +satellite BMC. The following is an example entity-manager json config for a +satellite located at 160.80.40.20:80 + +```bash +{ + "Exposes": [ + { + "Hostname": "160.80.40.20", + "Port": "80", + "Name": "sat0", + "Type": "SatelliteController", + "AuthType": "None" + } + ], +``` + +Note that the satellite config must specify a hostname, port, and authentication +type. Currently the only type of supported authentication is "None". Bmcweb will +reject satellite configs that do not comply with these requirements. + +## Satellite BMC Restrictions + +- Can only aggregate a single satellite BMC +- HTTP only connection to satellite BMC +- No authentication on satellite BMC + +## Supported Resources + +Aggregation is supported for all resources that are currently supported by +bmcweb and appear under top level collections. A top level collection is the +first collection reached when walking the path from the service root. The +following are a few examples of top level collections: + +```bash +/redfish/v1/Chassis +/redfish/v1/TaskService/Tasks +/redfish/v1/UpdateService/FirmwareInventory + +``` + +The only exception is `/redfish/v1/JsonSchemas`. We purposefully do not +aggregate that collection since some of the schemas can be very large and their +versions could differ from the schema versions on the aggregating BMC. Instead +it is assumed that the schemas are compatible. + +Similarly, we do not aggregate any satellite `$metadata` which is available at +`/redfish/v1/$metadata`. We make the assumption that the $metadata of the +aggregating BMC is compatible with all aggregated satellite resources. + +Complete support needs to be added for all top level resource collections that +are defined in the Redfish spec, but are not yet supported by bmcweb. Queries to +these endpoints like `/redfish/v1/<unsupported_collection>` will return all +resources on the satellite BMC, but a link for the unsupported collection will +not appear when querying the Service Root. + +## Operation + +Aggregated resources will have a prefix appended to their URIs in order to +distinguish them from resources that are local to the aggregating BMC. The +aggregation prefix is planned to be derived from the uuid of the aggregating +BMC. This should result in the aggregation prefix being unique to each +aggregating BMC. + +The general URI format for aggregated resources is + +```bash +/redfish/v1/<resource_collection>/<prefix>_<resource_id> +``` + +When support is added for aggregating more than one satellite BMC, then each +satellite will be assigned its own unique satellite prefix. + +### Aggregating Collections + +Requests to top level collections are locally processed like normal by the +aggregating BMC. In addition, the request is forwarded to the satellite BMCs as +long as it was a GET request. Any other types of request is still handled +locally, but the aggregator will not forward it to the satellites. + +The responses are processed by first adding the aggregation prefix to the URIs +and then adding the URIs to the "Members" array in the response generated by the +aggregating BMC. + +If the responses from the satellite responses do not contain a "Members" array +then we assume the initial request was not actually for a top level collection +and we do not attempt to add anything to the response generated by the +aggregating BMC. Similarly, we ignore any satellite responses that do not return +a 200 response code. + +The following example shows how aggregated resources are added to a top level +collection + +```bash +curl -k -H "X-Auth-Token: $token" https://${bmc}/redfish/v1/Systems +{ + "@odata.id": "/redfish/v1/Systems", + "@odata.type": "#ComputerSystemCollection.ComputerSystemCollection", + "Members": [ + { + "@odata.id": "/redfish/v1/Systems/system" + }, + { + "@odata.id": "/redfish/v1/Systems/5B247A_system" + } + ], + "Members@odata.count": 2, + "Name": "Computer System Collection" +} +``` + +### Aggregating a Resource + +When the request is for a singular satellite resource instead of a top level +collection, the aggregator will forward all types of requests (GET, POST, +DELETE, etc.). This is different from aggregating a collection where only GET +requests are forwarded to satellites. + +Requests for aggregated resources are not fully processed by the aggregating +BMC. These requests are identified by the presence of the aggregation prefix in +the request's URI. + +The following steps are used to retrieve the requested aggregated resource: + +1. Determine the target satellite BMC based on the prefix +2. Remove the prefix from the response URI +3. Forward the request to the satellite BMC +4. Where appropriate add the prefix to the URIs in the response +5. Return the updated response from the satellite BMC + +```bash +curl -k -H "X-Auth-Token: $token" https://${bmc}/redfish/v1/Systems/5B247A_system +{ + "@odata.id": "/redfish/v1/Systems/5B247A_system", + ... + "LogServices": { + "@odata.id": "/redfish/v1/Systems/5B247A_system/LogServices" + }, + "Memory": { + "@odata.id": "/redfish/v1/Systems/5B247A_system/Memory" + }, + ... +} +``` + +We consider any response to be a valid response code from the satellite BMC. The +aggregator will attempt to perform prefix fixing on the received response and +then forward it to the client. It is up to the client to determine how to react +to the received response (e.g. resend the request). A failure during the +communication process will cause bmcweb to attempt to resend the request as per +the retry policy. Exhausting the retry policy will result in the aggregating BMC +returning a 502 response. + +## Remaining Work + +The long term goal is to have Redfish aggregation be enabled by default. There +are some features that must still be implemented before that can happen. + +1. Add links to satellite only collections in responses from service root and + other appropriate locations +2. Generate aggregation prefix from uuid +3. Aggregate more than one satellite BMC +4. Support HTTPS connection to satellite BMC + +Support for the following items should be added as well. However, their +implementation is not a requirement to being able to enable Redfish aggregation +by default. + +1. Support adding a Contains/ContainedBy relationship between local and + aggregated Chassis. +2. Support Authentication with satellite BMCs @@ -90,3 +90,9 @@ read/written can seen from the `persistent_data` namespace. When SSL support is enabled and a usable certificate is not found, bmcweb will generate a self-signed a certificate before launching the server. Please see the bmcweb source code for details on the parameters this certificate is built with. + +## Redfish Aggregation + +bmcweb is capable of aggregating resources from satellite BMCs. Refer to +[AGGREGATION.md](https://github.com/openbmc/bmcweb/blob/master/AGGREGATION.md) +for more information on how to enable and use this feature. |