You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@brooklyn.apache.org by he...@apache.org on 2016/01/30 04:38:30 UTC
[05/29] incubator-brooklyn git commit: Updated blueprints and managing
Updated blueprints and managing
Project: http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/repo
Commit: http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/commit/bb5f8e14
Tree: http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/tree/bb5f8e14
Diff: http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/diff/bb5f8e14
Branch: refs/heads/master
Commit: bb5f8e14094f921176f8bb2ae85666755a907dae
Parents: 3085324
Author: Duncan Godwin <du...@cloudsoftcorp.com>
Authored: Tue Jan 19 15:25:12 2016 +0000
Committer: Duncan Godwin <du...@cloudsoftcorp.com>
Committed: Tue Jan 19 15:25:12 2016 +0000
----------------------------------------------------------------------
brooklyn-docs/guide/start/blueprints.md | 10 +-
brooklyn-docs/guide/start/managing.md | 134 +++++++++++++++++----------
brooklyn-docs/guide/start/running.md | 2 +-
3 files changed, 91 insertions(+), 55 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/bb5f8e14/brooklyn-docs/guide/start/blueprints.md
----------------------------------------------------------------------
diff --git a/brooklyn-docs/guide/start/blueprints.md b/brooklyn-docs/guide/start/blueprints.md
index 0c52de9..4f271cc 100644
--- a/brooklyn-docs/guide/start/blueprints.md
+++ b/brooklyn-docs/guide/start/blueprints.md
@@ -6,7 +6,7 @@ children:
- { section: Launching from a Blueprint, title: Blueprint }
---
-Blueprints are descriptors or patterns which describe how Apache Brooklyn should deploy applications. Blueprints are written in [YAML](https://en.wikipedia.org/wiki/YAML){:target="_blank"} and all of the entities available are defined in the __[Brooklyn Catalog](../../learnmore/catalog/)__.
+Blueprints are descriptors or patterns which describe how Apache Brooklyn should deploy applications. Blueprints are written in [YAML](https://en.wikipedia.org/wiki/YAML){:target="_blank"} and all of the entities available are defined in the __[Brooklyn Catalog](../../website/learnmore/catalog/)__.
## Launching from a Blueprint
@@ -17,9 +17,9 @@ hover your mouse over the right side of the text box below to get a Javascript "
{% highlight yaml %}
name: Tomcat
-location:
services:
-- serviceType: brooklyn.entity.webapp.tomcat.TomcatServer
+- type: org.apache.brooklyn.entity.webapp.tomcat.TomcatServer
+location: <your-location-definition-goes-here>
{% endhighlight %}
@@ -48,7 +48,7 @@ These can be launched by entering the following command into the terminal in the
$ vagrant up byon1 byon2 byon3 byon4
{% endhighlight %}
-The location in "myapp.yaml" can then be replaced with the following YAML to launch using these.
+The location in "myapp.yaml" can now be replaced with the following YAML to launch using these vagrant servers.
{% highlight yaml %}
location:
@@ -110,7 +110,7 @@ $ br login http://localhost:8081/
{% endhighlight %}
To secure the Apache Brooklyn instance, you can add a username and password to Brooklyn's properties file, as described in the User Guide [here](../ops/brooklyn_properties.html){:target="_blank"}.
-If this is configured, the login command will then require additional parameters for the userid and password.
+If this is configured, the login command will require an additional parameter for the userid and will then prompt for a password.
Now you can create the application with the command below:
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/bb5f8e14/brooklyn-docs/guide/start/managing.md
----------------------------------------------------------------------
diff --git a/brooklyn-docs/guide/start/managing.md b/brooklyn-docs/guide/start/managing.md
index 63742f9..cffd3a1 100644
--- a/brooklyn-docs/guide/start/managing.md
+++ b/brooklyn-docs/guide/start/managing.md
@@ -13,28 +13,40 @@ children:
-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.
+So far we have gone through Apache Brooklyn's ability to *deploy* an application blueprint to a location, but this just
+the beginning. Next we will outline how to *manage* the application that has been deployed.
## Applications
-Having created the application we can query its status. We can find a summary of all deployed apps:
+Having created the application, we can find a summary of all deployed applications using:
{% highlight bash %}
-$ br application
- Id Name Status Location
- hTPAF19s Tomcat RUNNING ajVVAhER
+$ br application
{% endhighlight %}
-```application``` can be shortened to one of the aliases ```app``` or just ```a```, for example:
-{% highlight bash %}
-$ br app
+<pre>
Id Name Status Location
- hTPAF19s Tomcat RUNNING ajVVAhER
+ hTPAF19s Tomcat RUNNING ajVVAhER
+</pre>
+
+```application``` can be shortened to the alias ```app```, for example:
+{% highlight bash %}
+$ br app
{% endhighlight %}
+<pre>
+ Id Name Status Location
+ hTPAF19s Tomcat RUNNING ajVVAhER
+</pre>
+
+A full list of abbreviations such as this can be found in the [CLI reference guide](../ops/cli/cli-ref-guide.html#abbreviations){:target="_blank"}.
+
+In the above example the Id `hTPAF19s` and the Name `Tomcat` are shown. You can use either of these handles to monitor and control the application. The Id shown for your application will be different to this but the name should be the same, note that if you are running multiple applications the Name may not be unique.
+
+Using the name `Tomcat` we can get the application details:
-You can find the details of a given application, using its name or ID.
{% highlight bash %}
$ br app Tomcat
+{% endhighlight %}
+<pre>
Id: hTPAF19s
Name: Tomcat
Status: RUNNING
@@ -45,68 +57,71 @@ $ br app Tomcat
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.
+</pre>
We can explore the management hierarchy of all applications, which will show us the entities they are composed of.
{% highlight bash %}
$ br tree
+{% endhighlight %}
+<pre>
|- Tomcat
+- org.apache.brooklyn.entity.stock.BasicApplication
|- TomcatServer:Wx7r
+- org.apache.brooklyn.entity.webapp.tomcat.TomcatServer
-{% endhighlight %}
+</pre>
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"
+$ br app tomcat spec
{% endhighlight %}
+<pre>
+"name: Tomcat\nlocation:\n mylocation\nservices:\n- serviceType: brooklyn.entity.webapp.tomcat.TomcatServer\n"
+</pre>
You can view the config of the application:
{% highlight bash %}
-$ tom config
+$ br app tomcat config
+{% endhighlight %}
+<pre>
Key Value
camp.template.id l67i25CM
brooklyn.wrapper_app true
-{% endhighlight %}
+</pre>
## 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.
+
+An *Entity* is Apache Brooklyn's representation of a software package or service which it can control or interact with. All of the entities Apache Brooklyn can use are listed in the __[Brooklyn Catalog](../../website/learnmore/catalog/)__.
+
+To list the entities of the application you can use the `entity` or `ent` command:
{% highlight bash %}
$ br app Tomcat entity
+{% endhighlight %}
+<pre>
Id Name Type
Wx7r1C4e TomcatServer:Wx7r org.apache.brooklyn.entity.webapp.tomcat.TomcatServer
-{% endhighlight %}
-
-```entity``` has aliases ```ent``` or ```e```.
+</pre>
You can get summary information for an entity by providing its name (or ID).
{% highlight bash %}
$ br app Tomcat ent TomcatServer:Wx7r
+{% endhighlight %}
+<pre>
Id: Wx7r1C4e
Name: TomcatServer:Wx7r
Status: RUNNING
ServiceUp: true
Type: org.apache.brooklyn.entity.webapp.tomcat.TomcatServer
CatalogItemId: null
-{% endhighlight %}
+</pre>
Also you can see the config of the entity with the ```config``` command.
{% highlight bash %}
$ br app Tomcat ent TomcatServer:Wx7r config
+{% endhighlight %}
+<pre>
Key Value
jmx.agent.mode JMXMP_AND_RMI
brooklyn.wrapper_app true
@@ -114,7 +129,7 @@ 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 %}
+</pre>
If an entity name is annoyingly long to type, the entity can be renamed:
@@ -124,25 +139,29 @@ $ br app Tomcat ent TomcatServer:Wx7r rename server
## Sensors
-"Sensors" on entities provide a real-time picture of the status and operation of an entity of the application.
+*Sensors* are properties which reflect the state of an *entity* and provide a real-time picture of an *entity* in an application.
To view the sensors on the application itself, use the command below:
{% highlight bash %}
$ br app Tomcat sensor
+{% endhighlight %}
+<pre>
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 %}
+</pre>
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
+$ br app Tomcat ent TomcatServer:Wx7r sensor
+{% endhighlight %}
+<pre>
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"
@@ -153,15 +172,17 @@ host.sshAddress user@host:port for ssh'ing (or n
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 %}
+</pre>
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/"
+$ br app Tomcat ent TomcatServer:Wx7r sensor webapp.url
{% endhighlight %}
+<pre>
+"http://10.10.10.101:8080/"
+</pre>
## Effectors
@@ -171,16 +192,20 @@ with
{% highlight bash %}
$ br app Tomcat effector
+{% endhighlight %}
+<pre>
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 %}
+</pre>
For an entity supply the entity scope:
{% highlight bash %}
$ br app Tomcat ent TomcatServer:Wx7r effector
+{% endhighlight %}
+<pre>
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
@@ -188,15 +213,17 @@ restart Restart the process/service represented by an
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 %}
+</pre>
To view just one effector's documentation, supply its name to the show command:
{% highlight bash %}
$ br app Tomcat ent TomcatServer:Wx7r effector deploy
+{% endhighlight %}
+<pre>
Name Description Parameters
deploy Deploys the given artifact, from a source URL, to a given deployment filename/context url,targetName
-{% endhighlight %}
+</pre>
These effectors can be invoked using the command ```invoke```, supplying the application and entity id of the entity to
invoke the effector on.
@@ -220,10 +247,12 @@ $ br app Tomcat ent TomcatServer:Wx7r stop
Some effectors require parameters for their invocation, as in the example of ```deploy``` above.
{% highlight bash %}
-br app Tomcat ent TomcatServer:Wx7r effector deploy
+$ br app Tomcat ent TomcatServer:Wx7r effector deploy
+{% endhighlight %}
+<pre>
Name Description Parameters
deploy Deploys the given artifact, from a source URL, to a given deployment filename/context url,targetName
-{% endhighlight %}
+</pre>
Now the effector can be invoked by supplying the parameters using ```--param parm=value``` or just ```-P parm=value```.
@@ -235,12 +264,14 @@ quotation characters from the returned sensor value.
$ 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/
+{% endhighlight %}
+<pre>
<html>
<head>
<title>Sample "Hello, World" Application</title>
</head>
# etc. etc.
-{% endhighlight %}
+</pre>
## Activities
@@ -251,6 +282,8 @@ To view a list of all activities associated with an entity simply use
{% highlight bash %}
$ br app Tomcat ent TomcatServer:Wx7r activity
+{% endhighlight %}
+<pre>
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
@@ -258,12 +291,14 @@ wLD764HE pre-start Thu Dec 17 15:04:43 GMT 20
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 %}
+</pre>
To view the details of an individual activity provide its ID:
{% highlight bash %}
$ br app Tomcat ent TomcatServer:Wx7r activity jwwcJWmF
+{% endhighlight %}
+<pre>
Id: jwwcJWmF
DisplayName: start (processes)
Description:
@@ -280,7 +315,7 @@ Streams:
DetailedStatus: "Completed after 4m 16s
No return value (null)"
-{% endhighlight %}
+</pre>
If an activity has failed, the "DetailedStatus" value will show information about the failure, as an aid to diagnosis.
@@ -289,6 +324,8 @@ of the activities to be investigated:
{% highlight bash %}
$ br app Tomcat ent TomcatServer:Wx7r activity -c jwwcJWmF
+{% endhighlight %}
+<pre>
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
@@ -303,7 +340,7 @@ 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 %}
+</pre>
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"
@@ -312,7 +349,6 @@ 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 %}
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/bb5f8e14/brooklyn-docs/guide/start/running.md
----------------------------------------------------------------------
diff --git a/brooklyn-docs/guide/start/running.md b/brooklyn-docs/guide/start/running.md
index 74dc687..5da792c 100644
--- a/brooklyn-docs/guide/start/running.md
+++ b/brooklyn-docs/guide/start/running.md
@@ -97,7 +97,7 @@ $ vagrant up brooklyn
You can see if Apache Brooklyn launched OK by viewing the log files with the command
{% highlight bash %}
-$ ssh brooklyn --command 'sudo journalctl -n15 -f -u brooklyn'
+$ vagrant ssh brooklyn --command 'sudo journalctl -n15 -f -u brooklyn'
{% endhighlight %}
</div>