AGGREGATION.md - gbmcweb - Git at Google

 # 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
	# 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