docs: separate âlaunchingâ and âruntime managementâ Project: http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/repo Commit: http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/commit/aed2f1c8 Tree: http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/tree/aed2f1c8 Diff: http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/diff/aed2f1c8
Branch: refs/heads/master Commit: aed2f1c8ae96e44d9a65ee8e994a28e494794a35 Parents: 663f673 Author: Aled Sage <[email protected]> Authored: Thu Jan 15 16:51:22 2015 +0000 Committer: Aled Sage <[email protected]> Committed: Thu Jan 15 16:51:22 2015 +0000 ---------------------------------------------------------------------- docs/guide/ops/index.md | 3 +- docs/guide/ops/launching/index.md | 87 ++++ docs/guide/ops/runtime-management/index.md | 324 +++++++++++++++ .../webconsole-dashboard-w400.png | Bin 0 -> 137463 bytes .../runtime-management/webconsole-dashboard.png | Bin 0 -> 214723 bytes .../webconsole-detail-w400.png | Bin 0 -> 111993 bytes .../runtime-management/webconsole-detail.png | Bin 0 -> 165359 bytes docs/guide/ops/webconsole/index.md | 399 ------------------- .../webconsole/webconsole-dashboard-w400.png | Bin 137463 -> 0 bytes .../ops/webconsole/webconsole-dashboard.png | Bin 214723 -> 0 bytes .../ops/webconsole/webconsole-detail-w400.png | Bin 111993 -> 0 bytes docs/guide/ops/webconsole/webconsole-detail.png | Bin 165359 -> 0 bytes 12 files changed, 413 insertions(+), 400 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/aed2f1c8/docs/guide/ops/index.md ---------------------------------------------------------------------- diff --git a/docs/guide/ops/index.md b/docs/guide/ops/index.md index 27da59f..2e076da 100644 --- a/docs/guide/ops/index.md +++ b/docs/guide/ops/index.md @@ -5,7 +5,8 @@ children: - locations/index.md - locations/configuring.md - persistence/ -- webconsole/ +- launching/ +- runtime-management/ --- {% include list-children.html %} \ No newline at end of file http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/aed2f1c8/docs/guide/ops/launching/index.md ---------------------------------------------------------------------- diff --git a/docs/guide/ops/launching/index.md b/docs/guide/ops/launching/index.md new file mode 100644 index 0000000..8eb3dd9 --- /dev/null +++ b/docs/guide/ops/launching/index.md @@ -0,0 +1,87 @@ +--- +title: Launching Brooklyn +layout: website-normal +--- + +There are several ways to launch applications with brooklyn, and useful configuration options, +as well as a debug-view web console. + +This chapter describes how to launch brooklyn. + + +Startup Configuration +--------------------- + +brooklyn can read configuration from a variety of places: + +* the file ``~/.brooklyn/brooklyn.properties`` +* ``-D`` defines on the brooklyn (java) command-line +* shell environment variables + +Default properties are described in the Javadoc and code of the class ``BrooklynProperties``, +but some of the most common ones are: + +{% highlight properties %} +brooklyn.location.jclouds.aws-ec2.identity=AKA50M30N3S1DFR0MAW55 +brooklyn.location.jclouds.aws-ec2.credential=aT0Ps3cr3tC0D3wh1chAW5w1llG1V3y0uTOus333 +brooklyn.location.jclouds.aws-ec2.privateKeyFile=~/path/to/id_rsa # use specified key (default is ~/.ssh/id_rsa) +brooklyn.location.jclouds.aws-ec2.publicKeyFile=~/path/to/id_rsa.pub # (optional, inferred from previous if omitted) +{% endhighlight %} + +These can be specified as a shell environment variable or as a Java system property, +although in those contexts the conventional format ``BROOKLYN_JCLOUDS_AWS_EC2_IDENTITY`` +is supported and recommended. + + +Command Line Interface +---------------------- + +Brooklyn comes with a Command Line Interface (cli) that makes it easier to launch an application. + +In order to have easy access to the cli it is useful to configure the PATH environment variable to also point to the cli's bin directory: + +{% highlight bash %} +BROOKLYN_HOME=/path/to/brooklyn/ +export PATH=$PATH:$BROOKLYN_HOME/usage/dist/target/brooklyn-dist/bin/ +{% endhighlight %} + +If you have set this up correctly you should be able to invoke the ```brooklyn``` command: + +{% highlight bash %} +brooklyn +{% endhighlight %} + +To get information about all the supported cli options just run: + +{% highlight bash %} +brooklyn help +usage: brooklyn [(-q | --quiet)] [(-v | --verbose)] <command> [<args>] + +The most commonly used brooklyn commands are: + help Display help information about brooklyn + info Display information about brooklyn + launch Starts a brooklyn application. Note that a BROOKLYN_CLASSPATH environment variable needs to be set up beforehand to point to the user application classpath. + +See 'brooklyn help <command>' for more information on a specific command. +{% endhighlight %} + +Here is an example of the commands you might run to get the Brooklyn code, compile it and launch an application: + +{% highlight bash %} +git clone https://github.com/apache/incubator-brooklyn.git +cd brooklyn +mvn clean install -DskipTests +BROOKLYN_HOME=$(pwd) +export PATH=${PATH}:${BROOKLYN_HOME}/usage/dist/target/brooklyn-dist/bin/ +export BROOKLYN_CLASSPATH=${BROOKLYN_HOME}/examples/simple-web-cluster/target/classes +brooklyn launch --app brooklyn.demo.SingleWebServerExample --location localhost +{% endhighlight %} + +You can add things to the brooklyn classpath in a number of ways: + +* Add ``.jar`` files to brooklyn's ``./lib/dropins/`` directory. These are added at the end of the classpath. +* Add ``.jar`` files to brooklyn's ``./lib/patch/`` directory. These are added at the front of the classpath. +* Add resources to brooklyn's ``./conf/`` directory. This directory is at the very front of the classpath. +* Use the ``BROOKLYN_CLASSPATH`` environment variable. If set, this is prepended to the brooklyn classpath. + + http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/aed2f1c8/docs/guide/ops/runtime-management/index.md ---------------------------------------------------------------------- diff --git a/docs/guide/ops/runtime-management/index.md b/docs/guide/ops/runtime-management/index.md new file mode 100644 index 0000000..42b274e --- /dev/null +++ b/docs/guide/ops/runtime-management/index.md @@ -0,0 +1,324 @@ +--- +title: Runtime Management +layout: website-normal +--- + +brooklyn uses many of the ideas from autonomic computing to implement management of entities in a +structured and reusable fashion (including provisioning, healing, and optimising). + +Each external system, process or service is represented as an entity within brooklyn, with +collections of these being represented and managed by other entities, and so forth through +a hierarchy rooted in entities referred to as "Applications". Each entity has: + +- provisioning and tear-down logic for the external system(s) it represents +- sensors which it publishes to report on its state and activity +- effectors which can be invoked to change it +- policies which perform analysis, enrichment (sensors), and execution (effectors). It is the + policies in brooklyn which perform the self-management (in autonomic terms) by monitoring sensors + and invoking effectors. + +This chapter describes these high-level runtime concepts, as well as presenting more +detailed information on the underlying implementation of management within brooklyn. + + + + +Management Web Console +---------------------- + +The web-based management console that comes with brooklyn serves as a way to observe and manage brooklyn entities. +It provides low-level details of activity (including stack-traces), sensor values, and policies, +and some visual widgets for observing what is happening. +This console is not designed as a management dashboard or portal -- +many good options exist in that space -- +but what could be useful is to embed widgets from the brooklyn portal for selected high-level views. + +<!-- FIXME Update to use new construction pattern, rather than calling app's constructor --> +To start a management console from your own code, use ``BrooklynLaucher.launch``: +{% highlight java %} +public static void main(String[] argv) { + Application app = new MyApplicationExample(displayName:"myapp") + BrooklynServerDetails server = BrooklynLauncher.newLauncher() + .managing(app) + .launch(); + // ... +} +{% endhighlight %} + +This will start an embedded brooklyn management node, including the web console. +The URL for the web console defaults to http://127.0.0.1:8081, . + +The mechanism for launching brooklyn management will change in a future release. For this release, the brooklyn management node is embedded. + +The console contains two main views: Dashboard and Detail. These update in real-time. + +**Dashboard** + +The dashboard is a high level overview of the state of the application: + +[](webconsole-dashboard.png) + + +**Detail** + +The Detail view gives an in-depth view of the application and its entities. +Child-parent relationships between entities are navigable using the entity tree; +each entity is shown with its children (or, in the case of childless group entities, the members). +Selecting a specific entity allows you to access detailed information about that entity. + +[](webconsole-detail.png) + +The Detail view contains a breadcrumb trail, showing the current entitiy's position in the heirarchy, and six tabs: + +**Summary:** Description of the selected entity. + +**Sensors:** Lists the attribute sensors that the entity has and their values. + +**Effectors:** Lists the effectors that can be invoked on the selected entity. + +**Activity:** Current and historic activity of the entity, currently running effectors, finished effectors. + +**Location:** The geographical location of the selected entity. + +**Policies:** Lists the policies associated with the current entity. Policies can be suspended, resumed and removed through the UI. + +### Security + +Security providers can be configured by specifying `brooklyn.webconsole.security.provider` equal +to the name of a class implementing `SecurityProvider`. +An implementation of this could point to Spring, LDAP, OpenID or another identity management system. + +The default implementation, `ExplicitUsersSecurityProvider`, reads from a list of users and passwords +which should be specified as configuration parameters e.g. in `brooklyn.properties`. +This configuration could look like: + +{% highlight properties %} +brooklyn.webconsole.security.users=admin +brooklyn.webconsole.security.user.admin.salt=OHDf +brooklyn.webconsole.security.user.admin.sha256=91e16f94509fa8e3dd21c43d69cadfd7da6e7384051b18f168390fe378bb36f9 +{% endhighlight %} + +The `users` line should contain a comma-separated list. The special value `*` is accepted to permit all users. + +To generate this, the brooklyn CLI can be used: +{% highlight bash %} +brooklyn generate-password --user admin + +Enter password: +Re-enter password: + +Please add the following to your brooklyn.properies: + +brooklyn.webconsole.security.users=admin +brooklyn.webconsole.security.user.admin.salt=OHDf +brooklyn.webconsole.security.user.admin.sha256=91e16f94509fa8e3dd21c43d69cadfd7da6e7384051b18f168390fe378bb36f9 +{% endhighlight %} + +For legacy and dev purposes, the password can also be stored in plain text: + +{% highlight properties %} +brooklyn.webconsole.security.users=admin +brooklyn.webconsole.security.user.admin.password=mypassword +{% endhighlight %} + +If not using the web console, you can specify +`brooklyn.webconsole.security.provider=brooklyn.rest.security.provider.BlackholeSecurityProvider` to prevent inadvertant logins. +During dev/test you can specify `brooklyn.webconsole.security.provider=brooklyn.rest.security.provider.AnyoneSecurityProvider` +to allow logins with no credentials. + +To enable https, you will need a server certificate in a java keystore. To create a self-signed certificate, you can use the +following command: + +`keytool -genkey -keyalg RSA -alias brooklyn -keystore <path-to-keystore-directory>/server.key -storepass mypassword -validity 360 -keysize 2048` + +You will then be prompted to enter you name and organization details. This will create a keystore with the password `mypassword` +- you should use your own secure password, which will be the same password used in your brooklyn.properties (below). +You will also need to replace `<path-to-keystore-directory>` with the full path of the folder where you wish to store your +keystore. + +The certificate generated will be a self-signed certificate and will not have a CN field identifying the website server +name, which will cause a warning to be displayed by the browser when viewing the page. For production servers, a valid signed +certificate from a trusted certifying authority should be used instead + +To enable HTTPS in Brooklyn, add the following to your brooklyn.properties: + +``` +# HTTPS +brooklyn.webconsole.security.https.required=true +brooklyn.webconsole.security.keystore.url=<path-to-keystore-directory>/server.key +brooklyn.webconsole.security.keystore.password=mypassword +brooklyn.webconsole.security.keystore.certificate.alias=brooklyn +``` + +In order to access the Brooklyn console, you will also need to enable security, and setup a user as described above + +Other Ways to Observe Activity +------------------------------ + +### Java API + +``ManagementContext`` provides a Java programmatic API. + +More information can be found in the javadoc for ``ManagementContext``. + +### Command-line Console + +*Not available yet.* + +### Management REST API + +Brooklyn does not yet expose a REST API. This was to allow the APi to be designed to align with emerging standards. + +Selected management operations are possible remotely using links exposed by the GUI (after authenticating with the GUI). + +### Logging + +Brooklyn uses the SLF4J logging facade, which allows use of many popular frameworks including java.util.logging, log4j, and logback. + +The convention for log levels is as follows: +* ERROR and above: exceptional situations which indicate that something has unexpectedly failed or +some other problem has occured which the user is expected to attend to +* WARN: exceptional situations which the user may which to know about but which do not necessarily indicate failure or require a response +* INFO: a synopsis of activity, but which should not generate large volumes of events nor overwhelm a human observer +* DEBUG and lower: detail of activity which is not normally of interest, but which might merit closer inspection under certain circumstances. + +Loggers follow the ``package.ClassName`` naming standard. + +It is possible for entities to emit logging activity sensors so that an operator can observe what is occurring within their application through the web console or via programmatic means. + +Examples for testing can be found in some of the poms. + + +<!--- + +<a name="distributed-management"></a> +Distributed Management +---------------------- + +TODO Describe how and when objects become "live", pushed out to other nodes. +--> + +<!--- + +<a name="resilience"></a> +Resilience +---------- +TODO +*This section still needs to be written. Feel free to [fork]({{site.path.guide}}/dev/code) the docs and lend a hand.* +--> + + +Key APIs +-------- +<!--- +TODO - brief overview of key APIs +--> +*This section still needs to be written. Feel free to [fork]({{site.path.guide}}/dev/code) the docs and lend a hand.* + +- ``ManagementContext`` (Java management API) +- ``EntityLocal`` (used by policies) + + +<!--- +TODO - describe how to simply configure logging slf4j +--> + +Sensors and Effectors +--------------------- + +### Sensors + +Sensors are typically defined as static named fields on the Entity subclass. These define the channels of events and activity that interested parties can track remotely. For example: +{% highlight java %} +/** a sensor for saying hi (illustrative), carrying a String value + which is typically the name of the person to whom we are saying hi */ +public static final Sensor<String> HELLO_SENSOR = ... + +{% endhighlight %} + +If the entity is local (e.g. to a policy) these can be looked up using ``get(Sensor)``. If it may be remote, you can subscribe to it through various APIs. + +<!--- +TODO probably say about events now, quick reference about SubscriptionManager (either here or in next section on management context) +TODO remaining section on Sensors perhaps should be moved to Writing Entities section? as reader won't need to know too much detail of sensor types to understand policies... though perhaps saying some is right. (Talking about JSON is almost certainly overkill...) +--> + +Sensors are used by operators and policies to monitor health and know when to invoke the effectors. The sensor data forms a nested map (i.e. JSON), which can be subscribed to through the ``ManagementContext``. + +Often ``Policy`` instances will subscribe to sensor events on their associated entity or its children; these events might be an ``AttributeValueEvent`` â an attribute value being reported on change or periodically â or something transient such as ``LogMessage`` or a custom ``Event`` such as "TOO_HOT". + +<!--- +TODO check classes above; is this much detail needed here? +--> + +Sensor values form a map-of-maps. An example of some simple sensor information is shown below in JSON: + + { + config : { + url : "jdbc:mysql://ec2-50-17-19-65.compute-1.amazonaws.com:3306/mysql" + status : "running" + } + workrate : { + msgsPerSec : 432 + } + } + +Sensor values are defined as statics, which can be used to programmatically drive the subscription. +<!--- +TODO , etc., example +--> + +### SubscriptionManager + +*This section is not complete. Feel free to [fork]({{site.path.guide}}/dev/code) the docs and lend a hand.* + +*See the* ``SubscriptionManager`` *class.* +<!--- +TODO +--> + +### Effectors + +Like sensors and config info, effectors are also static fields on the Entity class. These describe actions available on the entity, similar to methods. Their implementation includes details of how to invoke them, typically this is done by calling a method on the entity. Effectors are typically defined as follows: + +{% highlight java %} +/** an effector which returns no value, + but which causes the entity to emit a HELLO sensor event */ +public static Effector<Void> SAY_HI = ... + +{% endhighlight %} + +Effectors are invoked by calling ``invoke(SAY_HI, name:"Bob")`` or similar. The method may take an entity if context is not clear, and it takes parameters as named parameters or a Map. + +Invocation returns a ``Task`` object (extending ``Future``). This allows the caller to understand progress and errors on the task, as well as ``Task.get()`` the return value. Be aware that ``task.get()`` is a blocking function that will wait until a value is available before returning. + +The management framework ensures that execution occurs on the machine where the ``Entity`` is mastered, with progress, result, and/or any errors reported back to the caller. It does this through the ``ExecutionManager`` which, where necessary, creates proxy ``Task`` instances. The ``ExecutionManager`` associates ``Tasks`` with the corresponding ``Entity`` so that these can be tracked externally (and relocated if the Entity is remastered to a different location). + +It is worth noting that where a method corresponds to an effector, direct invocation of that method on an ``Entity`` will implicitly generate the ``Task`` object as though the effector had been invoked. For example, invoking ``Cluster.resize(int)``, where ``resize`` provides an ``Effector RESIZE``, will generate a ``Task`` which can be observed remotely. + +### ExecutionManager + +The ``ExecutionManager`` is responsible for tracking simultaneous executing tasks and associating these with given **tags**. +Arbitrary tasks can be run by calling ``Task submit(Runnable)`` (similarly to the standard ``Executor``, although it also supports ``Callable`` arguments including Groovy closures, and can even be passed ``Task`` instances which have not been started). ``submit`` also accepts a few other named parameters, including ``description``, which allow additional metadata to be kept on the ``Task``. The main benefit then is to have rich metadata for executing tasks, which can be inspected through methods on the ``Task`` interface. + +By using the ``tag`` or ``tags`` named parameters on ``submit`` (or setting ``tags`` in a ``Task`` that is submitted), execution can be associated with various categories. This allows easy viewing can be examined by calling +``ExecutionManager.getTasksWithTag(...)``. + +The following example uses Groovy, with time delays abused for readability. brooklyn's test cases check this using mutexes, which is recommended. + + ExecutionManager em = [] + em.submit(tag:"a", description:"One Mississippi", { Thread.sleep(1000) }) + em.submit(tags:["a","b"], description:"Two Mississippi", { Thread.sleep(1000) }) + assert em.getTasksWithTag("a").size()==2 + assert em.getTasksWithTag("a").every { Task t -> !t.isDone() } + Thread.sleep(1500) + assert em.getTasksWithTag("a").size()==2 + assert em.getTasksWithTag("a").every { Task t -> t.isDone() } + +It is possible to define ParallelTasks and SequentialTasks and to specify inter-task relationships with TaskPreprocessors. This allows building quite sophisticated workflows relatively easily. + +Continuing the example above, submitting a SequentialTasks or specifying ``em.setTaskPreprocessorForTag("a", SingleThreadedExecution.class)`` will cause ``Two Mississippi`` to run after ``One Mississippi`` completes. + +For more information consult the javadoc on these classes and associated tests. + +Note that it is currently necessary to prune dead tasks, either periodically or by the caller. By default they are kept around for reference. It is expected that an enhancement in a future release will allow pruning completed and failed tasks after a specified amount of time. http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/aed2f1c8/docs/guide/ops/runtime-management/webconsole-dashboard-w400.png ---------------------------------------------------------------------- diff --git a/docs/guide/ops/runtime-management/webconsole-dashboard-w400.png b/docs/guide/ops/runtime-management/webconsole-dashboard-w400.png new file mode 100644 index 0000000..6364dc5 Binary files /dev/null and b/docs/guide/ops/runtime-management/webconsole-dashboard-w400.png differ http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/aed2f1c8/docs/guide/ops/runtime-management/webconsole-dashboard.png ---------------------------------------------------------------------- diff --git a/docs/guide/ops/runtime-management/webconsole-dashboard.png b/docs/guide/ops/runtime-management/webconsole-dashboard.png new file mode 100644 index 0000000..cac5567 Binary files /dev/null and b/docs/guide/ops/runtime-management/webconsole-dashboard.png differ http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/aed2f1c8/docs/guide/ops/runtime-management/webconsole-detail-w400.png ---------------------------------------------------------------------- diff --git a/docs/guide/ops/runtime-management/webconsole-detail-w400.png b/docs/guide/ops/runtime-management/webconsole-detail-w400.png new file mode 100644 index 0000000..b372e55 Binary files /dev/null and b/docs/guide/ops/runtime-management/webconsole-detail-w400.png differ http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/aed2f1c8/docs/guide/ops/runtime-management/webconsole-detail.png ---------------------------------------------------------------------- diff --git a/docs/guide/ops/runtime-management/webconsole-detail.png b/docs/guide/ops/runtime-management/webconsole-detail.png new file mode 100644 index 0000000..17829cd Binary files /dev/null and b/docs/guide/ops/runtime-management/webconsole-detail.png differ http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/aed2f1c8/docs/guide/ops/webconsole/index.md ---------------------------------------------------------------------- diff --git a/docs/guide/ops/webconsole/index.md b/docs/guide/ops/webconsole/index.md deleted file mode 100644 index 62afc2c..0000000 --- a/docs/guide/ops/webconsole/index.md +++ /dev/null @@ -1,399 +0,0 @@ ---- -title: Runtime Management -layout: website-normal ---- - -brooklyn uses many of the ideas from autonomic computing to implement management of entities in a structured and reusable fashion (including provisioning, -healing, and optimising). - -Each external system, process or service is represented as an entity within brooklyn, with collections of these being represented and -managed by other entities, and so forth through a hierarchy rooted in entities referred to as "Applications". Each entity has: - -- provisioning and tear-down logic for the external system(s) it represents -- sensors which it publishes to report on its state and activity -- effectors which can be invoked to change it -- policies which perform analysis, enrichment (sensors), and execution (effectors). It is the policies in brooklyn which - perform the self-management (in autonomic terms) by monitoring sensors and invoking effectors. - -There are several ways to launch applications with brooklyn, and useful configuration options, -as well as a debug-view web console. -This chapter describes these high-level runtime concepts, then proceeds to present more -detailed information on the underlying implementation of management within brooklyn. - - -Startup Configuration ---------------------- - -brooklyn can read configuration from a variety of places: - -* the file ``~/.brooklyn/brooklyn.properties`` -* ``-D`` defines on the brooklyn (java) command-line -* shell environment variables - -Default properties are described in the Javadoc and code of the class ``BrooklynProperties``, -but some of the most common ones are: - -{% highlight properties %} -brooklyn.location.jclouds.aws-ec2.identity=AKA50M30N3S1DFR0MAW55 -brooklyn.location.jclouds.aws-ec2.credential=aT0Ps3cr3tC0D3wh1chAW5w1llG1V3y0uTOus333 -brooklyn.location.jclouds.aws-ec2.privateKeyFile=~/path/to/id_rsa # use specified key (default is ~/.ssh/id_rsa) -brooklyn.location.jclouds.aws-ec2.publicKeyFile=~/path/to/id_rsa.pub # (optional, inferred from previous if omitted) -{% endhighlight %} - -These can be specified as a shell environment variable or as a Java system property, -although in those contexts the conventional format ``BROOKLYN_JCLOUDS_AWS_EC2_IDENTITY`` -is supported and recommended. - - - -Command Line Interface ----------------------- - -Brooklyn comes with a Command Line Interface (cli) that makes it easier to launch an application. - -In order to have easy access to the cli it is useful to configure the PATH environment variable to also point to the cli's bin directory: - -{% highlight bash %} -BROOKLYN_HOME=/path/to/brooklyn/ -export PATH=$PATH:$BROOKLYN_HOME/usage/dist/target/brooklyn-dist/bin/ -{% endhighlight %} - -If you have set this up correctly you should be able to invoke the ```brooklyn``` command: - -{% highlight bash %} -brooklyn -{% endhighlight %} - -To get information about all the supported cli options just run: - -{% highlight bash %} -brooklyn help -usage: brooklyn [(-q | --quiet)] [(-v | --verbose)] <command> [<args>] - -The most commonly used brooklyn commands are: - help Display help information about brooklyn - info Display information about brooklyn - launch Starts a brooklyn application. Note that a BROOKLYN_CLASSPATH environment variable needs to be set up beforehand to point to the user application classpath. - -See 'brooklyn help <command>' for more information on a specific command. -{% endhighlight %} - -Here is an example of the commands you might run to get the Brooklyn code, compile it and launch an application: - -{% highlight bash %} -git clone https://github.com/apache/incubator-brooklyn.git -cd brooklyn -mvn clean install -DskipTests -BROOKLYN_HOME=$(pwd) -export PATH=${PATH}:${BROOKLYN_HOME}/usage/dist/target/brooklyn-dist/bin/ -export BROOKLYN_CLASSPATH=${BROOKLYN_HOME}/examples/simple-web-cluster/target/classes -brooklyn launch --app brooklyn.demo.SingleWebServerExample --location localhost -{% endhighlight %} - -You can add things to the brooklyn classpath in a number of ways: - -* Add ``.jar`` files to brooklyn's ``./lib/dropins/`` directory. These are added at the end of the classpath. -* Add ``.jar`` files to brooklyn's ``./lib/patch/`` directory. These are added at the front of the classpath. -* Add resources to brooklyn's ``./conf/`` directory. This directory is at the very front of the classpath. -* Use the ``BROOKLYN_CLASSPATH`` environment variable. If set, this is prepended to the brooklyn classpath. - - -Management Web Console ----------------------- - -The web-based management console that comes with brooklyn serves as a way to observe and manage brooklyn entities. -It provides low-level details of activity (including stack-traces), sensor values, and policies, -and some visual widgets for observing what is happening. -This console is not designed as a management dashboard or portal -- -many good options exist in that space -- -but what could be useful is to embed widgets from the brooklyn portal for selected high-level views. - -<!-- FIXME Update to use new construction pattern, rather than calling app's constructor --> -To start a management console from your own code, use ``BrooklynLaucher.launch``: -{% highlight java %} -public static void main(String[] argv) { - Application app = new MyApplicationExample(displayName:"myapp") - BrooklynServerDetails server = BrooklynLauncher.newLauncher() - .managing(app) - .launch(); - // ... -} -{% endhighlight %} - -This will start an embedded brooklyn management node, including the web console. -The URL for the web console defaults to http://127.0.0.1:8081, . - -The mechanism for launching brooklyn management will change in a future release. For this release, the brooklyn management node is embedded. - -The console contains two main views: Dashboard and Detail. These update in real-time. - -**Dashboard** - -The dashboard is a high level overview of the state of the application: - -[](webconsole-dashboard.png) - - -**Detail** - -The Detail view gives an in-depth view of the application and its entities. -Child-parent relationships between entities are navigable using the entity tree; -each entity is shown with its children (or, in the case of childless group entities, the members). -Selecting a specific entity allows you to access detailed information about that entity. - -[](webconsole-detail.png) - -The Detail view contains a breadcrumb trail, showing the current entitiy's position in the heirarchy, and six tabs: - -**Summary:** Description of the selected entity. - -**Sensors:** Lists the attribute sensors that the entity has and their values. - -**Effectors:** Lists the effectors that can be invoked on the selected entity. - -**Activity:** Current and historic activity of the entity, currently running effectors, finished effectors. - -**Location:** The geographical location of the selected entity. - -**Policies:** Lists the policies associated with the current entity. Policies can be suspended, resumed and removed through the UI. - -### Security - -Security providers can be configured by specifying `brooklyn.webconsole.security.provider` equal -to the name of a class implementing `SecurityProvider`. -An implementation of this could point to Spring, LDAP, OpenID or another identity management system. - -The default implementation, `ExplicitUsersSecurityProvider`, reads from a list of users and passwords -which should be specified as configuration parameters e.g. in `brooklyn.properties`. -This configuration could look like: - -{% highlight properties %} -brooklyn.webconsole.security.users=admin -brooklyn.webconsole.security.user.admin.salt=OHDf -brooklyn.webconsole.security.user.admin.sha256=91e16f94509fa8e3dd21c43d69cadfd7da6e7384051b18f168390fe378bb36f9 -{% endhighlight %} - -The `users` line should contain a comma-separated list. The special value `*` is accepted to permit all users. - -To generate this, the brooklyn CLI can be used: -{% highlight bash %} -brooklyn generate-password --user admin - -Enter password: -Re-enter password: - -Please add the following to your brooklyn.properies: - -brooklyn.webconsole.security.users=admin -brooklyn.webconsole.security.user.admin.salt=OHDf -brooklyn.webconsole.security.user.admin.sha256=91e16f94509fa8e3dd21c43d69cadfd7da6e7384051b18f168390fe378bb36f9 -{% endhighlight %} - -For legacy and dev purposes, the password can also be stored in plain text: - -{% highlight properties %} -brooklyn.webconsole.security.users=admin -brooklyn.webconsole.security.user.admin.password=mypassword -{% endhighlight %} - -If not using the web console, you can specify -`brooklyn.webconsole.security.provider=brooklyn.rest.security.provider.BlackholeSecurityProvider` to prevent inadvertant logins. -During dev/test you can specify `brooklyn.webconsole.security.provider=brooklyn.rest.security.provider.AnyoneSecurityProvider` -to allow logins with no credentials. - -To enable https, you will need a server certificate in a java keystore. To create a self-signed certificate, you can use the -following command: - -`keytool -genkey -keyalg RSA -alias brooklyn -keystore <path-to-keystore-directory>/server.key -storepass mypassword -validity 360 -keysize 2048` - -You will then be prompted to enter you name and organization details. This will create a keystore with the password `mypassword` -- you should use your own secure password, which will be the same password used in your brooklyn.properties (below). -You will also need to replace `<path-to-keystore-directory>` with the full path of the folder where you wish to store your -keystore. - -The certificate generated will be a self-signed certificate and will not have a CN field identifying the website server -name, which will cause a warning to be displayed by the browser when viewing the page. For production servers, a valid signed -certificate from a trusted certifying authority should be used instead - -To enable HTTPS in Brooklyn, add the following to your brooklyn.properties: - -``` -# HTTPS -brooklyn.webconsole.security.https.required=true -brooklyn.webconsole.security.keystore.url=<path-to-keystore-directory>/server.key -brooklyn.webconsole.security.keystore.password=mypassword -brooklyn.webconsole.security.keystore.certificate.alias=brooklyn -``` - -In order to access the Brooklyn console, you will also need to enable security, and setup a user as described above - -Other Ways to Observe Activity ------------------------------- - -### Java API - -``ManagementContext`` provides a Java programmatic API. - -More information can be found in the javadoc for ``ManagementContext``. - -### Command-line Console - -*Not available yet.* - -### Management REST API - -Brooklyn does not yet expose a REST API. This was to allow the APi to be designed to align with emerging standards. - -Selected management operations are possible remotely using links exposed by the GUI (after authenticating with the GUI). - -### Logging - -Brooklyn uses the SLF4J logging facade, which allows use of many popular frameworks including java.util.logging, log4j, and logback. - -The convention for log levels is as follows: -* ERROR and above: exceptional situations which indicate that something has unexpectedly failed or -some other problem has occured which the user is expected to attend to -* WARN: exceptional situations which the user may which to know about but which do not necessarily indicate failure or require a response -* INFO: a synopsis of activity, but which should not generate large volumes of events nor overwhelm a human observer -* DEBUG and lower: detail of activity which is not normally of interest, but which might merit closer inspection under certain circumstances. - -Loggers follow the ``package.ClassName`` naming standard. - -It is possible for entities to emit logging activity sensors so that an operator can observe what is occurring within their application through the web console or via programmatic means. - -Examples for testing can be found in some of the poms. - - -<!--- - -<a name="distributed-management"></a> -Distributed Management ----------------------- - -TODO Describe how and when objects become "live", pushed out to other nodes. ---> - -<!--- - -<a name="resilience"></a> -Resilience ----------- -TODO -*This section still needs to be written. Feel free to [fork]({{site.path.guide}}/dev/code) the docs and lend a hand.* ---> - - -Key APIs --------- -<!--- -TODO - brief overview of key APIs ---> -*This section still needs to be written. Feel free to [fork]({{site.path.guide}}/dev/code) the docs and lend a hand.* - -- ``ManagementContext`` (Java management API) -- ``EntityLocal`` (used by policies) - - -<!--- -TODO - describe how to simply configure logging slf4j ---> - -Sensors and Effectors ---------------------- - -### Sensors - -Sensors are typically defined as static named fields on the Entity subclass. These define the channels of events and activity that interested parties can track remotely. For example: -{% highlight java %} -/** a sensor for saying hi (illustrative), carrying a String value - which is typically the name of the person to whom we are saying hi */ -public static final Sensor<String> HELLO_SENSOR = ... - -{% endhighlight %} - -If the entity is local (e.g. to a policy) these can be looked up using ``get(Sensor)``. If it may be remote, you can subscribe to it through various APIs. - -<!--- -TODO probably say about events now, quick reference about SubscriptionManager (either here or in next section on management context) -TODO remaining section on Sensors perhaps should be moved to Writing Entities section? as reader won't need to know too much detail of sensor types to understand policies... though perhaps saying some is right. (Talking about JSON is almost certainly overkill...) ---> - -Sensors are used by operators and policies to monitor health and know when to invoke the effectors. The sensor data forms a nested map (i.e. JSON), which can be subscribed to through the ``ManagementContext``. - -Often ``Policy`` instances will subscribe to sensor events on their associated entity or its children; these events might be an ``AttributeValueEvent`` â an attribute value being reported on change or periodically â or something transient such as ``LogMessage`` or a custom ``Event`` such as "TOO_HOT". - -<!--- -TODO check classes above; is this much detail needed here? ---> - -Sensor values form a map-of-maps. An example of some simple sensor information is shown below in JSON: - - { - config : { - url : "jdbc:mysql://ec2-50-17-19-65.compute-1.amazonaws.com:3306/mysql" - status : "running" - } - workrate : { - msgsPerSec : 432 - } - } - -Sensor values are defined as statics, which can be used to programmatically drive the subscription. -<!--- -TODO , etc., example ---> - -### SubscriptionManager - -*This section is not complete. Feel free to [fork]({{site.path.guide}}/dev/code) the docs and lend a hand.* - -*See the* ``SubscriptionManager`` *class.* -<!--- -TODO ---> - -### Effectors - -Like sensors and config info, effectors are also static fields on the Entity class. These describe actions available on the entity, similar to methods. Their implementation includes details of how to invoke them, typically this is done by calling a method on the entity. Effectors are typically defined as follows: - -{% highlight java %} -/** an effector which returns no value, - but which causes the entity to emit a HELLO sensor event */ -public static Effector<Void> SAY_HI = ... - -{% endhighlight %} - -Effectors are invoked by calling ``invoke(SAY_HI, name:"Bob")`` or similar. The method may take an entity if context is not clear, and it takes parameters as named parameters or a Map. - -Invocation returns a ``Task`` object (extending ``Future``). This allows the caller to understand progress and errors on the task, as well as ``Task.get()`` the return value. Be aware that ``task.get()`` is a blocking function that will wait until a value is available before returning. - -The management framework ensures that execution occurs on the machine where the ``Entity`` is mastered, with progress, result, and/or any errors reported back to the caller. It does this through the ``ExecutionManager`` which, where necessary, creates proxy ``Task`` instances. The ``ExecutionManager`` associates ``Tasks`` with the corresponding ``Entity`` so that these can be tracked externally (and relocated if the Entity is remastered to a different location). - -It is worth noting that where a method corresponds to an effector, direct invocation of that method on an ``Entity`` will implicitly generate the ``Task`` object as though the effector had been invoked. For example, invoking ``Cluster.resize(int)``, where ``resize`` provides an ``Effector RESIZE``, will generate a ``Task`` which can be observed remotely. - -### ExecutionManager - -The ``ExecutionManager`` is responsible for tracking simultaneous executing tasks and associating these with given **tags**. -Arbitrary tasks can be run by calling ``Task submit(Runnable)`` (similarly to the standard ``Executor``, although it also supports ``Callable`` arguments including Groovy closures, and can even be passed ``Task`` instances which have not been started). ``submit`` also accepts a few other named parameters, including ``description``, which allow additional metadata to be kept on the ``Task``. The main benefit then is to have rich metadata for executing tasks, which can be inspected through methods on the ``Task`` interface. - -By using the ``tag`` or ``tags`` named parameters on ``submit`` (or setting ``tags`` in a ``Task`` that is submitted), execution can be associated with various categories. This allows easy viewing can be examined by calling -``ExecutionManager.getTasksWithTag(...)``. - -The following example uses Groovy, with time delays abused for readability. brooklyn's test cases check this using mutexes, which is recommended. - - ExecutionManager em = [] - em.submit(tag:"a", description:"One Mississippi", { Thread.sleep(1000) }) - em.submit(tags:["a","b"], description:"Two Mississippi", { Thread.sleep(1000) }) - assert em.getTasksWithTag("a").size()==2 - assert em.getTasksWithTag("a").every { Task t -> !t.isDone() } - Thread.sleep(1500) - assert em.getTasksWithTag("a").size()==2 - assert em.getTasksWithTag("a").every { Task t -> t.isDone() } - -It is possible to define ParallelTasks and SequentialTasks and to specify inter-task relationships with TaskPreprocessors. This allows building quite sophisticated workflows relatively easily. - -Continuing the example above, submitting a SequentialTasks or specifying ``em.setTaskPreprocessorForTag("a", SingleThreadedExecution.class)`` will cause ``Two Mississippi`` to run after ``One Mississippi`` completes. - -For more information consult the javadoc on these classes and associated tests. - -Note that it is currently necessary to prune dead tasks, either periodically or by the caller. By default they are kept around for reference. It is expected that an enhancement in a future release will allow pruning completed and failed tasks after a specified amount of time. http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/aed2f1c8/docs/guide/ops/webconsole/webconsole-dashboard-w400.png ---------------------------------------------------------------------- diff --git a/docs/guide/ops/webconsole/webconsole-dashboard-w400.png b/docs/guide/ops/webconsole/webconsole-dashboard-w400.png deleted file mode 100644 index 6364dc5..0000000 Binary files a/docs/guide/ops/webconsole/webconsole-dashboard-w400.png and /dev/null differ http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/aed2f1c8/docs/guide/ops/webconsole/webconsole-dashboard.png ---------------------------------------------------------------------- diff --git a/docs/guide/ops/webconsole/webconsole-dashboard.png b/docs/guide/ops/webconsole/webconsole-dashboard.png deleted file mode 100644 index cac5567..0000000 Binary files a/docs/guide/ops/webconsole/webconsole-dashboard.png and /dev/null differ http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/aed2f1c8/docs/guide/ops/webconsole/webconsole-detail-w400.png ---------------------------------------------------------------------- diff --git a/docs/guide/ops/webconsole/webconsole-detail-w400.png b/docs/guide/ops/webconsole/webconsole-detail-w400.png deleted file mode 100644 index b372e55..0000000 Binary files a/docs/guide/ops/webconsole/webconsole-detail-w400.png and /dev/null differ http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/aed2f1c8/docs/guide/ops/webconsole/webconsole-detail.png ---------------------------------------------------------------------- diff --git a/docs/guide/ops/webconsole/webconsole-detail.png b/docs/guide/ops/webconsole/webconsole-detail.png deleted file mode 100644 index 17829cd..0000000 Binary files a/docs/guide/ops/webconsole/webconsole-detail.png and /dev/null differ
