misc fixes to documentation
Project: http://git-wip-us.apache.org/repos/asf/brooklyn-docs/repo Commit: http://git-wip-us.apache.org/repos/asf/brooklyn-docs/commit/f0fe5688 Tree: http://git-wip-us.apache.org/repos/asf/brooklyn-docs/tree/f0fe5688 Diff: http://git-wip-us.apache.org/repos/asf/brooklyn-docs/diff/f0fe5688 Branch: refs/heads/0.6.0 Commit: f0fe5688f3f54e8f81b24647a765e5a0314ea36d Parents: 7416d00 Author: Alex Heneveld <[email protected]> Authored: Thu Sep 19 21:55:10 2013 +0100 Committer: Alex Heneveld <[email protected]> Committed: Thu Sep 19 21:55:10 2013 +0100 ---------------------------------------------------------------------- .../guide/defining-applications/common-usage.md | 64 +++++++------- docs/use/guide/quickstart/index.md | 87 ++++++++++++++------ 2 files changed, 93 insertions(+), 58 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/f0fe5688/docs/use/guide/defining-applications/common-usage.md ---------------------------------------------------------------------- diff --git a/docs/use/guide/defining-applications/common-usage.md b/docs/use/guide/defining-applications/common-usage.md index b45a2b4..8da4973 100644 --- a/docs/use/guide/defining-applications/common-usage.md +++ b/docs/use/guide/defining-applications/common-usage.md @@ -41,7 +41,7 @@ These include: - **PaaS**: Cloud Foundry, Stackato; OpenShift -### Off-the-Shelf Locations +### <a id="locations"></a> Off-the-Shelf Locations Brooklyn supports deploying to any machine which admits SSH access, as well as to a huge variety of external and on-premise clouds. You can also connect to services, @@ -49,23 +49,23 @@ or use whatever technique for deployment suits you best (such as Xebia Overthere Configuration is typically set in `~/.brooklyn/brooklyn.properties` using keys such as the following: -{% highlight java %} - # use this key for localhost (this is the default, although if you have a passphrase you must set it) - brooklyn.location.localhost.privateKeyFile=~/.ssh/id_rsa - - brooklyn.location.localhost.privateKeyPassphrase=s3cr3tPASSPHRASE - - # use a special key when connecting to public clouds, and a particularly special one for AWS - brooklyn.location.jclouds.privateKeyFile=~/.ssh/public_clouds/id_rsa - brooklyn.location.jclouds.aws-ec2.privateKeyFile=~/.ssh/public_clouds/aws_id_rsa - - # AWS credentials (when deploying to location jclouds:aws-ec2) - brooklyn.location.jclouds.aws-ec2.identity=ABCDEFGHIJKLMNOPQRST - brooklyn.location.jclouds.aws-ec2.credential=s3cr3tsq1rr3ls3cr3tsq1rr3ls3cr3tsq1rr3l - - # credentials for 'geoscaling' service - brooklyn.geoscaling.username=cloudsoft - brooklyn.geoscaling.password=xxx +{% highlight bash %} +# use this key for localhost (this is the default, although if you have a passphrase you must set it) +brooklyn.location.localhost.privateKeyFile=~/.ssh/id_rsa + +brooklyn.location.localhost.privateKeyPassphrase=s3cr3tPASSPHRASE + +# use a special key when connecting to public clouds, and a particularly special one for AWS +brooklyn.location.jclouds.privateKeyFile=~/.ssh/public_clouds/id_rsa +brooklyn.location.jclouds.aws-ec2.privateKeyFile=~/.ssh/public_clouds/aws_id_rsa + +# AWS credentials (when deploying to location jclouds:aws-ec2) +brooklyn.location.jclouds.aws-ec2.identity=ABCDEFGHIJKLMNOPQRST +brooklyn.location.jclouds.aws-ec2.credential=s3cr3tsq1rr3ls3cr3tsq1rr3ls3cr3tsq1rr3l + +# credentials for 'geoscaling' service +brooklyn.geoscaling.username=cloudsoft +brooklyn.geoscaling.password=xxx {% endhighlight %} These can also be set as environment variables (in the shell) or system properties (java command line). @@ -119,19 +119,19 @@ These can be accessed at runtime using the syntax ``named:your-group-name`` as t Some more advanced examples showing the syntax and properties above are as follows: -{% highlight java %} - # Production pool of machines for my application (deploy to named:prod1) - brooklyn.location.named.prod1=byon:(hosts="10.9.1.1,10.9.1.2,[email protected].{10,11,20-29}") - brooklyn.location.named.prod1.user=produser1 - brooklyn.location.named.prod1.privateKeyFile=~/.ssh/produser_id_rsa - brooklyn.location.named.prod1.privateKeyPassphrase=s3cr3tCOMPANYpassphrase - - # AWS using my company's credentials and image standard, then labelling images so others know they're mine - brooklyn.location.named.company-jungle=jclouds:aws-ec2:us-west-1 - brooklyn.location.named.company-jungle.identity=BCDEFGHIJKLMNOPQRSTU - brooklyn.location.named.company-jungle.privateKeyFile=~/.ssh/public_clouds/company_aws_id_rsa - brooklyn.location.named.company-jungle.imageId=ami-12345 - brooklyn.location.named.company-jungle.minRam=2048 - brooklyn.location.named.company-jungle.userMetadata=application=my-jungle-app,owner="Bob Johnson" +{% highlight bash %} +# Production pool of machines for my application (deploy to named:prod1) +brooklyn.location.named.prod1=byon:(hosts="10.9.1.1,10.9.1.2,[email protected].{10,11,20-29}") +brooklyn.location.named.prod1.user=produser1 +brooklyn.location.named.prod1.privateKeyFile=~/.ssh/produser_id_rsa +brooklyn.location.named.prod1.privateKeyPassphrase=s3cr3tCOMPANYpassphrase + +# AWS using my company's credentials and image standard, then labelling images so others know they're mine +brooklyn.location.named.company-jungle=jclouds:aws-ec2:us-west-1 +brooklyn.location.named.company-jungle.identity=BCDEFGHIJKLMNOPQRSTU +brooklyn.location.named.company-jungle.privateKeyFile=~/.ssh/public_clouds/company_aws_id_rsa +brooklyn.location.named.company-jungle.imageId=ami-12345 +brooklyn.location.named.company-jungle.minRam=2048 +brooklyn.location.named.company-jungle.userMetadata=application=my-jungle-app,owner="Bob Johnson" {% endhighlight %} http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/f0fe5688/docs/use/guide/quickstart/index.md ---------------------------------------------------------------------- diff --git a/docs/use/guide/quickstart/index.md b/docs/use/guide/quickstart/index.md index 7ab74cc..67dd091 100644 --- a/docs/use/guide/quickstart/index.md +++ b/docs/use/guide/quickstart/index.md @@ -9,9 +9,11 @@ categories: [use, guide] This guide will get you up and running with Brooklyn quickly. You will become familiar with launching Brooklyn from the command line, using the web interface and deploying an application (to a public cloud). + ### Before We Start You are going to need some basic tools (that are normally installed by default). You will need `curl`, `wget`, `tar`, `ssh` and `ssh-keygen`. + ### Download Brooklyn Download the Brooklyn distribution. This contains Brooklyn, ready to run. @@ -21,24 +23,33 @@ Save the [Distro tgz]({{ this_dist_url_tgz }}) file to your home directory `~/`, Expand the `tar.gz` archive. {% if site.brooklyn-version contains 'SNAPSHOT' %}Each Distro is timestamped, so your filename will be different.{% endif %} {% if site.brooklyn-version contains 'SNAPSHOT' %} - $ tar -zxf brooklyn-dist-{{ site.version }}-timestamp-dist.tar.gz +{% highlight bash %} +$ tar -zxf brooklyn-dist-{{ site.version }}-timestamp-dist.tar.gz +{% endhighlight %} {% else %} - $ tar -zxf brooklyn-dist-{{ site.version }}-dist.tar.gz +{% highlight bash %} +$ tar -zxf brooklyn-dist-{{ site.version }}-dist.tar.gz +{% endhighlight %} {% endif %} This will create a `brooklyn-{{ site.version }}` folder. Let's setup some paths for easy commands. - $ cd brooklyn-{{ site.version }} - $ BROOKLYN_HOME=$(pwd) - $ export PATH=$PATH:$BROOKLYN_HOME/bin/ +{% highlight bash %} +$ cd brooklyn-{{ site.version }} +$ BROOKLYN_HOME=$(pwd) +$ export PATH=$PATH:$BROOKLYN_HOME/bin/ +{% endhighlight %} + ### A Quick Test Drive Running Brooklyn now will launch the web interface, but there will be little to do, as we haven't configured any deployment locations or added a service catalog. Check your progress by running: - $ brooklyn launch +{% highlight bash %} +$ brooklyn launch +{% endhighlight %} Brooklyn will output the address of the management interface: @@ -46,49 +57,62 @@ Brooklyn will output the address of the management interface: Stop Brooklyn with ctrl-c. + ### Setting up Locations and Applications By default Brooklyn loads configuration parameters from `~/.brooklyn/brooklyn.properties` and a service catalog from `~/.brooklyn/catalog.xml`. -Create a .brooklyn folder: - $ mkdir ~/.brooklyn +Create a `.brooklyn` folder in your home directory: -Then download the following default/template files. +{% highlight bash %} +$ mkdir ~/.brooklyn +{% endhighlight %} -### brooklyn.properties -Download the template [brooklyn.properties](brooklyn.properties) (to `~/.brooklyn`). -brooklyn.properties is a standard java .properties file. +Next, set up the following default/template files in that directory: -Edit this file (in any text editor) to add credentials for your favorite cloud. +* **`brooklyn.properties`**: Download the template [brooklyn.properties](brooklyn.properties) + and place this in `~/.brooklyn`. This is a standard java `.properties` file, + which you can edit in your favourite text editor to add credentials for your favorite clouds. -### catalog.xml -Download the template [catalog.xml](catalog.xml) (to `~/.brooklyn`). +* **`catalog.xml`**: Download the template [catalog.xml](catalog.xml) (also to`~/.brooklyn`). + This is a catalog of application blueprints. The example file contains some blueprints which will + be automatically downloaded from the web if you run them. + You may need to edit this file (text editor) to ensure that the links to the demo application `.jar` files + are correct for your version of Brooklyn. -catalog.xml is catalog of application or service blueprints. The example file contains two demos which will be automatically downloaded from the web if you run them. -Edit this file (text editor) and check that the links to the demo applications' .jars are valid. At the time of writing these were for version `0.5.0-SNAPSHOT`, but if this has changed you may need to update the links. <!-- BROOKLYN VERSION --> +Finally, if you do not already have SSH keys installed (in `~/.ssh`, either `id_rsa` and `id_rsa.pub` or the +same for `id_dsa`), you will need to create keys for Brooklyn to use. +If you're deploying to localhost, these should be added to your `authorized_keys` file. -### SSH Key -If this is a new machine, or you haven't used SSH before, you will need to create keys for Brooklyn to use, and add them your list of authorized_keys (for deployment to localhost). +{% highlight bash %} +$ ssh-keygen -t rsa -N "" -f ~/.ssh/id_rsa +$ cat ~/.ssh/id_rsa.pub >> ~/.ssh/authorized_keys +{% endhighlight %} - $ ssh-keygen -t rsa -N "" -f ~/.ssh/id_rsa - $ cat ~/.ssh/id_rsa.pub >> ~/.ssh/authorized_keys +(*Existing SSH keys?*: If you are using an existing key SSH that has a passphrase, +or is not located at `~/.ssh/id_rsa`, you can point Brooklyn at these by setting +`brooklyn.location.localhost.privateKeyFile` and `brooklyn.location.localhost.privateKeyPassphrase` +in your `brooklyn.properties` file.) -(Existing SSH keys?: If you are using an existing key SSH that has a password, or is not located at `~/.ssh/id_rsa`, please supply the `brooklyn.location.localhost.privateKeyFile` and `brooklyn.location.localhost.privateKeyPassphrase` in your `brooklyn.properties` file.) +(*MacOSx user?*: To allow SSH access to localhost please enable 'Remote Login' in System Preferences > Sharing.) -(MacOSx user?: To allow SSH access to localhost please enable 'Remote Login' in System Preferences > Sharing.) ### 3-2-1 Go! Now when we launch Brooklyn: - $ brooklyn launch +{% highlight bash %} +$ brooklyn launch +{% endhighlight %} -Brooklyn will use the `brooklyn.properties` and `catalog.xml` files. There will be more locations available in the management interface at [localhost:8081](http://localhost:8081), and the blueprints from the service catalog will be available for deployment. +Brooklyn will use the `brooklyn.properties` and `catalog.xml` files. +The new locations will be available in the management interface at [localhost:8081](http://localhost:8081), +and the blueprints from the service catalog will be available for deployment. -Click "add application". The Create Application dialog will appear. +Start opening the "Create Application" dialog. (This may open automatically, but if it does not, click "Add Application".) Select the "Demo Web Cluster with DB", then "Next". @@ -98,6 +122,7 @@ You will see Brooklyn create an Application with status "STARTING". It make take some time for Brooklyn to download everything and configure the application's initial topography, so lets have a look at the web interface while we wait. + ### Exploring the Hierarchy of Web Cluster with DB Clicking on an application listed on the home page, or the Applications tab, will show you the management hierarchy. @@ -108,6 +133,7 @@ Clicking on the `ControlledDynamicWebAppCluster` and then the Sensor tab will sh If the `service.isUp`, you can view the demo web application in your browser at the `webapp.url.` + ### Testing the Policies Brooklyn at its heart is a policy driven management plane. After codifying your technical and business policies, Brooklyn can implement them automatically. @@ -123,7 +149,9 @@ Sitting idle, your cluster will only contain one server, but you can check that Brooklyn's policies are configurable, customizable, and can be completely bespoke to your needs. As an example, the `AutoScalerPolicy` is tunable, can be applied to any relevant metric (here, average requests per second), and is a sufficiently complex piece of math that it understand hysteresis and prevents thrashing. + ### REST API Browser + Click on the Script tab at the top of the web interface and select REST API. Brooklyn supports a REST, JSON and Java API to allow you to integrate it with (pretty much) anything. The Script tab allows you to explore the API. @@ -132,12 +160,16 @@ Try: Locations > GET:/v1/locations > Try it out! You will be presented with a json response of the currently configured locations. + ### Stopping the Web Cluster with DB + By now the Web Cluster with DB should have started, and you will have been able to view the application in your browser. Returning to the "Applications" tab, and selecting the `WebClusterDatabaseExample`'s Effectors, we can Invoke the Stop Effector. This will cleanly shutdown the Web Cluster with DB example. + ### Deploying to Cloud + The user experience of using the service catalog to deploy an application to a cloud is exactly the same as deploying to localhost. Brooklyn transparently handles the differences between locations and environments. Return to the Create Application dialog, reselect the Web Cluster with DB Demo, and select your public cloud of choice. @@ -146,13 +178,16 @@ Return to the Create Application dialog, reselect the Web Cluster with DB Demo, Remember to invoke the stop method when you are finished. + ### Closing Thoughts + This guide has shown two aspects of Brooklyn in action: policy driven management capability, and the service catalog/web interface. Additionally, we briefly explored Brooklyn's API. It is worth noting that Brooklyn could be included as a library in your own applications (no command line required), or it could be used just as a management plane (without a service catalog). During this guide we have been using Brooklyn's web interface, but Brooklyn's APIs are extensive and powerful. Brooklyn can be used with (controlled by and make data available to) your existing management UI. Brooklyn is intended to complement (not replace) your existing technologies and tooling. + ### Next The [Elastic Web Cluster Example]({{site.url}}/use/examples/webcluster/index.html) page details how to build the demo application from scratch. It shows how Brooklyn can complement your application with policy driven management, and how an application can be run without using the service catalog.
