You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@brooklyn.apache.org by Taylor <ts...@live.com> on 2017/08/23 15:49:34 UTC

Apache Brooklyn Architecture

Hello,


For the last few weeks I have been reading the documentation and source code trying to build a mental model for how brooklyn works. This started when I began looking at writing a custom entity and the VanillaSoftwareService. I want to understand how the tiny bit of YAML gets translated into the java objects on the brooklyn host or remote host. For example, where is the main entry point, how is the driver selected for an entity, when an enricher is invoked how does that reach a method on the driver.


From looking at the source code I have discovered various objects and processes but do not yet have a "start to finish" idea of what goes on. I have read through the CAMP specs and the brooklyn site and not found a diagram or comments in code.


I would like to work with some experienced developers to fill in my blanks and possibly add some comments/content/diagrams to the site.


Is anyone knowledgeable in this subject?


Thanks,


Taylor

Re: Apache Brooklyn Architecture

Posted by Taylor <ts...@live.com>.
Hi Aled,


Thanks for writing. It took some time to digest / compare with my notes from reading the source code.


I still have some remaining questions. Ultimatly once resolved I would like yo put together some docs/diagrams.


Does anyone know who I could contact for further deep dive discussion? Possibly a skype call?


Thanks,


Taylor

________________________________
From: Aled Sage <al...@gmail.com>
Sent: Thursday, August 24, 2017 9:40 AM
To: dev@brooklyn.apache.org; Taylor
Subject: Re: Apache Brooklyn Architecture

Hi Taylor, thanks for getting in touch.

Improving the docs would be awesome!

Is there a use-case you have in mind as well, or is it to just get a better understanding of how Brooklyn works?

---
See http://brooklyn.apache.org/v/latest/blueprints/java/entities.html#softwareprocess-lifecycle for a description of the steps.

The description at that page could do with updating - e.g. it is missing the "latches".

Also, the pages could do with a re-vamp to ensure people are pointed to the yaml way whenever possible, with the underlying Java being described for those who want to look under the covers or write entities in Java for whatever reason.

Note that those using YAML don't need to know most of this, but they do need to know the order in which their commands will be executed.

---
I can give you some additional pointers/info now.

Let's start with a simpler entity type - e.g. org.apache.brooklyn.entity.stock.BasicStartable - which will illustrate how things wire up.
location: localhost
services:
  - type: org.apache.brooklyn.entity.stock.BasicStartable
    brooklyn.config:
      foo: bar
    brooklyn.enrichers:
      - type: org.apache.brooklyn.enricher.stock.Transformer
        brooklyn.config:
          ...
Brooklyn looks up "org.apache.brooklyn.entity.stock.BasicStartable" in the catalog, and instantiates that entity. Under the covers, the YAML parser creates an EntitySpec, then calls managementContext.getEntityManager().createEntity(spec).

The keys and values under brooklyn.config get turned into org.apache.brooklyn.config.ConfigKeys (which are set via the spec). In the subsequent entity, these values are then available in the Java model via entity.config().get(...).

When the entity is instantiated (after its config has been populated etc), the entity.init() method is called. After that, the entity is offiically "managed" by the management context.

The enrichers listed above are instantiated in a similar way (i.e. the yaml parser creates an EnricherSpec, and then calls managementContext.getEntityManager().createEnricher(spec). The enricher then has its enricher.setEntity(entity) method called automatically, which is where it wires itself up (e.g. subscribes to sensors, etc).

The location is instantiated (see the code org.apache.brooklyn.api.location.LocationRegistry, LocationSpec, and managementContext.getLocationManager().createLocation(spec)).

When this yaml blueprint is deployed, it automatically calls the start(locations) effector, if it exists. Effectors can either be declared in Java entities or can be defined in the YAML. Where the given effector is a simple annotated method, that method will be called (wrapped in a "task" so that it is shown in the activity view).

---
Now let's switch to your VanillaSoftwareProcess. e.g.:
location: localhost
services:
  - type: org.apache.brooklyn.entity.software.base.VanillaSoftwareProcess
    brooklyn.config:
      install.command: echo installing
      launch.command: echo launching
      checkRunning.command: echo checking
As with the simpler entity example, the start(locations) effector is called. This delegates to softwareProcessDriverLifecycleEffectorTasks.start(), which executes a sequence the sequence of actions as sub-tasks (based on the config you have supplied).

---
You asked above the choice of driver. See http://brooklyn.apache.org/v/latest/blueprints/java/entity.html#key-steps

In hindsight, this is definitely architectural/plugability overkill! Almost everything uses just one driver implementation. One can configure it explicitly, but the "convention over configuration" is to implement getDriverInterface() to return the driver interface (e.g. VanillaSoftwareProcessDriver.class), and then for it to reflectively instantiate the expected driver class name by changing he suffix to SshDriver (e.g. VanillaSoftwareProcessSshDriver).

Aled


On 23/08/2017 16:49, Taylor wrote:

Hello,


For the last few weeks I have been reading the documentation and source code trying to build a mental model for how brooklyn works. This started when I began looking at writing a custom entity and the VanillaSoftwareService. I want to understand how the tiny bit of YAML gets translated into the java objects on the brooklyn host or remote host. For example, where is the main entry point, how is the driver selected for an entity, when an enricher is invoked how does that reach a method on the driver.


From looking at the source code I have discovered various objects and processes but do not yet have a "start to finish" idea of what goes on. I have read through the CAMP specs and the brooklyn site and not found a diagram or comments in code.


I would like to work with some experienced developers to fill in my blanks and possibly add some comments/content/diagrams to the site.


Is anyone knowledgeable in this subject?


Thanks,


Taylor

Re: Apache Brooklyn Architecture

Posted by Aled Sage <al...@gmail.com>.
Hi Taylor, thanks for getting in touch.

Improving the docs would be awesome!

Is there a use-case you have in mind as well, or is it to just get a 
better understanding of how Brooklyn works?

---
See 
http://brooklyn.apache.org/v/latest/blueprints/java/entities.html#softwareprocess-lifecycle 
for a description of the steps.

The description at that page could do with updating - e.g. it is missing 
the "latches".

Also, the pages could do with a re-vamp to ensure people are pointed to 
the yaml way whenever possible, with the underlying Java being described 
for those who want to look under the covers or write entities in Java 
for whatever reason.

Note that those using YAML don't need to know most of this, but they do 
need to know the order in which their commands will be executed.

---
I can give you some additional pointers/info now.

Let's start with a simpler entity type - e.g. 
org.apache.brooklyn.entity.stock.BasicStartable - which will illustrate 
how things wire up.

    location: localhost
    services:
       - type: org.apache.brooklyn.entity.stock.BasicStartable
         brooklyn.config:
           foo: bar
         brooklyn.enrichers:
           - type: org.apache.brooklyn.enricher.stock.Transformer
             brooklyn.config:
               ...

Brooklyn looks up "org.apache.brooklyn.entity.stock.BasicStartable" in 
the catalog, and instantiates that entity. Under the covers, the YAML 
parser creates an EntitySpec, then calls 
managementContext.getEntityManager().createEntity(spec).

The keys and values under brooklyn.config get turned into 
org.apache.brooklyn.config.ConfigKeys (which are set via the spec). In 
the subsequent entity, these values are then available in the Java model 
via entity.config().get(...).

When the entity is instantiated (after its config has been populated 
etc), the entity.init() method is called. After that, the entity is 
offiically "managed" by the management context.

The enrichers listed above are instantiated in a similar way (i.e. the 
yaml parser creates an EnricherSpec, and then calls 
managementContext.getEntityManager().createEnricher(spec). The enricher 
then has its enricher.setEntity(entity) method called automatically, 
which is where it wires itself up (e.g. subscribes to sensors, etc).

The location is instantiated (see the code 
org.apache.brooklyn.api.location.LocationRegistry, LocationSpec, and 
managementContext.getLocationManager().createLocation(spec)).

When this yaml blueprint is deployed, it automatically calls the 
start(locations) effector, if it exists. Effectors can either be 
declared in Java entities or can be defined in the YAML. Where the given 
effector is a simple annotated method, that method will be called 
(wrapped in a "task" so that it is shown in the activity view).

---
Now let's switch to your VanillaSoftwareProcess. e.g.:

    location: localhost
    services:
       - type:
    org.apache.brooklyn.entity.software.base.VanillaSoftwareProcess
         brooklyn.config:
           install.command: echo installing
           launch.command: echo launching
           checkRunning.command: echo checking

As with the simpler entity example, the start(locations) effector is 
called. This delegates to 
softwareProcessDriverLifecycleEffectorTasks.start(), which executes a 
sequence the sequence of actions as sub-tasks (based on the config you 
have supplied).

---
You asked above the choice of driver. See 
http://brooklyn.apache.org/v/latest/blueprints/java/entity.html#key-steps

In hindsight, this is definitely architectural/plugability overkill! 
Almost everything uses just one driver implementation. One can configure 
it explicitly, but the "convention over configuration" is to implement 
getDriverInterface() to return the driver interface (e.g. 
VanillaSoftwareProcessDriver.class), and then for it to reflectively 
instantiate the expected driver class name by changing he suffix to 
SshDriver (e.g. VanillaSoftwareProcessSshDriver).

Aled


On 23/08/2017 16:49, Taylor wrote:
> Hello,
>
>
> For the last few weeks I have been reading the documentation and source code trying to build a mental model for how brooklyn works. This started when I began looking at writing a custom entity and the VanillaSoftwareService. I want to understand how the tiny bit of YAML gets translated into the java objects on the brooklyn host or remote host. For example, where is the main entry point, how is the driver selected for an entity, when an enricher is invoked how does that reach a method on the driver.
>
>
>  From looking at the source code I have discovered various objects and processes but do not yet have a "start to finish" idea of what goes on. I have read through the CAMP specs and the brooklyn site and not found a diagram or comments in code.
>
>
> I would like to work with some experienced developers to fill in my blanks and possibly add some comments/content/diagrams to the site.
>
>
> Is anyone knowledgeable in this subject?
>
>
> Thanks,
>
>
> Taylor
>