metlos/RHQ — pull request #8 by metlos (2013-03-05 14:28:33+00:00)
Title: First stab at the plugin API of the new provisioning subsystem.

First proposal of the plugin API for the provisioning subsystem,

# Goals

This proposal tries to address a couple of issues with the current
bundles and content APIs:

* Does not leak DB entities into the plugin API.
* IMHO, this is important for the stability of the API. The agent
side is usually much more stable than the serverside.
* Has a concept of deployment that can be either discovered or deployed
* Deployments can de done using the FS modification or through an API
* Deployment can be analyzed for effects on the inventory

# Implementation details

The original `BundleFacet` performed the deployment of a bundle on a
filesystem. The original `ContentFacet` performed the deployment and
discovery of packages through API (which could have been a FS
modification :wink: ).

Both interfaces were monolithic in a sense. The `ContentFacet` did
everything content-related, the `BundleFacet` did everything bundle
related.

The new implementation dissects the functionality of both old
subsystems into more fine-grained interfaces that define different
levels of capabilities of the components involved in the new
provisioning subsystem (similarly to how we for example split
`CreateChildResourceFacet` and `DeleteResourceFacet`).

## `Deployment`
A deployment is the basic representation of an actual deployment. It
actually is an interface with 2 implementations, but the basics of
a deployment are:
* It is explicitely either filesystem or API deployment
* This is important so that any participating party in the
provisioning workflow can find out whether they can access
the deployment data or if an intermediary is necessary.
* It is identifiable
* The deployment knows its "owner" (the class that discovered or
deployed it) and a name specific for that owner.
* It contains a set of files.
* Depending on the type of deployment, these are either actual
files on the filesystem or some logical names of stuff
represented by `File` objects.

## `DeployerFacet`
This is almost one-to-one copy of `BundleFacet`. You deploy and
undeploy, sending in a request and getting a realized deployment.

Both today's bundle plugins as well as `ContentFacet` implementors
would implement this interface.

We would keep the distinction between the deployer and target of
the deployment as it exists today in the bundle subsystem.
`DeployerFacet` is obviously the deployer part of the equation and the
target of the deployment would be handed down to the agent from the
server by whatever means (group deployment, whatever).

Once deployer finishes the deployment and returns the
`RealizedDeployment` instance to the plugin container, the plugin
container passes that instance to all resource components of the target
resources that implement the `DeploymentAnalysisFacet`.

## `DeploymentAnalysisFacet`
The resulting deployment coming from the deployer has passed down to
the targets of the deployment. The targets then have a chance of
analyzing the deployment and figure out the effects of the deployment
on their resource subtree.

This facet is therefore meant to be implemented by the resource
components.

There are 2 methods: `analyzeDeployment` and `analyzeUndeployment` both
getting a `Deployment` instance coming from the `DeployerFacet` (which
might or might not be the same resource component instance btw.).

## `DeploymentDiscoveryFacet`
Another source of deployment objects are resource components
implementing this interface. This is akin to
`ContentFacet.discoverDeployedPackages()` method.

The discovered deployments share one important aspect with the
`ContentFacet`. The deployments discovered using this facet are never
supposed to "escape" it - i.e. the discovered deployments only affect
the resource itself or some of its subdeployments.

# TODO list
- [ ] Plugin descriptor changes
- [ ] Migration guides from the current APIs
- [ ] Interaction with `DeleteResourceFacet` - if a deployment spans
multiple resources, what happens when we remove one of them?
- [ ] Figure out how to modify ant bundle plugin (or a successor
thereof) to return the list of modified files (fork ant? require
the recipe to explicitly list the files somehow?)