You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@brooklyn.apache.org by sj...@apache.org on 2016/01/05 12:16:27 UTC
[05/10] incubator-brooklyn git commit: Removing previous "Getting
Started" pages.
Removing previous "Getting Started" pages.
Project: http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/repo
Commit: http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/commit/cb76968c
Tree: http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/tree/cb76968c
Diff: http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/diff/cb76968c
Branch: refs/heads/master
Commit: cb76968cd3f978478e1fda3c089e21e69c0e8747
Parents: a5a7d26
Author: Geoff Macartney <ge...@cloudsoftcorp.com>
Authored: Wed Dec 23 15:18:21 2015 +0000
Committer: Geoff Macartney <ge...@cloudsoftcorp.com>
Committed: Wed Dec 23 15:18:21 2015 +0000
----------------------------------------------------------------------
brooklyn-docs/guide/start/blueprints.md | 91 ++++---
brooklyn-docs/guide/start/index.md | 2 +
brooklyn-docs/guide/start/managing.md | 355 ++++++++++++++++++++++++---
brooklyn-docs/guide/start/policies.md | 156 ++++++++++--
brooklyn-docs/website/index.md | 3 +-
docs/guide/start/blueprints-cli.md | 84 -------
docs/guide/start/index-cli.md | 14 --
docs/guide/start/managing-cli.md | 347 --------------------------
docs/guide/start/policies-cli.md | 174 -------------
9 files changed, 527 insertions(+), 699 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/cb76968c/brooklyn-docs/guide/start/blueprints.md
----------------------------------------------------------------------
diff --git a/brooklyn-docs/guide/start/blueprints.md b/brooklyn-docs/guide/start/blueprints.md
index 0ccf664..98eb88e 100644
--- a/brooklyn-docs/guide/start/blueprints.md
+++ b/brooklyn-docs/guide/start/blueprints.md
@@ -7,31 +7,34 @@ children:
- { section: Launching from the Catalog, title: Catalog }
---
-{% include fields.md %}
-
+<div style="width: 100%; display: block; background-color: #CC9966; margin-bottom: 2px; padding: 50px 30px 50px 80px;" >
+ <h3>NOTE</h3>
+ <div>
+ The structure of Brooklyn's repositories is changing at present (Jan 2016). Until this is complete
+ please obtain the "br" command line tool from <a href="https://github.com/brooklyncentral/brooklyn-cli">Brooklyn Central</a>
+ </div>
+</div>
## Launching from a Blueprint
-We'll start by deploying an application via YAML blueprint consisting of the following layers.
-
-- Nginx load balancer
-- Tomcat app server cluster
-- MySQL DB
-
-When you first access the web console on [127.0.0.1:8081](http://127.0.0.1:8081) you will be requested to create your first application.
-
+We'll start by deploying an application with a simple YAML blueprint containing a Tomcat server.
-[](images/add-application-modal-yaml-large.png)
-
-Switch to the YAML tab and copy the blueprint below into the large text box.
-
-But *before* you submit it, modify the YAML to specify the location where the application will be deployed.
+Copy the blueprint below into a text file, "myapp.yaml", in your workspace, but *before* you create an application with
+it, modify the YAML to specify the location where the application will be deployed. (Note, to copy the file you can
+hover your mouse over the right side of the text box below to get a Javascript "copy" button.)
{% highlight yaml %}
-{% readj _my-web-cluster.yaml %}
+name: Tomcat
+location:
+ jclouds:aws-ec2:
+ identity: ABCDEFGHIJKLMNOPQRST
+ credential: s3cr3tsq1rr3ls3cr3tsq1rr3ls3cr3tsq1rr3l
+services:
+- serviceType: brooklyn.entity.webapp.tomcat.TomcatServer
{% endhighlight %}
-Replace the `location:` element with values for your chosen target environment, for example to use SoftLayer rather than AWS (updating with your own credentials):
+Replace the `location:` element with values for your chosen target environment, for example to use SoftLayer rather
+than AWS (updating with your own credentials):
{% highlight yaml %}
location:
@@ -40,26 +43,54 @@ location:
credential: s3cr3tsq1rr3ls3cr3tsq1rr3ls3cr3tsq1rr3l
{% endhighlight %}
-**Note**: See __[Locations](../ops/locations)__ in the Operations section of the User Guide for instructions on setting up alternate cloud providers, bring-your-own-nodes, or localhost targets, and storing credentials/locations in a file on disk rather than in the blueprint.
+Or, if you already have machines provisioned, you can use the "bring your own nodes" (byon) approach.
+Of course, replace the identity and address values below with your own values.
+{% highlight yaml %}
+location:
+ byon:
+ user: myuser
+ password: mypassword
+ # or...
+ #privateKeyFile: ~/.ssh/my.pem
+ hosts:
+ - 192.168.0.18
+ - 192.168.0.19
+{% endhighlight %}
+
+**Note**: See __[Locations](../ops/locations)__ in the Operations section of the User Guide for instructions on setting
+up alternate cloud providers, bring-your-own-nodes, or localhost targets, and storing credentials/locations in a file
+on disk rather than in the blueprint.
+(For the application above, if you are using a "Bring your own Nodes" location, you will need at least three nodes.)
+
+First you will have to log in to brooklyn:
+{% highlight bash %}
+$ br login http://localhost:8081/
+{% endhighlight %}
-With the modified YAML in the dialog, click "Finish". The dialog will close and Brooklyn will begin deploying your
-application. Your application will be shown as "Starting" on the web console's front page.
+To secure the server you can add a username and password in Brooklyn's properties file, as described in the User Guide.
+Then the login command will require the additional parameters of the userid and password.
-Depending on your choice of location it may take some time for the application nodes to start, the next page describes how you can monitor the progress of the application deployment and verify its successful deployment.
+Now you can create the application with the command below:
-### Launching from the Catalog
+{% highlight bash %}
+$ br deploy myapp.yaml
+Id: hTPAF19s
+Name: Tomcat
+Status: In progress
+{% endhighlight %}
-Instead of pasting the YAML blueprint each time, it can be added to Brooklyns Catalog where it will be accessible from the Catalog tab of the Create Application dialog.
+Depending on your choice of location it may take some time for the application to start, the next page describes how
+you can monitor the progress of the application deployment and verify its successful deployment.
-[](images/add-application-catalog-web-cluster-with-db-large.png)
-<!-- TODO: more detail for adding to catalog? but wait for persistence to be the default,
- rather than extensively document default.catalog.bom.
- also need to include instructions on stopping (currently in help, including stopping apps) -->
+## Launching from the Catalog
+Instead of pasting the YAML blueprint each time, it can be added to Brooklyns Catalog where it will be accessible
+for use in any blueprint that you want to deploy.
-See __[Catalog](../ops/catalog/)__ in the Operations section of the User Guide for instructions on creating a new Catalog entry from your Blueprint YAML.
+See __[Catalog](../ops/catalog/)__ in the Operations section of the User Guide for instructions on creating a new
+Catalog entry from your Blueprint YAML.
-## Next
+## Next
-So far we have touched on Brooklyn's ability to *deploy* an application blueprint to a cloud provider, but this just the beginning, proceed to **[Monitoring and Managing Applications](managing.html)**.
+Having deployed an application, the next step is **[monitoring and managing](managing.html)** it.
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/cb76968c/brooklyn-docs/guide/start/index.md
----------------------------------------------------------------------
diff --git a/brooklyn-docs/guide/start/index.md b/brooklyn-docs/guide/start/index.md
index ccd6f6f..ea8c2a3 100644
--- a/brooklyn-docs/guide/start/index.md
+++ b/brooklyn-docs/guide/start/index.md
@@ -10,3 +10,5 @@ children:
---
{% include list-children.html %}
+
+
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/cb76968c/brooklyn-docs/guide/start/managing.md
----------------------------------------------------------------------
diff --git a/brooklyn-docs/guide/start/managing.md b/brooklyn-docs/guide/start/managing.md
index 7139f32..79937bd 100644
--- a/brooklyn-docs/guide/start/managing.md
+++ b/brooklyn-docs/guide/start/managing.md
@@ -3,68 +3,357 @@ title: Monitoring and Managing Applications
title_in_menu: Monitoring and Managing Applications
layout: website-normal
menu_parent: index.md
+children:
+- { section: Applications }
+- { section: Entities }
+- { section: Sensors }
+- { section: Effectors }
+- { section: Activities }
---
-Click on the application name, or open the Applications tab.
-We can explore the management hierarchy of the application, which will show us the entities it is composed of.
- * My Web Cluster (A `BasicApplication`)
- * My DB (A `MySqlNode`)
- * My Web (A `ControlledDynamicWebAppCluster`)
- * Cluster of TomcatServer (A `DynamicWebAppCluster`)
- * NginxController (An `NginxController`)
+So far we have touched on Brooklyn's ability to *deploy* an application blueprint to a cloud provider, but this just
+the beginning. The sections below outline how to manage the application that has been deployed.
+## Scopes in CLI commands
+Many commands require a "scope" expression to indicate the target on which they operate. The scope expressions are
+as follows (values in brackets are aliases for the scope):
-Clicking on the "My Web Cluster" entity will show the "Summary" tab,
-giving a very high level of what that component is doing.
-Click on each of the child components in turn for more detail on that component.
-Note that the cluster of web servers includes a "quarantine group", to which members of the
-cluster that fail will be added. These are excluded from the load-balancer's targets.
+- application APP-ID (app, a)
+ Selects an application, e.g. "br app myapp"
+- entity ENT-ID (ent, e)
+ Selects an entity within an application scope, e.g. "br app myapp ent myserver"
+- effector EFF-ID (eff, f)
+ Selects an effector of an entity or application, e.g. "br a myapp e myserver eff xyz"
+- config CONF-KEY (conf, con, c)
+ Selects a configuration key of an entity e.g. "br a myapp e myserver config jmx.agent.mode"
+- activity ACT-ID (act, v)
+ Selects an activity of an entity e.g. "br a myapp e myserver act iHG7sq1"
-[](images/my-web-large.png)
+For example
+{% highlight bash %}
+$ br app Tomcat ent TomcatServer:Wx7r config
+{% endhighlight %}
+runs the "config" command with application scope of "Tomcat" and entity scope of "TomcatServer:Wx7r".
+## Applications
-## Activities
+Having created the application we can query its status. We can find a summary of all deployed apps:
+{% highlight bash %}
+$ br application
+ Id Name Status Location
+ hTPAF19s Tomcat RUNNING ajVVAhER
+{% endhighlight %}
+
+"application" can be shortened to one of the aliases "app" or just "a", for example:
+{% highlight bash %}
+$ br app
+ Id Name Status Location
+ hTPAF19s Tomcat RUNNING ajVVAhER
+{% endhighlight %}
+
+You can find the details of a given application, using its name or ID.
+{% highlight bash %}
+$ br app Tomcat
+ Id: hTPAF19s
+ Name: Tomcat
+ Status: RUNNING
+ ServiceUp: true
+ Type: org.apache.brooklyn.entity.stock.BasicApplication
+ CatalogItemId: null
+ LocationId: ajVVAhER
+ LocationName: FixedListMachineProvisioningLocation:ajVV
+ LocationSpec: vagrantbyon
+ LocationType: org.apache.brooklyn.location.byon.FixedListMachineProvisioningLocation
+{% endhighlight %}
+
+To ease management of multiple applications, or even to reduce the amount of typing required, it is convenient
+to create an alias for the commonly used application scope:
+{% highlight bash %}
+alias tom="br app Tomcat"
+{% endhighlight %}
+
+To illustrate this we will assume the above alias for the rest of this section, but to avoid confusion
+the examples in other sections will show the full command in all cases.
+
+We can explore the management hierarchy of all applications, which will show us the entities they are composed of.
+{% highlight bash %}
+$ br tree
+|- Tomcat
++- org.apache.brooklyn.entity.stock.BasicApplication
+ |- TomcatServer:Wx7r
+ +- org.apache.brooklyn.entity.webapp.tomcat.TomcatServer
+{% endhighlight %}
-The Activity tab allows us to drill down into the tasks each entity is currently executing or has recently completed. It is possible to drill down through all child tasks, and view the commands issued, along with any errors or warnings that occurred.
+You can view the blueprint for the application again:
+{% highlight bash %}
+$ tom spec
+"name: Tomcat\nlocation:\n mylocation\nservices:\n- serviceType: brooklyn.entity.webapp.tomcat.TomcatServer\n"
+{% endhighlight %}
-For example clicking on the NginxController in the left hand tree and opening its Activity tab you can observe the 'start' task is 'In progress'.
+You can view the config of the application:
+{% highlight bash %}
+$ tom config
+Key Value
+camp.template.id l67i25CM
+brooklyn.wrapper_app true
+{% endhighlight %}
-**Note**: You may observe different tasks depending on how far your deployment has progressed).
+## Entities
+To explore the entities of the application you can use the "entity" command. This will show the
+immediate child entities of a given application or one of its child entities.
-[](images/my-db-activities-step1-large.png)
+{% highlight bash %}
+$ br app Tomcat entity
+Id Name Type
+Wx7r1C4e TomcatServer:Wx7r org.apache.brooklyn.entity.webapp.tomcat.TomcatServer
+{% endhighlight %}
-Clicking on the 'start' task you can discover more details on the actions being carried out by that task (a task may consist of additional subtasks).
+"entity" has aliases "ent" or "e".
-[](images/my-db-activities-step2-large.png)
+You can get summary information for an entity by providing its name (or ID).
-Continuing to drill down into the 'In progress' tasks you will eventually reach the currently active task where you can investigate the ssh command executed on the target node including the current stdin, stdout and stderr output.
+{% highlight bash %}
+$ br app Tomcat ent TomcatServer:Wx7r
+Id: Wx7r1C4e
+Name: TomcatServer:Wx7r
+Status: RUNNING
+ServiceUp: true
+Type: org.apache.brooklyn.entity.webapp.tomcat.TomcatServer
+CatalogItemId: null
+{% endhighlight %}
-[](images/my-db-activities-step3-large.png)
+Also you can see the config of the entity with the "config" command.
+{% highlight bash %}
+$ br app Tomcat ent TomcatServer:Wx7r config
+Key Value
+jmx.agent.mode JMXMP_AND_RMI
+brooklyn.wrapper_app true
+camp.template.id yBcQuFZe
+onbox.base.dir /home/vagrant/brooklyn-managed-processes
+onbox.base.dir.resolved true
+install.unique_label TomcatServer_7.0.65
+{% endhighlight %}
+
+If an entity name is annoyingly long to type, the entity can be renamed:
+
+{% highlight bash %}
+$ br app Tomcat ent TomcatServer:Wx7r rename server
+{% endhighlight %}
## Sensors
-Now click on the "Sensors" tab:
-these data feeds drive the real-time picture of the application.
-As you navigate in the tree at the left, you can see more targeted statistics coming in in real-time.
+"Sensors" on entities provide a real-time picture of the status and operation of an entity of the application.
+
+To view the sensors on the application itself, use the command below:
+
+{% highlight bash %}
+$ br app Tomcat sensor
+Name Description Value
+service.isUp Whether the service is active and availability (confirmed and monitored) true
+service.notUp.indicators A map of namespaced indicators that the service is not up {}
+service.problems A map of namespaced indicators of problems with a service {}
+service.state Actual lifecycle state of the service "RUNNING"
+service.state.expected Last controlled change to service state, indicating what the expected state should be "running @ 1450356994928 / Thu Dec 17 12:56:34 GMT 2015"
+{% endhighlight %}
+
+To explore all sensors available on an entity use the sensor command with an entity scope.
+Note, again, the name of the application or entity can be used or the ID:
+
+{% highlight bash %}
+br app Tomcat ent TomcatServer:Wx7r sensor
+Name Description Value
+download.addon.urls URL patterns for downloading named add-ons (will substitute things like ${version} automatically)
+download.url URL pattern for downloading the installer (will substitute things like ${version} automatically) "http://download.nextag.com/apache/tomcat/tomcat-7/v${version}/bin/apache-tomcat-${version}.tar.gz"
+expandedinstall.dir Directory for installed artifacts (e.g. expanded dir after unpacking .tgz) "/home/vagrant/brooklyn-managed-processes/installs/TomcatServer_7.0.65/apache-tomcat-7.0.65"
+host.address Host IP address "10.10.10.101"
+host.name Host name "10.10.10.101"
+host.sshAddress user@host:port for ssh'ing (or null if inappropriate) "vagrant@10.10.10.101:22"
+host.subnet.address Host address as known internally in the subnet where it is running (if different to host.name) "10.10.10.101"
+host.subnet.hostname Host name as known internally in the subnet where it is running (if different to host.name) "10.10.10.101"
+# etc. etc.
+{% endhighlight %}
+
+
+To study selected sensors, give the command the sensor name as an argument
+
+{% highlight bash %}
+$ br app Tomcat ent TomcatServer:Wx7r sensor webapp.url
+"http://10.10.10.101:8080/"
+{% endhighlight %}
+
+
+## Effectors
+
+Effectors are the means by which you can manipulate the entities in an application. For an application you can list them
+with
+
+{% highlight bash %}
+$ br app Tomcat effector
+Name Description Parameters
+restart Restart the process/service represented by an entity
+start Start the process/service represented by an entity locations
+stop Stop the process/service represented by an entity
+{% endhighlight %}
+
+For an entity supply the entity scope:
+
+{% highlight bash %}
+$ br app Tomcat ent TomcatServer:Wx7r effector
+Name Description Parameters
+deploy Deploys the given artifact, from a source URL, to a given deployment filename/context url,targetName
+populateServiceNotUpDiagnostics Populates the attribute service.notUp.diagnostics, with any available health indicators
+restart Restart the process/service represented by an entity restartChildren,restartMachine
+start Start the process/service represented by an entity locations
+stop Stop the process/service represented by an entity stopProcessMode,stopMachineMode
+undeploy Undeploys the given context/artifact targetName
+{% endhighlight %}
+
+To view just one effector's documentation, supply its name to the show command:
+
+{% highlight bash %}
+$ br app Tomcat ent TomcatServer:Wx7r effector deploy
+Name Description Parameters
+deploy Deploys the given artifact, from a source URL, to a given deployment filename/context url,targetName
+{% endhighlight %}
+
+These effectors can be invoked using the command "invoke", supplying the application and entity id of the entity to
+invoke the effector on.
+
+For example, to stop an application, use the "stop" effector. This will cleanly shutdown all components in the
+application and return any cloud machines that were being used. Do the invocation by supplying the effector name in
+the scope, and using the command 'invoke'.
+
+{% highlight bash %}
+$ br app Tomcat ent TomcatServer:Wx7r eff stop invoke
+{% endhighlight %}
+
+Note that the three "lifecycle" related effectors, start, stop, and restart, are common to all software process
+entities in Brooklyn. They are so commonly used that they have their own aliases. The above could also have been done
+by:
+
+{% highlight bash %}
+$ br app Tomcat ent TomcatServer:Wx7r stop
+{% endhighlight %}
+
+Some effectors require parameters for their invocation, as in the example of "deploy" above.
+
+{% highlight bash %}
+br app Tomcat ent TomcatServer:Wx7r effector deploy
+Name Description Parameters
+deploy Deploys the given artifact, from a source URL, to a given deployment filename/context url,targetName
+{% endhighlight %}
+
+Now the effector can be invoked by supplying the parameters using ```--param parm=value``` or just ```-P parm=value```.
+
+In the example below, a sample Tomcat war file is deployed, a variable is created for the root URL using the appropriate
+sensor, and the index page is fetched. Note that at present a "tr" command is required in the second line below to strip
+quotation characters from the returned sensor value.
+
+{% highlight bash %}
+$ br app Tomcat ent TomcatServer:Wx7r effector deploy invoke -P url=https://tomcat.apache.org/tomcat-6.0-doc/appdev/sample/sample.war -P targetName=sample
+$ webapp=$(br app Tomcat ent TomcatServer:Wx7r sensor webapp.url | tr -d '"')
+$ curl $webapp/sample/
+<html>
+<head>
+<title>Sample "Hello, World" Application</title>
+</head>
+# etc. etc.
+{% endhighlight %}
+
+
+## Activities
+
+The 'activity' command allows us to investigate the activities of an entity.
+
+To view a list of all activities associated with an entity simply use
+
+{% highlight bash %}
+$ br app Tomcat ent TomcatServer:Wx7r activity
+Id Task Submitted Status Streams
+LtD5P1cb start Thu Dec 17 15:04:43 GMT 2015 Completed
+l2qo4vTl provisioning (FixedListMachineProvisi... Thu Dec 17 15:04:43 GMT 2015 Completed
+wLD764HE pre-start Thu Dec 17 15:04:43 GMT 2015 Completed
+KLTxDkoa ssh: initializing on-box base dir ./b... Thu Dec 17 15:04:43 GMT 2015 Completed env,stderr,stdin,stdout
+jwwcJWmF start (processes) Thu Dec 17 15:04:43 GMT 2015 Completed
+# etc. etc.
+{% endhighlight %}
+
+To view the details of an individual activity provide its ID:
+
+{% highlight bash %}
+$ br app Tomcat ent TomcatServer:Wx7r activity jwwcJWmF
+Id: jwwcJWmF
+DisplayName: start (processes)
+Description:
+EntityId: efUvVWAw
+EntityDisplayName: TomcatServer:efUv
+Submitted: Thu Dec 17 15:04:43 GMT 2015
+Started: Thu Dec 17 15:04:43 GMT 2015
+Ended: Thu Dec 17 15:08:59 GMT 2015
+CurrentStatus: Completed
+IsError: false
+IsCancelled: false
+SubmittedByTask: LtD5P1cb
+Streams:
+DetailedStatus: "Completed after 4m 16s
+
+No return value (null)"
+{% endhighlight %}
+
+If an activity has failed, the "DetailedStatus" value will show information about the failure, as an aid to diagnosis.
+
+Adding the "--children" or "-c" parameter will show the activity's child activities, to allow the hierarchical structure
+of the activities to be investigated:
+
+{% highlight bash %}
+$ br app Tomcat ent TomcatServer:Wx7r activity -c jwwcJWmF
+Id Task Submitted Status
+UpYRc3fw copy-pre-install-resources Thu Dec 17 15:04:43 GMT 2015 Completed
+ig8sBHQr pre-install Thu Dec 17 15:04:43 GMT 2015 Completed
+Elp4HaVj pre-install-command Thu Dec 17 15:04:43 GMT 2015 Completed
+YOvNobJk setup Thu Dec 17 15:04:43 GMT 2015 Completed
+VN3cDKki copy-install-resources Thu Dec 17 15:08:43 GMT 2015 Completed
+xDJXQC0J install Thu Dec 17 15:08:43 GMT 2015 Completed
+zxMDXUxz post-install-command Thu Dec 17 15:08:58 GMT 2015 Completed
+qnQnw7Oc customize Thu Dec 17 15:08:58 GMT 2015 Completed
+ug044ArS copy-runtime-resources Thu Dec 17 15:08:58 GMT 2015 Completed
+STavcRc8 pre-launch-command Thu Dec 17 15:08:58 GMT 2015 Completed
+HKrYfH6h launch Thu Dec 17 15:08:58 GMT 2015 Completed
+T1m8VXbq post-launch-command Thu Dec 17 15:08:59 GMT 2015 Completed
+n8eK5USE post-launch Thu Dec 17 15:08:59 GMT 2015 Completed
+{% endhighlight %}
-Explore the sensors and the tree to find the URL where the _NginxController_ for the webapp we just deployed is running. This can be found in '**My Web Cluster** -> **My Web** -> **NginxController** -> **_main.uri_**'.
+If an activity has associated input and output streams, these may be viewed by providing the activity scope and
+using the commands, "env", "stdin", "stdout", and "stderr". For example, for the "initializing on-box base dir"
+activity from the result of the earlier example,
-Quickly return to the **‘Brooklyn JS REST client’** web browser
-tab showing the "Sensors" and observe the '**My Web Cluster** -> **My Web** -> **Cluster of TomcatServer** -> **_webapp.reqs.perSec.last_**' sensor value increase.
+{% highlight bash %}
+$ br app Tomcat ent TomcatServer:Wx7r act KLTxDkoa stdout
+BASE_DIR_RESULT:/home/vagrant/brooklyn-managed-processes:BASE_DIR_RESULT
+{% endhighlight %}
-## Stopping the Application
+To monitor progress on an application as it deploys, for example, one could use a shell loop:
-To stop an application, select the application in the tree view (the top/root entity), click on the Effectors tab, and invoke the "Stop" effector. This will cleanly shutdown all components in the application and return any cloud machines that were being used.
+{% highlight bash %}
+$ while br app Tomcat ent TomcatServer:Wx7r activity | grep 'In progress' ; do
+ sleep 1; echo ; date;
+done
+{% endhighlight %}
+This loop will exit when the application has deployed successfully or has failed. If it fails then the 'stderr'
+command may provide information about what happened in any activities that have associated streams:
-[](images/my-web-cluster-stop-confirm-large.png)
+{% highlight bash %}
+$ br app Tomcat ent TomcatServer:Wx7r act KLTxDkoa stderr
+{% endhighlight %}
-### Next
+## Next
-Brooklyn's real power is in using **[Policies](policies.html)** to automatically *manage* applications.
+We will look next at a slightly more complex example, which will illustrate the capabilities of Brooklyn's
+**[policies](policies.html)** mechanism, and how to configure dependencies between application entities.
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/cb76968c/brooklyn-docs/guide/start/policies.md
----------------------------------------------------------------------
diff --git a/brooklyn-docs/guide/start/policies.md b/brooklyn-docs/guide/start/policies.md
index b1029b2..c23f0b2 100644
--- a/brooklyn-docs/guide/start/policies.md
+++ b/brooklyn-docs/guide/start/policies.md
@@ -2,50 +2,176 @@
title: Getting Started - Policies
title_in_menu: Policies
layout: website-normal
+menu_parent: index.md
+children:
+- { section: "A Clustered Example", title_in_menu: "Clustering" }
+- { section: "Configuring Dependencies", title_in_menu: "Dependencies" }
+- { section: "Managing with Policies", title_in_menu: "Policies" }
---
-### Exploring and Testing Policies
-To see an example of policy based management, please deploy the following blueprint:
+## A Clustered Example
+
+We'll now look at a more complex example that better shows the capabilities of Brooklyn.
+
+We'll start by deploying an application via YAML blueprint consisting of the following layers.
+
+- A dynamically scalable Web App Cluster
+- A MySQL DB
+
+
+Copy the blueprint below into a text file, "mycluster.yaml", in your workspace, but *before* you create an application
+with it, again modify the YAML to specify the location where the application will be deployed.
+You will need at least five machines for this example, one for the DB, and four for the tomcats
+(but you can reduce this by changing the "maxPoolSize" below.
+
+{% highlight yaml %}
+name: cluster
+
+location:
+ jclouds:aws-ec2:
+ identity: ABCDEFGHIJKLMNOPQRST
+ credential: s3cr3tsq1rr3ls3cr3tsq1rr3ls3cr3tsq1rr3l
+
+
+services:
+- serviceType: brooklyn.entity.webapp.ControlledDynamicWebAppCluster
+ name: webcluster
+ brooklyn.config:
+ wars.root: http://search.maven.org/remotecontent?filepath=io/brooklyn/example/brooklyn-example-hello-world-sql-webapp/0.6.0-M2/brooklyn-example-hello-world-sql-webapp-0.6.0-M2.war
+ http.port: 9280+
+ proxy.http.port: 9210+
+ java.sysprops:
+ brooklyn.example.db.url: $brooklyn:formatString("jdbc:%s%s?user=%s\\&password=%s",
+ component("db").attributeWhenReady("datastore.url"), "visitors", "brooklyn", "br00k11n")
+ brooklyn.policies:
+ - policyType: brooklyn.policy.autoscaling.AutoScalerPolicy
+ brooklyn.config:
+ metric: $brooklyn:sensor("brooklyn.entity.webapp.DynamicWebAppCluster", "webapp.reqs.perSec.windowed.perNode")
+ metricLowerBound: 10
+ metricUpperBound: 100
+ minPoolSize: 1
+ maxPoolSize: 4
+
+- serviceType: brooklyn.entity.database.mysql.MySqlNode
+ id: db
+ name: mysql
+ brooklyn.config:
+ creationScriptUrl: https://bit.ly/brooklyn-visitors-creation-script
+{% endhighlight %}
+
+Explore this app using the 'application' and other commands from the previous section.
+
+## Configuring Dependencies
+The App above illustrates how one component in a blueprint can be configured with information relating to one of the other
+components in the blueprint. In this example the web cluster is configured with a URL for JDBC connections to the database.
+{% highlight yaml %}
+java.sysprops:
+ brooklyn.example.db.url: $brooklyn:formatString("jdbc:%s%s?user=%s\\&password=%s",
+ component("db").attributeWhenReady("datastore.url"), "visitors", "brooklyn", "br00k11n")
+{% endhighlight %}
+
+the syntax ```$brooklyn:formatString(...)``` is an example of the Brooklyn DSL (Domain Specific Language) which
+allows expressions referring to Brooklyn's management information to be embedded in blueprints. The line above also illustrates the use of Brooklyn's ```component(...)``` and ```attributeWhenReady(...)``` to get an identified component from a deployment, and to wait until the component is fully deployed before reading one of its sensors ("datastore.url" in this case).
+
+## Managing with Policies
+
+
+The app server cluster has an `AutoScalerPolicy`and the loadbalancer has a `Controller targets tracker` policy.
+
+For example
{% highlight yaml %}
-{% readj _my-web-cluster2.yaml %}
+$ br app cluster ent webcluster policy
+Id Name State
+mMZngBnb org.apache.brooklyn.policy.autoscaling.AutoScalerPolicy RUNNING
{% endhighlight %}
-The app server cluster has an `AutoScalerPolicy`, and the loadbalancer has a `targets` policy.
+You can investigate the status of the `AutoScalerPolicy` with
-Use the Applications tab in the web console to drill down into the Policies section of the ControlledDynamicWebAppCluster. You will see that the `AutoScalerPolicy` is running.
+{% highlight yaml %}
+$ br app cluster ent webcluster policy org.apache.brooklyn.policy.autoscaling.AutoScalerPolicy
+"RUNNING"
+{% endhighlight %}
+
+A more detailed description of the parameters of the policy can be obtained with
+{% highlight yaml %}
+$ br app cluster ent webcluster policy org.apache.brooklyn.policy.autoscaling.AutoScalerPolicy
+Name Value Description
+autoscaler.currentSizeOperator org.apache.brooklyn.policy.autoscaling.AutoScalerPolicy$4@9393100
+autoscaler.entityWithMetric The Entity with the metric that will be monitored
+autoscaler.maxPoolSize 4
+autoscaler.maxReachedNotificationDelay 0ms Time that we consistently wanted to go above the maxPoolSize for, after which the maxSizeReachedSensor (if any) will be emitted
+autoscaler.maxSizeReachedSensor Sensor for which a notification will be emitted (on the associated entity) when we consistently wanted to resize the pool above the max allowed size, for maxReachedNotificationDelay milliseconds
+autoscaler.metric Sensor: webapp.reqs.perSec.windowed.perNode (java.lang.Double)
+autoscaler.metricLowerBound 10 The lower bound of the monitored metric. Below this the policy will resize down
+autoscaler.metricUpperBound 100 The upper bound of the monitored metric. Above this the policy will resize up
+autoscaler.minPeriodBetweenExecs 100ms
+autoscaler.minPoolSize 1
+autoscaler.poolColdSensor Sensor: resizablepool.cold (java.util.Map)
+autoscaler.poolHotSensor Sensor: resizablepool.hot (java.util.Map)
+autoscaler.poolOkSensor Sensor: resizablepool.cold (java.util.Map)
+autoscaler.resizeDownIterationIncrement 1 Batch size for resizing down; the size will be decreased by a multiple of this value
+autoscaler.resizeDownIterationMax 2147483647 Maximum change to the size on a single iteration when scaling down
+autoscaler.resizeDownStabilizationDelay 0ms
+autoscaler.resizeOperator org.apache.brooklyn.policy.autoscaling.AutoScalerPolicy$3@387a7e10
+autoscaler.resizeUpIterationIncrement 1 Batch size for resizing up; the size will be increased by a multiple of this value
+autoscaler.resizeUpIterationMax 2147483647 Maximum change to the size on a single iteration when scaling up
+autoscaler.resizeUpStabilizationDelay 0ms
+{% endhighlight %}
-This policy automatically scales the cluster up or down to be the right size for the cluster's current load. One server is the minimum size allowed by the policy.
+The loadbalancer's `Controller targets tracker` policy ensures that the loadbalancer is updated as the cluster size changes.
-The loadbalancer's `targets` policy ensures that the loadbalancer is updated as the cluster size changes.
+This policy automatically scales the cluster up or down to be the right size for the cluster's current load. One server
+is the minimum size allowed by the policy.
-Sitting idle, this cluster will only contain one server, but you can use a tool like [jmeter](http://jmeter.apache.org/) pointed at the nginx endpoint to create load on the cluster. Download a jmeter test plan [here](https://github.com/apache/incubator-brooklyn/blob/master/examples/simple-web-cluster/resources/jmeter-test-plan.jmx).
+Sitting idle, this cluster will only contain one server, but you can use a tool like [jmeter](http://jmeter.apache.org/)
+pointed at the nginx endpoint to create load on the cluster. Download a jmeter test
+plan [here](https://github.com/apache/incubator-brooklyn/blob/master/examples/simple-web-cluster/resources/jmeter-test-plan.jmx).
-As load is added, Apache Brooklyn requests a new cloud machine, creates a new app server, and adds it to the cluster. As load is removed, servers are removed from the cluster, and the infrastructure is handed back to the cloud.
+As load is added, Apache Brooklyn requests a new cloud machine, creates a new app server, and adds it to the cluster.
+As load is removed, servers are removed from the cluster, and the infrastructure is handed back to the cloud.
### Under the Covers
The `AutoScalerPolicy` here is configured to respond to the sensor
reporting requests per second per node, invoking the default `resize` effector.
-By clicking on the policy, you can configure it to respond to a much lower threshhold
+By updating on the policy, you can configure it to respond to a much lower threshhold
or set long stabilization delays (the period before it scales out or back).
-An even simpler test is to manually suspend the policy, by clicking "Suspend" in the policies list.
-You can then switch to the "Effectors" tab and manually trigger a `resize`.
+At present the CLI does not support a command to update a policy.
+
+However it is possible to manually suspend the policy, by
+
+{% highlight bash %}
+$ br app cluster ent webcluster stop-policy org.apache.brooklyn.policy.autoscaling.AutoScalerPolicy
+
+{% endhighlight %}
+
+You can then invoke a `resize` using the appropriate effector:
+{% highlight bash %}
+$ br app cluster ent webcluster effector resize invoke -P desiredSize=3
+{% endhighlight %}
+
On resize, new nodes are created and configured,
and in this case a policy on the nginx node reconfigures nginx whenever the set of active
targets changes.
+The policy can then be re-enabled with start-policy:
+
+{% highlight bash %}
+$ br app cluster ent webcluster start-policy org.apache.brooklyn.policy.autoscaling.AutoScalerPolicy
+
+{% endhighlight %}
-### Next
+
+## Next
This guide has given a quick overview to writing blueprints for applications, deploying applications, and
managing them. Next, learn more about any of:
* [Writing Blueprints with YAML](../yaml/)
* [Writing Blueprints with Java](../java/)
-* [Operating Brooklyn](../ops/)
-
+* [Operating Brooklyn](../ops/)
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/cb76968c/brooklyn-docs/website/index.md
----------------------------------------------------------------------
diff --git a/brooklyn-docs/website/index.md b/brooklyn-docs/website/index.md
index 7f2f56e..e419488 100644
--- a/brooklyn-docs/website/index.md
+++ b/brooklyn-docs/website/index.md
@@ -5,8 +5,7 @@ landing: true
children:
- learnmore/
- { path: download/, menu: null }
-- { path: /guide/start/index.md, title_in_menu: Get Started, href_path: /guide/start/running.md}
-- { path: /guide/start/index-cli.md, title_in_menu: CLI Get Started, href_path: /guide/start/index-cli.md}
+- { path: /guide/start/index.md, title_in_menu: Get Started, href_path: /guide/start/index.md}
- path: documentation/
menu:
- { path: /guide/index.md, title_in_menu: "User Guide",
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/cb76968c/docs/guide/start/blueprints-cli.md
----------------------------------------------------------------------
diff --git a/docs/guide/start/blueprints-cli.md b/docs/guide/start/blueprints-cli.md
deleted file mode 100644
index 79cd1bb..0000000
--- a/docs/guide/start/blueprints-cli.md
+++ /dev/null
@@ -1,84 +0,0 @@
----
-title: Deploying Blueprints
-layout: website-normal
-menu_parent: index-cli.md
-children:
-- { section: Launching from a Blueprint, title: Blueprint }
-- { section: Launching from the Catalog, title: Catalog }
----
-
-
-## Launching from a Blueprint
-
-We'll start by deploying an application with a simple YAML blueprint containing a Tomcat server.
-
-Copy the blueprint below into a text file, "myapp.yaml", in your workspace, but *before* you create an application with
-it, modify the YAML to specify the location where the application will be deployed. (Note, to copy the file you can
-hover your mouse over the right side of the text box below to get a Javascript "copy" button.)
-
-{% highlight yaml %}
-name: Tomcat
-location:
- jclouds:aws-ec2:
- identity: ABCDEFGHIJKLMNOPQRST
- credential: s3cr3tsq1rr3ls3cr3tsq1rr3ls3cr3tsq1rr3l
-services:
-- serviceType: brooklyn.entity.webapp.tomcat.TomcatServer
-{% endhighlight %}
-
-Replace the `location:` element with values for your chosen target environment, for example to use SoftLayer rather
-than AWS (updating with your own credentials):
-
-{% highlight yaml %}
-location:
- jclouds:softlayer:
- identity: ABCDEFGHIJKLMNOPQRST
- credential: s3cr3tsq1rr3ls3cr3tsq1rr3ls3cr3tsq1rr3l
-{% endhighlight %}
-
-Or, if you already have machines provisioned, you can use the "bring your own nodes" (byon) approach.
-Of course, replace the identity and address values below with your own values.
-{% highlight yaml %}
-location:
- byon:
- user: myuser
- password: mypassword
- # or...
- #privateKeyFile: ~/.ssh/my.pem
- hosts:
- - 192.168.0.18
- - 192.168.0.19
-{% endhighlight %}
-
-**Note**: See __[Locations](../ops/locations)__ in the Operations section of the User Guide for instructions on setting
-up alternate cloud providers, bring-your-own-nodes, or localhost targets, and storing credentials/locations in a file
-on disk rather than in the blueprint.
-(For the application above, if you are using a "Bring your own Nodes" location, you will need at least three nodes.)
-
-First you will have to log in to brooklyn:
-{% highlight bash %}
-$ br login http://localhost:8081/
-{% endhighlight %}
-
-To secure the server you can add a username and password in Brooklyn's properties file, as described in the User Guide.
-Then the login command will require the additional parameters of the userid and password.
-
-Now you can create the application with the command below:
-
-{% highlight bash %}
-$ br deploy myapp.yaml
-Id: hTPAF19s
-Name: Tomcat
-Status: In progress
-{% endhighlight %}
-
-Depending on your choice of location it may take some time for the application to start, the next page describes how
-you can monitor the progress of the application deployment and verify its successful deployment.
-
-
-## Launching from the Catalog
-Instead of pasting the YAML blueprint each time, it can be added to Brooklyns Catalog where it will be accessible
-for use in any blueprint that you want to deploy.
-
-See __[Catalog](../ops/catalog/)__ in the Operations section of the User Guide for instructions on creating a new
-Catalog entry from your Blueprint YAML.
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/cb76968c/docs/guide/start/index-cli.md
----------------------------------------------------------------------
diff --git a/docs/guide/start/index-cli.md b/docs/guide/start/index-cli.md
deleted file mode 100644
index e2e76c1..0000000
--- a/docs/guide/start/index-cli.md
+++ /dev/null
@@ -1,14 +0,0 @@
----
-layout: website-normal
-title: Getting Started with the Command Line
-children:
-- running.md
-- blueprints-cli.md
-- managing-cli.md
-- policies-cli.md
-- concept-quickstart.md
----
-
-{% include list-children.html %}
-
-
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/cb76968c/docs/guide/start/managing-cli.md
----------------------------------------------------------------------
diff --git a/docs/guide/start/managing-cli.md b/docs/guide/start/managing-cli.md
deleted file mode 100644
index 94c2a82..0000000
--- a/docs/guide/start/managing-cli.md
+++ /dev/null
@@ -1,347 +0,0 @@
----
-title: Monitoring and Managing Applications
-title_in_menu: Monitoring and Managing Applications
-layout: website-normal
-menu_parent: index-cli.md
-children:
-- { section: Applications }
-- { section: Entities }
-- { section: Sensors }
-- { section: Effectors }
-- { section: Activities }
----
-
-
-
-So far we have touched on Brooklyn's ability to *deploy* an application blueprint to a cloud provider, but this just
-the beginning. The sections below outline how to manage the application that has been deployed.
-
-
-## Scopes in CLI commands
-Many commands require a "scope" expression to indicate the target on which they operate. The scope expressions are
-as follows (values in brackets are aliases for the scope):
- - application APP-ID (app, a)
- Selects an application, e.g. "br app myapp"
- - entity ENT-ID (ent, e)
- Selects an entity within an application scope, e.g. "br app myapp ent myserver"
- - effector EFF-ID (eff, f)
- Selects an effector of an entity or application, e.g. "br a myapp e myserver eff xyz"
- - config CONF-KEY (conf, con, c)
- Selects a configuration key of an entity e.g. "br a myapp e myserver config jmx.agent.mode"
- - activity ACT-ID (act, v)
- Selects an activity of an entity e.g. "br a myapp e myserver act iHG7sq1"
-
-
-## Applications
-
-Having created the application we can query its status. We can find a summary of all deployed apps:
-{% highlight bash %}
-$ br application
- Id Name Status Location
- hTPAF19s Tomcat RUNNING ajVVAhER
-{% endhighlight %}
-
-"application" can be shortened to one of the aliases "app" or just "a", for example:
-{% highlight bash %}
-$ br app
- Id Name Status Location
- hTPAF19s Tomcat RUNNING ajVVAhER
-{% endhighlight %}
-
-You can find the details of a given application, using its name or ID.
-{% highlight bash %}
-$ br app Tomcat
- Id: hTPAF19s
- Name: Tomcat
- Status: RUNNING
- ServiceUp: true
- Type: org.apache.brooklyn.entity.stock.BasicApplication
- CatalogItemId: null
- LocationId: ajVVAhER
- LocationName: FixedListMachineProvisioningLocation:ajVV
- LocationSpec: vagrantbyon
- LocationType: org.apache.brooklyn.location.byon.FixedListMachineProvisioningLocation
-{% endhighlight %}
-
-To ease management of multiple applications, or even to reduce the amount of typing required, it is convenient
-to create an alias for the commonly used application scope:
-{% highlight bash %}
-alias tom="br app Tomcat"
-{% endhighlight %}
-
-To illustrate this we will assume the above alias for the rest of this section, but to avoid confusion
-the examples in other sections will show the full command in all cases.
-
-We can explore the management hierarchy of all applications, which will show us the entities they are composed of.
-{% highlight bash %}
-$ br tree
-|- Tomcat
-+- org.apache.brooklyn.entity.stock.BasicApplication
- |- TomcatServer:Wx7r
- +- org.apache.brooklyn.entity.webapp.tomcat.TomcatServer
-{% endhighlight %}
-
-You can view the blueprint for the application again:
-{% highlight bash %}
-$ tom spec
-"name: Tomcat\nlocation:\n mylocation\nservices:\n- serviceType: brooklyn.entity.webapp.tomcat.TomcatServer\n"
-{% endhighlight %}
-
-You can view the config of the application:
-{% highlight bash %}
-$ tom config
-Key Value
-camp.template.id l67i25CM
-brooklyn.wrapper_app true
-{% endhighlight %}
-
-## Entities
-To explore the entities of the application you can use the "entity" command. This will show the
-immediate child entities of a given application or one of its child entities.
-
-{% highlight bash %}
-$ br app Tomcat entity
-Id Name Type
-Wx7r1C4e TomcatServer:Wx7r org.apache.brooklyn.entity.webapp.tomcat.TomcatServer
-{% endhighlight %}
-
-"entity" has aliases "ent" or "e".
-
-You can get summary information for an entity by providing its name (or ID).
-
-{% highlight bash %}
-$ br app Tomcat ent TomcatServer:Wx7r
-Id: Wx7r1C4e
-Name: TomcatServer:Wx7r
-Status: RUNNING
-ServiceUp: true
-Type: org.apache.brooklyn.entity.webapp.tomcat.TomcatServer
-CatalogItemId: null
-{% endhighlight %}
-
-Also you can see the config of the entity with the "config" command.
-
-{% highlight bash %}
-$ br app Tomcat ent TomcatServer:Wx7r config
-Key Value
-jmx.agent.mode JMXMP_AND_RMI
-brooklyn.wrapper_app true
-camp.template.id yBcQuFZe
-onbox.base.dir /home/vagrant/brooklyn-managed-processes
-onbox.base.dir.resolved true
-install.unique_label TomcatServer_7.0.65
-{% endhighlight %}
-
-If an entity name is annoyingly long to type, the entity can be renamed:
-
-{% highlight bash %}
-$ br app Tomcat ent TomcatServer:Wx7r rename server
-{% endhighlight %}
-
-## Sensors
-
-"Sensors" on entities provide a real-time picture of the status and operation of an entity of the application.
-
-To view the sensors on the application itself, use the command below:
-
-{% highlight bash %}
-$ br app Tomcat sensor
-Name Description Value
-service.isUp Whether the service is active and availability (confirmed and monitored) true
-service.notUp.indicators A map of namespaced indicators that the service is not up {}
-service.problems A map of namespaced indicators of problems with a service {}
-service.state Actual lifecycle state of the service "RUNNING"
-service.state.expected Last controlled change to service state, indicating what the expected state should be "running @ 1450356994928 / Thu Dec 17 12:56:34 GMT 2015"
-{% endhighlight %}
-
-To explore all sensors available on an entity use the sensor command with an entity scope.
-Note, again, the name of the application or entity can be used or the ID:
-
-{% highlight bash %}
-br app Tomcat ent TomcatServer:Wx7r sensor
-Name Description Value
-download.addon.urls URL patterns for downloading named add-ons (will substitute things like ${version} automatically)
-download.url URL pattern for downloading the installer (will substitute things like ${version} automatically) "http://download.nextag.com/apache/tomcat/tomcat-7/v${version}/bin/apache-tomcat-${version}.tar.gz"
-expandedinstall.dir Directory for installed artifacts (e.g. expanded dir after unpacking .tgz) "/home/vagrant/brooklyn-managed-processes/installs/TomcatServer_7.0.65/apache-tomcat-7.0.65"
-host.address Host IP address "10.10.10.101"
-host.name Host name "10.10.10.101"
-host.sshAddress user@host:port for ssh'ing (or null if inappropriate) "vagrant@10.10.10.101:22"
-host.subnet.address Host address as known internally in the subnet where it is running (if different to host.name) "10.10.10.101"
-host.subnet.hostname Host name as known internally in the subnet where it is running (if different to host.name) "10.10.10.101"
-# etc. etc.
-{% endhighlight %}
-
-
-To study selected sensors, give the command the sensor name as an argument
-
-{% highlight bash %}
-$ br app Tomcat ent TomcatServer:Wx7r sensor webapp.url
-"http://10.10.10.101:8080/"
-{% endhighlight %}
-
-
-## Effectors
-
-Effectors are the means by which you can manipulate the entities in an application. For an application you can list them
-with
-
-{% highlight bash %}
-$ br app Tomcat effector
-Name Description Parameters
-restart Restart the process/service represented by an entity
-start Start the process/service represented by an entity locations
-stop Stop the process/service represented by an entity
-{% endhighlight %}
-
-For an entity supply the entity scope:
-
-{% highlight bash %}
-$ br app Tomcat ent TomcatServer:Wx7r effector
-Name Description Parameters
-deploy Deploys the given artifact, from a source URL, to a given deployment filename/context url,targetName
-populateServiceNotUpDiagnostics Populates the attribute service.notUp.diagnostics, with any available health indicators
-restart Restart the process/service represented by an entity restartChildren,restartMachine
-start Start the process/service represented by an entity locations
-stop Stop the process/service represented by an entity stopProcessMode,stopMachineMode
-undeploy Undeploys the given context/artifact targetName
-{% endhighlight %}
-
-To view just one effector's documentation, supply its name to the show command:
-
-{% highlight bash %}
-$ br app Tomcat ent TomcatServer:Wx7r effector deploy
-Name Description Parameters
-deploy Deploys the given artifact, from a source URL, to a given deployment filename/context url,targetName
-{% endhighlight %}
-
-These effectors can be invoked using the command "invoke", supplying the application and entity id of the entity to
-invoke the effector on.
-
-For example, to stop an application, use the "stop" effector. This will cleanly shutdown all components in the
-application and return any cloud machines that were being used. Do the invocation by supplying the effector name in
-the scope, and using the command 'invoke'.
-
-{% highlight bash %}
-$ br app Tomcat ent TomcatServer:Wx7r eff stop invoke
-{% endhighlight %}
-
-Note that the three "lifecycle" related effectors, start, stop, and restart, are common to all software process
-entities in Brooklyn. They are so commonly used that they have their own aliases. The above could also have been done
-by:
-
-{% highlight bash %}
-$ br app Tomcat ent TomcatServer:Wx7r stop
-{% endhighlight %}
-
-Some effectors require parameters for their invocation, as in the example of "deploy" above.
-
-{% highlight bash %}
-br app Tomcat ent TomcatServer:Wx7r effector deploy
-Name Description Parameters
-deploy Deploys the given artifact, from a source URL, to a given deployment filename/context url,targetName
-{% endhighlight %}
-
-Now the effector can be invoked by supplying the parameters using ```--param parm=value``` or just ```-P parm=value```.
-
-In the example below, a sample Tomcat war file is deployed, a variable is created for the root URL using the appropriate
-sensor, and the index page is fetched. Note that at present a "tr" command is required in the second line below to strip
-quotation characters from the returned sensor value.
-
-{% highlight bash %}
-$ br app Tomcat ent TomcatServer:Wx7r effector deploy invoke -P url=https://tomcat.apache.org/tomcat-6.0-doc/appdev/sample/sample.war -P targetName=sample
-$ webapp=$(br app Tomcat ent TomcatServer:Wx7r sensor webapp.url | tr -d '"')
-$ curl $webapp/sample/
-<html>
-<head>
-<title>Sample "Hello, World" Application</title>
-</head>
-# etc. etc.
-{% endhighlight %}
-
-
-## Activities
-
-The 'activity' command allows us to investigate the activities of an entity.
-
-To view a list of all activities associated with an entity simply use
-
-{% highlight bash %}
-$ br app Tomcat ent TomcatServer:Wx7r activity
-Id Task Submitted Status Streams
-LtD5P1cb start Thu Dec 17 15:04:43 GMT 2015 Completed
-l2qo4vTl provisioning (FixedListMachineProvisi... Thu Dec 17 15:04:43 GMT 2015 Completed
-wLD764HE pre-start Thu Dec 17 15:04:43 GMT 2015 Completed
-KLTxDkoa ssh: initializing on-box base dir ./b... Thu Dec 17 15:04:43 GMT 2015 Completed env,stderr,stdin,stdout
-jwwcJWmF start (processes) Thu Dec 17 15:04:43 GMT 2015 Completed
-# etc. etc.
-{% endhighlight %}
-
-To view the details of an individual activity provide its ID:
-
-{% highlight bash %}
-$ br app Tomcat ent TomcatServer:Wx7r activity jwwcJWmF
-Id: jwwcJWmF
-DisplayName: start (processes)
-Description:
-EntityId: efUvVWAw
-EntityDisplayName: TomcatServer:efUv
-Submitted: Thu Dec 17 15:04:43 GMT 2015
-Started: Thu Dec 17 15:04:43 GMT 2015
-Ended: Thu Dec 17 15:08:59 GMT 2015
-CurrentStatus: Completed
-IsError: false
-IsCancelled: false
-SubmittedByTask: LtD5P1cb
-Streams:
-DetailedStatus: "Completed after 4m 16s
-
-No return value (null)"
-{% endhighlight %}
-
-If an activity has failed, the "DetailedStatus" value will show information about the failure, as an aid to diagnosis.
-
-Adding the "--children" or "-c" parameter will show the activity's child activities, to allow the hierarchical structure
-of the activities to be investigated:
-
-{% highlight bash %}
-$ br app Tomcat ent TomcatServer:Wx7r activity -c jwwcJWmF
-Id Task Submitted Status
-UpYRc3fw copy-pre-install-resources Thu Dec 17 15:04:43 GMT 2015 Completed
-ig8sBHQr pre-install Thu Dec 17 15:04:43 GMT 2015 Completed
-Elp4HaVj pre-install-command Thu Dec 17 15:04:43 GMT 2015 Completed
-YOvNobJk setup Thu Dec 17 15:04:43 GMT 2015 Completed
-VN3cDKki copy-install-resources Thu Dec 17 15:08:43 GMT 2015 Completed
-xDJXQC0J install Thu Dec 17 15:08:43 GMT 2015 Completed
-zxMDXUxz post-install-command Thu Dec 17 15:08:58 GMT 2015 Completed
-qnQnw7Oc customize Thu Dec 17 15:08:58 GMT 2015 Completed
-ug044ArS copy-runtime-resources Thu Dec 17 15:08:58 GMT 2015 Completed
-STavcRc8 pre-launch-command Thu Dec 17 15:08:58 GMT 2015 Completed
-HKrYfH6h launch Thu Dec 17 15:08:58 GMT 2015 Completed
-T1m8VXbq post-launch-command Thu Dec 17 15:08:59 GMT 2015 Completed
-n8eK5USE post-launch Thu Dec 17 15:08:59 GMT 2015 Completed
-{% endhighlight %}
-
-If an activity has associated input and output streams, these may be viewed by providing the activity scope and
-using the commands, "env", "stdin", "stdout", and "stderr". For example, for the "initializing on-box base dir"
-activity from the result of the earlier example,
-
-{% highlight bash %}
-$ br app Tomcat ent TomcatServer:Wx7r act KLTxDkoa stdout
-BASE_DIR_RESULT:/home/vagrant/brooklyn-managed-processes:BASE_DIR_RESULT
-
-{% endhighlight %}
-
-
-To monitor progress on an application as it deploys, for example, one could use a shell loop:
-
-{% highlight bash %}
-$ while br app Tomcat ent TomcatServer:Wx7r activity | grep 'In progress' ; do
- sleep 1; echo ; date;
-done
-{% endhighlight %}
-This loop will exit when the application has deployed successfully or has failed. If it fails then the 'stderr'
-command may provide information about what happened in any activities that have associated streams:
-
-{% highlight bash %}
-$ br app Tomcat ent TomcatServer:Wx7r act KLTxDkoa stderr
-{% endhighlight %}
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/cb76968c/docs/guide/start/policies-cli.md
----------------------------------------------------------------------
diff --git a/docs/guide/start/policies-cli.md b/docs/guide/start/policies-cli.md
deleted file mode 100644
index 482c5a0..0000000
--- a/docs/guide/start/policies-cli.md
+++ /dev/null
@@ -1,174 +0,0 @@
----
-title: Getting Started - Policies
-title_in_menu: Policies
-layout: website-normal
-menu-parent: index-cli.md
----
-
-
-
-
-## A Clustered Example
-
-We'll now look at a more complex example that better shows the capabilities of Brooklyn.
-
-We'll start by deploying an application via YAML blueprint consisting of the following layers.
-
-- A dynamically scalable Web App Cluster
-- A MySQL DB
-
-
-Copy the blueprint below into a text file, "mycluster.yaml", in your workspace, but *before* you create an application
-with it, again modify the YAML to specify the location where the application will be deployed.
-You will need at least five machines for this example, one for the DB, and four for the tomcats
-(but you can reduce this by changing the "maxPoolSize" below.
-
-{% highlight yaml %}
-name: cluster
-
-location:
- jclouds:aws-ec2:
- identity: ABCDEFGHIJKLMNOPQRST
- credential: s3cr3tsq1rr3ls3cr3tsq1rr3ls3cr3tsq1rr3l
-
-
-services:
-- serviceType: brooklyn.entity.webapp.ControlledDynamicWebAppCluster
- name: webcluster
- brooklyn.config:
- wars.root: http://search.maven.org/remotecontent?filepath=io/brooklyn/example/brooklyn-example-hello-world-sql-webapp/0.6.0-M2/brooklyn-example-hello-world-sql-webapp-0.6.0-M2.war
- http.port: 9280+
- proxy.http.port: 9210+
- java.sysprops:
- brooklyn.example.db.url: $brooklyn:formatString("jdbc:%s%s?user=%s\\&password=%s",
- component("db").attributeWhenReady("datastore.url"), "visitors", "brooklyn", "br00k11n")
- brooklyn.policies:
- - policyType: brooklyn.policy.autoscaling.AutoScalerPolicy
- brooklyn.config:
- metric: $brooklyn:sensor("brooklyn.entity.webapp.DynamicWebAppCluster", "webapp.reqs.perSec.windowed.perNode")
- metricLowerBound: 10
- metricUpperBound: 100
- minPoolSize: 1
- maxPoolSize: 4
-
-- serviceType: brooklyn.entity.database.mysql.MySqlNode
- id: db
- name: mysql
- brooklyn.config:
- creationScriptUrl: https://bit.ly/brooklyn-visitors-creation-script
-{% endhighlight %}
-
-Explore this app using the 'application' and other commands from the previous section.
-
-## Configuring Dependencies
-The App above illustrates how one component in a blueprint can be configured with information relating to one of the other
-components in the blueprint. In this example the web cluster is configured with a URL for JDBC connections to the database.
-{% highlight yaml %}
-java.sysprops:
- brooklyn.example.db.url: $brooklyn:formatString("jdbc:%s%s?user=%s\\&password=%s",
- component("db").attributeWhenReady("datastore.url"), "visitors", "brooklyn", "br00k11n")
-{% endhighlight %}
-
-the syntax ```$brooklyn:formatString(...)``` is an example of the Brooklyn DSL (Domain Specific Language) which
-allows expressions referring to Brooklyn's management information to be embedded in blueprints. The line above also illustrates the use of Brooklyn's ```component(...)``` and ```attributeWhenReady(...)``` to get an identified component from a deployment, and to wait until the component is fully deployed before reading one of its sensors ("datastore.url" in this case).
-
-## Managing with Policies
-
-
-The app server cluster has an `AutoScalerPolicy`and the loadbalancer has a `Controller targets tracker` policy.
-
-For example
-{% highlight yaml %}
-$ br app cluster ent webcluster policy
-Id Name State
-mMZngBnb org.apache.brooklyn.policy.autoscaling.AutoScalerPolicy RUNNING
-{% endhighlight %}
-
-You can investigate the status of the `AutoScalerPolicy` with
-
-{% highlight yaml %}
-$ br app cluster ent webcluster policy org.apache.brooklyn.policy.autoscaling.AutoScalerPolicy
-"RUNNING"
-{% endhighlight %}
-
-A more detailed description of the parameters of the policy can be obtained with
-{% highlight yaml %}
-$ br app cluster ent webcluster policy org.apache.brooklyn.policy.autoscaling.AutoScalerPolicy
-Name Value Description
-autoscaler.currentSizeOperator org.apache.brooklyn.policy.autoscaling.AutoScalerPolicy$4@9393100
-autoscaler.entityWithMetric The Entity with the metric that will be monitored
-autoscaler.maxPoolSize 4
-autoscaler.maxReachedNotificationDelay 0ms Time that we consistently wanted to go above the maxPoolSize for, after which the maxSizeReachedSensor (if any) will be emitted
-autoscaler.maxSizeReachedSensor Sensor for which a notification will be emitted (on the associated entity) when we consistently wanted to resize the pool above the max allowed size, for maxReachedNotificationDelay milliseconds
-autoscaler.metric Sensor: webapp.reqs.perSec.windowed.perNode (java.lang.Double)
-autoscaler.metricLowerBound 10 The lower bound of the monitored metric. Below this the policy will resize down
-autoscaler.metricUpperBound 100 The upper bound of the monitored metric. Above this the policy will resize up
-autoscaler.minPeriodBetweenExecs 100ms
-autoscaler.minPoolSize 1
-autoscaler.poolColdSensor Sensor: resizablepool.cold (java.util.Map)
-autoscaler.poolHotSensor Sensor: resizablepool.hot (java.util.Map)
-autoscaler.poolOkSensor Sensor: resizablepool.cold (java.util.Map)
-autoscaler.resizeDownIterationIncrement 1 Batch size for resizing down; the size will be decreased by a multiple of this value
-autoscaler.resizeDownIterationMax 2147483647 Maximum change to the size on a single iteration when scaling down
-autoscaler.resizeDownStabilizationDelay 0ms
-autoscaler.resizeOperator org.apache.brooklyn.policy.autoscaling.AutoScalerPolicy$3@387a7e10
-autoscaler.resizeUpIterationIncrement 1 Batch size for resizing up; the size will be increased by a multiple of this value
-autoscaler.resizeUpIterationMax 2147483647 Maximum change to the size on a single iteration when scaling up
-autoscaler.resizeUpStabilizationDelay 0ms
-{% endhighlight %}
-
-
-The loadbalancer's `Controller targets tracker` policy ensures that the loadbalancer is updated as the cluster size changes.
-
-This policy automatically scales the cluster up or down to be the right size for the cluster's current load. One server
-is the minimum size allowed by the policy.
-
-Sitting idle, this cluster will only contain one server, but you can use a tool like [jmeter](http://jmeter.apache.org/)
-pointed at the nginx endpoint to create load on the cluster. Download a jmeter test
-plan [here](https://github.com/apache/incubator-brooklyn/blob/master/examples/simple-web-cluster/resources/jmeter-test-plan.jmx).
-
-As load is added, Apache Brooklyn requests a new cloud machine, creates a new app server, and adds it to the cluster.
-As load is removed, servers are removed from the cluster, and the infrastructure is handed back to the cloud.
-
-
-## Under the Covers
-
-The `AutoScalerPolicy` here is configured to respond to the sensor
-reporting requests per second per node, invoking the default `resize` effector.
-By updating on the policy, you can configure it to respond to a much lower threshhold
-or set long stabilization delays (the period before it scales out or back).
-
-At present the CLI does not support a command to update a policy.
-
-However it is possible to manually suspend the policy, by
-
-{% highlight bash %}
-$ br app cluster ent webcluster stop-policy org.apache.brooklyn.policy.autoscaling.AutoScalerPolicy
-
-{% endhighlight %}
-
-You can then invoke a `resize` using the appropriate effector:
-{% highlight bash %}
-$ br app cluster ent webcluster effector resize invoke -P desiredSize=3
-{% endhighlight %}
-
-On resize, new nodes are created and configured,
-and in this case a policy on the nginx node reconfigures nginx whenever the set of active
-targets changes.
-
-The policy can then be re-enabled with start-policy:
-
-{% highlight bash %}
-$ br app cluster ent webcluster start-policy org.apache.brooklyn.policy.autoscaling.AutoScalerPolicy
-
-{% endhighlight %}
-
-
-## Next
-
-This guide has given a quick overview to writing blueprints for applications, deploying applications, and
-managing them. Next, learn more about any of:
-
-* [Writing Blueprints with YAML](../yaml/)
-* [Writing Blueprints with Java](../java/)
-* [Operating Brooklyn](../ops/)
\ No newline at end of file