The Management Resource Framework API

The Management Resource Framework (MRF) provides a RESTFul HTTP API for reading and writing properties and invoking operations. The framework uses JSON for data encoding to ensure interoperability with non-Java clients. The framework also makes extensive use of hypermedia and linking to provide loose-coupling and cross-cluster navigation without requiring the use of fixed IP addresses. Further, the MRF provides transparent replication of management changes across all members of a cluster so that runtime configuration remains consistent.

The Management API structure

The controller acts as the root for all resources in a cluster and provides a single stable URI in the form of:

http(s)://<controller address:port>/management/domain

In a single-VM environment, this remains the same since the controller and participant are collocated in the same process.

In topologies where multiple clusters (zones) exist, the zone leader is responsible for propagating a minimum of information to the controller. Specifically, the only information that is propagated is the HTTP(S) address port of the zone leader.

A client connects to a single stable URI on the controller. From there, it can navigate hyperlinks built from the propagated HTTP address and port of each zone leader. It can then follow the hyperlink to the zone leader to query zone information or perform a management operation. Since a zone is homogenous, F3 doesn't need to propagate information between zone members; they are just assumed they are in sync. Consequently, a GET on a management attribute will always return the same value from each runtime. If a zone leader crashes, a new one will be elected automatically by the Fabric3 clustering infrastructure. A client would then receive a 404 from the crashed zone address and may need to requery the controller for the new zone leader address.

When the root controller URI is queried, JSON similar to the following will be returned:

{

"selfLink":{"name":"self","rel":"self","href":"http://localhost:8180/management/domain"},

"components":{"name":"components","rel":"edit","href":"http://localhost:8180/management/domain/components"},

"zones":{"name":"zones","rel":"edit","href":"http://localhost:8180/management/domain/zones"},

"contributions":{"name":"contributions","rel":"edit","href":"http://localhost:8180/management/domain/contributions"},

"deployments":{"name":"deployments","rel":"edit","href":"http://localhost:8180/management/domain/deployments"}

}

All resources have a self-link, which is its URL. The domain resource has a number of sub-resources:

• components - a link to retrieve the current set of deployed components
• zones - the link to receive the current list of zones and their management addresses
• contributions - the link to contribution operations
• deployments the link to deployment operations

Querying Zone Information

To view a list of zones, the client would GET the zones link, http://<base address:port>/management/domain/zones:

{
"selfLink":{"name":"self","rel":"self","href":"http://localhost:8180/management/domain/zones"},

"value":[{"name":"zone1","rel":"edit","href":"http://10.0.1.9:8182/management/zone"}]
}  

The above example has one zone running, at http://10.0.1.9:8182/management/zone:

{
"selfLink":{"name":"self","rel":"self","href":"http://10.0.1.9:8182/management/zone"},

"leader":"domain:participant:zone1:participant","name":"domain:participant:zone1:participant",
"runtime":{"name":"runtime","rel":"edit","href":"http://10.0.1.9:8182/management/zone/runtime"}
}

The returned zone information provides the current leader as well as a link to the "runtime" resource. The runtime resource is a composite resource that represents all management resources in the zone. For example, the ThreadPoolExecutor for each runtime in the zone will be represented by a runtime subresource. If a client GETs an attribute, a value only needs to be returned from the current zone leader since all runtimes are considered to have the same values (for those attributes that do not have the same values, resources corresponding to each runtime can be accessed by following links to the runtime in question).

The interesting part is when a modification to a zone resource is made (PUT, DELETE, POST). In this case, the modification will be broadcast an applied to all zone members. This allows clients to make a simple HTTP request that transparently updates all runtimes in a zone.

Contribution and Deployment Operations

Contribution operations are performed against the /domain/contributions URI:

• GET /contributions - Returns installed contributions
• PUT /contributions/contribution/<uri> - Installs a contribution
• GET /contributions/contribution/<uri> - Returns information on the installed contribution
• DELETE /contributions/contribution/<uri> - Removes the installed contribution

Similarly, deployment operations are done against /domain/deployments:

• GET /deployments - Returns deployed contributions
• PUT /deployments/contribution/<uri> - Deploys a contribution
• DELETE /deployments/contribution/<uri> - Un-deploys a contribution

Querying Runtime Operations

Runtime resources are accessed from the top-level URI <address>/management/domain/runtime. The returned resource will contain hyperlinks to all managed resources for the particular runtime.

Performing Zone Operations

Management values can be modified in a single operation for all runtimes in a zone by using the MRF zone-based address. The zone based address is identical to the <address>/management/runtime address except it is located under the path <address>/management/zone. For example <address>/management/domain/runtime/foo would be <address>/management/zone. A management client can navigate to any runtime in a zone and perform an HTTP POST operation. Fabric3 will automatically propagate changes made via the POST to all runtimes in the zone.