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

1 files changed, 192 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