Move to docs for 0.7.0. Includes YAML GS and new Location section. - GS split to 1) Download and Deploy, 2) Catalog and Polices - brooklyn.properties small tidies - many screenshots added - YAML sample moved to include file - Deprecated help file contents removed.
Project: http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/repo Commit: http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/commit/bd0e1e07 Tree: http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/tree/bd0e1e07 Diff: http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/diff/bd0e1e07 Branch: refs/pull/1407/head Commit: bd0e1e077e04726f4119fc0fa65e3bb3b5cf58a4 Parents: f54024f Author: David Toy <d...@vidtoy.co.uk> Authored: Mon Apr 14 21:24:08 2014 +0100 Committer: David Toy <d...@vidtoy.co.uk> Committed: Thu May 22 11:21:06 2014 +0100 ---------------------------------------------------------------------- docs/_scripts/help.txt | 81 +----------- docs/use/guide/locations/index.md | 35 +++-- docs/use/guide/quickstart/brooklyn.properties | 72 +++++----- ...cation-catalog-web-cluster-with-db-large.png | Bin 0 -> 131618 bytes ...talog-web-cluster-with-db-location-large.png | Bin 0 -> 152721 bytes ...ion-catalog-web-cluster-with-db-location.png | Bin 0 -> 86425 bytes ...-application-catalog-web-cluster-with-db.png | Bin 0 -> 76065 bytes .../images/add-application-modal-yaml.png | Bin 0 -> 68401 bytes .../images/jboss7-cluster-policies-large.png | Bin 0 -> 157883 bytes .../images/jboss7-cluster-policies.png | Bin 0 -> 94056 bytes .../images/my-db-activities-large.png | Bin 0 -> 208313 bytes .../quickstart/images/my-db-activities.png | Bin 0 -> 130262 bytes .../images/my-web-cluster-starting.png | Bin 0 -> 32948 bytes .../my-web-cluster-stop-confirm-large.png | Bin 0 -> 148155 bytes .../images/my-web-cluster-stop-confirm.png | Bin 0 -> 79280 bytes .../quickstart/images/my-web-summary-large.png | Bin 0 -> 178785 bytes .../guide/quickstart/images/my-web-summary.png | Bin 0 -> 80583 bytes docs/use/guide/quickstart/images/my-web.png | Bin 0 -> 83081 bytes docs/use/guide/quickstart/index.md | 130 ++++++++++--------- docs/use/guide/quickstart/my-web-cluster.yaml | 19 +++ .../guide/quickstart/policies-and-catalogs.md | 66 ++++++++++ docs/use/guide/quickstart/toc.json | 4 + docs/use/guide/toc.json | 5 +- 23 files changed, 224 insertions(+), 188 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/bd0e1e07/docs/_scripts/help.txt ---------------------------------------------------------------------- diff --git a/docs/_scripts/help.txt b/docs/_scripts/help.txt index f6e4ae5..0a41a7b 100644 --- a/docs/_scripts/help.txt +++ b/docs/_scripts/help.txt @@ -9,81 +9,8 @@ _scripts/build.sh will build the site in _site including javadoc for offline browsing +Release Process +=============== -############################################################################### -# Deprecation Warning # -# # -# The following content has been superseded, and will be removed shortly # -# Please view /dev/tips/release.md or see: # -# http://brooklyncentral.github.io/v/0.6.0-SNAPSHOT/dev/tips/release.html # -# # -############################################################################### - - -GO LIVE (SNAPSHOT) ------------------- - -to make the docs live you build.sh then push _site to github brooklyncentral/brooklyncentral.github.com -the following instructions cover this, assuming brooklyncentral.github.com is a sibling dir to the brooklyn project, -and you are in the docs dir - - -updating a snapshot version, in /v/VERSION/ on the server: - -export TARGET=`pwd -P`/../../brooklyncentral.github.com -export BV=0.7.0-SNAPSHOT # BROOKLYN_VERSION - -# make sure repo is at latest -pushd $TARGET -git pull -popd - -# build, copy -if [ ! -f $TARGET/index.html ] ; then echo "could not find docs in $TARGET" ; exit 1 ; fi -_scripts/build.sh || { echo "failed to build docs" ; exit 1 ; } -rm -rf $TARGET/v/$BV -mkdir $TARGET/v/$BV -cp -r _site/* $TARGET/v/$BV/ - -# and push -pushd $TARGET -git add -A . -git commit -m "updated version docs for version $BV" -git push -popd - - -RELEASE -------- - -when we do a RELEASE we must run the above for e.g. BV=0.4.0 -AND must update the files in the root dir of brooklyncentral.github.com - -the commands below do this (basically like the process above but -with / in place of /v/$BV and overriding url in _config.yml -with the --url arg below): - - -# remove old root files -pushd $TARGET -if [ -f start/index.html ] ; then - for x in * ; do if [[ $x != "v" ]] ; then rm -rf $x ; fi ; done -else - echo IN WRONG DIRECTORY $TARGET - export TARGET to continue - exit 1 -fi -popd - -# build for hosting of / rather than /v/VERSION/ -_scripts/build.sh --url "" || { echo "failed to build docs" ; exit 1 ; } -cp -r _site/* $TARGET/ - -# and git push -pushd $TARGET -git add -A . -git commit -m "updated root docs for version $BV" -git push -popd - - -// END +Docs release instructions can be found at: +http://brooklyncentral.github.io/dev/tips/release.html http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/bd0e1e07/docs/use/guide/locations/index.md ---------------------------------------------------------------------- diff --git a/docs/use/guide/locations/index.md b/docs/use/guide/locations/index.md index 9570aa4..1c0668e 100644 --- a/docs/use/guide/locations/index.md +++ b/docs/use/guide/locations/index.md @@ -11,9 +11,11 @@ These can be clouds (public or private), fixed infrastructure environments, or y Brooklyn looks for Location configuration in `~/.brooklyn/brooklyn.properties`. -### Must have an SSH key +## Setting up an SSH key -To access any locations, Brooklyn must have access to an SSH key. By default Brooklyn looks for a key at `~/.ssh/id_rsa` and `~/.ssh/id_dsa`. +While some locations can be accessed using *user:password* credentials it is more common to use authentication keys. + +To use keyfile based authentication, Brooklyn requires that the management machine has an SSH key. By default Brooklyn looks for a key at `~/.ssh/id_rsa` and `~/.ssh/id_dsa`. If you do not already have an SSH key installed, create a new id_rsa key: @@ -28,60 +30,67 @@ that has a passphrase, or a location other than `~/.ssh`, you can specify this i ## Localhost -To allow Brooklyn to access locahost the SSH key must be added to the `authorized_keys` on that machine. +Brooklyn can access localhost if there is an SSH key on the machine and if the SSH key has been added to the list of `authorized_keys` on that machine. {% highlight bash %} # _Appends_ id_rsa.pub to authorized_keys. Other keys are unaffected. $ cat ~/.ssh/id_rsa.pub >> ~/.ssh/authorized_keys {% endhighlight %} -(MacOS user?: In addition to the above, enable 'Remote Login' in System Preferences > - Sharing.) +MacOS user? In addition to the above, enable 'Remote Login' in System Preferences > + Sharing. ## Cloud Endpoints (via jclouds) -[Apache jclouds](http://www.jclouds.org) is a multi-cloud library that Brooklyn uses to access [many clouds](http://www.jclouds.org/documentation/reference/supported-providers/). +[Apache jclouds](http://www.jclouds.org) is a multi-cloud library that Brooklyn uses to access many clouds. The [full list of supported providers](http://jclouds.apache.org/reference/providers/) is available on jclouds.apache.org. + +Add your cloud provider's (API) credentials to `brooklyn.properties` and create an SSH key on the management machine. + +Some clouds provide both API keys and SSH keys. In this case add only the API credentials to `brooklyn.properties`. (jclouds will transparently use the API credentials to setup access using the management machine's SSH key.) ### Example: AWS Virginia Large Centos {% highlight bash %} +## Snippet from ~/.brooklyn/brooklyn.properties. + # Provide jclouds with AWS API credentials. -brooklyn.jclouds.aws-ec2.identity = AKA_YOUR_ACCESS_KEY_ID -brooklyn.jclouds.aws-ec2.credential = YourSecretKeyWhichIsABase64EncodedString +brooklyn.location.jclouds.aws-ec2.identity = AKA_YOUR_ACCESS_KEY_ID +brooklyn.location.jclouds.aws-ec2.credential = YourSecretKeyWhichIsABase64EncodedString # Name this location 'AWS Virginia Large Centos' and wire to AWS US-East-1 brooklyn.location.named.AWS\ Virginia\ Large\ Centos = jclouds:aws-ec2:us-east-1 -# Specify image, user and minimum ram size (ie instance size) +# (Using the same name) specify image, user and minimum ram size (ie instance size) brooklyn.location.named.AWS\ Virginia\ Large\ Centos.imageId=us-east-1/ami-7d7bfc14 brooklyn.location.named.AWS\ Virginia\ Large\ Centos.user=root brooklyn.location.named.AWS\ Virginia\ Large\ Centos.minRam=4096 -# Snippet from ~/.brooklyn/brooklyn.properties. + {% endhighlight %} -This will appear as 'AWS Virginia Large Centos' in the web console, but will need to be escaped on the command line: `AWS\ Virginia\ Large\ Centos`. +This will appear as 'AWS Virginia Large Centos' in the web console, but will need to be escaped on the command line as: `AWS\ Virginia\ Large\ Centos`. See the Getting Started [template brooklyn.properties](/use/guide/quickstart/brooklyn.properties) for more examples of using cloud endpoints. ## Fixed Infrastructure -Bring-ing your own nodes (BYON) to Brooklyn is straightforward. +Bringing your own nodes (BYON) to Brooklyn is straightforward. You will need the IP addresses of the nodes and the access credentials. Both SSH and password based login are supported. ### Example: On-Prem Iron {% highlight bash %} +## Snippet from ~/.brooklyn/brooklyn.properties. + # Use the byon prefix, and provide the IP addresss (or IP ranges) brooklyn.location.named.On-Prem\ Iron\ Example=byon:(hosts="10.9.1.1,10.9.1.2,produser2@10.9.2.{10,11,20-29}") brooklyn.location.named.On-Prem\ Iron\ Example.user=produser1 brooklyn.location.named.On-Prem\ Iron\ Example.privateKeyFile=~/.ssh/produser_id_rsa brooklyn.location.named.On-Prem\ Iron\ Example.privateKeyPassphrase=s3cr3tpassphrase -# Snippet from ~/.brooklyn/brooklyn.properties. {% endhighlight %} http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/bd0e1e07/docs/use/guide/quickstart/brooklyn.properties ---------------------------------------------------------------------- diff --git a/docs/use/guide/quickstart/brooklyn.properties b/docs/use/guide/quickstart/brooklyn.properties index 53b479a..08a9d7c 100644 --- a/docs/use/guide/quickstart/brooklyn.properties +++ b/docs/use/guide/quickstart/brooklyn.properties @@ -6,22 +6,13 @@ # It's great to have you here. -# Getting Started options have been pulled to the top. They are repeated further down. -# When you are happy with what Brooklyn does, and how to use it, you can delete the -# Getting Started Section completely, and use the full options below to setup your -# configuration. - -# (There's a formatting guide at the very bottom.) +# Getting Started options have been pulled to the top. There's a formatting guide at the +# very bottom. ############################ Getting Started Options #################################### -# By default we have AWS and Rackspace (non-UK) set up (but with invalid credentials!) -# For each of those, either set the credentials immediately below -# or remove the corresponding "location.named" lines far below -# (i.e. look for brooklyn.location.named...=...<aws>.. or =...<cloudservers>... ) - -# For other clouds, ADD corresponding identity and credential lines -# and enable the "brooklyn.location.named" line(s) setup far below +# By default we have AWS set up (but with invalid credentials!). Many, many other +# providers are supported. ## Amazon EC2 Credentials # These should be an "Access Key ID" and "Secret Access Key" for your account. @@ -30,18 +21,28 @@ brooklyn.location.jclouds.aws-ec2.identity = AKA_YOUR_ACCESS_KEY_ID brooklyn.location.jclouds.aws-ec2.credential = <access-key-hex-digits> -# Instructions for many other clouds (public and private) are below. - # Beware of trailing spaces in your cloud credentials. This will cause unexpected # 401: unauthorized responses. -## SSH key for localhost +## Using Other Clouds +# 1. Cast your eyes down this document to find your preferred cloud in the Named Locations +# section, and the examples. +# 2. Uncomment the relevant line(s) for your provider. +# 3. ADD -.identity and -.credential lines for your provider, similar to the AWS ones above, +# replacing 'aws-ec2' with jcloud's id for your cloud. + + +## Deploying to Localhost +## see: brooklyncentral.github.io/use/guide/locations/ +# ## ~/.ssh/id_rsa is Brooklyn's default location -## Passphrases are supported, but not required # brooklyn.location.localhost.privateKeyFile = ~/.ssh/id_rsa +## Passphrases are supported, but not required # brooklyn.location.localhost.privateKeyPassphrase = s3cr3tpassphrase -## Geoscaling Service (Used for global web fabric demo) https://www.geoscaling.com/dns2/ +## Geoscaling Service - used for the Global Web Fabric demo +## see: brooklyncentral.github.io/use/examples/global-web-fabric/ and +## https://www.geoscaling.com/dns2/ ## other services may take similar configuration similarly; or can usually be set in YAML # brooklyn.geoscaling.username = USERNAME # brooklyn.geoscaling.password = PASSWORD @@ -52,10 +53,9 @@ brooklyn.location.jclouds.aws-ec2.credential = <access-key-hex-digits> # That's it, although you may want to read through these options... - ################################ Brooklyn Options ######################################## -## Brooklyn Mgmt Base Directory: specify where mgmt data should be stored on this server; +## Brooklyn Management Base Directory: specify where management data should be stored on this server; ## ~/.brooklyn/ is the default but you could use something like /opt/brooklyn/state/ ## (provided this process has write permissions) # brooklyn.base.dir=~/.brooklyn/ @@ -91,11 +91,11 @@ brooklyn.location.jclouds.aws-ec2.credential = <access-key-hex-digits> ## many cloud machines don't have sufficient entropy for lots of encrypted networking, so fake it: # brooklyn.location.jclouds.installDevUrandom=true -## This sets a property for all AWS machines. Recommended to avoid getting m1.micros ! +## Sets a minimium ram property for all jclouds locations. Recommended to avoid getting m1.micros on AWS! brooklyn.location.jclouds.minRam = 2048 -## By default it will set up a user with the same name as the user running on the brooklyn server, -## but you can force a user here: +## When setting up a new cloud machine Brooklyn creates a user with the same name as the user running +## Brooklyn on the management server, but you can force a different user here: # brooklyn.location.jclouds.user=brooklyn ## And you can force a password or key (by default it will use the keys in ~/.ssh/id_rsa{,.pub} # brooklyn.location.jclouds.password=s3cr3t @@ -103,7 +103,7 @@ brooklyn.location.jclouds.minRam = 2048 ################################ Named Locations ######################################## # Named locations appear in the web console. If using the command line or YAML it may be -# just as easy to use the jclouds:<provider> locations and specify add'l properties there. +# just as easy to use the jclouds:<provider> locations and specify additional properties there. ## Example: AWS Virginia using Rightscale 6.3 64bit Centos AMI and Large Instances # brooklyn.location.named.aws-va-centos-large = jclouds:aws-ec2:us-east-1 @@ -125,7 +125,7 @@ brooklyn.location.named.aws-oregon = jclouds:aws-ec2:us-west-2 brooklyn.location.named.aws-ireland = jclouds:aws-ec2:eu-west-1 brooklyn.location.named.aws-tokyo = jclouds:aws-ec2:ap-northeast-1 -## Similarly, for Google Compute +## Google Compute ## Note at present you have to create and download the P12 key from the Google "APIs & auth -> Registered Apps" interface, ## then convert to PEM private key format using `openssl pkcs12 -in Certificates.p12 -out Certificates.pem -nodes` ## then embed that on one line as the 'credential, replacing new lines with \n as below @@ -146,13 +146,13 @@ brooklyn.location.named.aws-tokyo = jclouds:aws-ec2:ap-northeast-1 ## gce images often start with iptables turned on; turn it off # brooklyn.location.jclouds.google-compute-engine.stopIptables=true -## Similarly, here are definitions for HP Cloud - also Ubuntu 12.04 LTS +## HP Cloud - also Ubuntu 12.04 LTS ## You specify your HP Credentials like this: # brooklyn.location.jclouds.hpcloud-compute.identity = projectname:username # brooklyn.location.jclouds.hpcloud-compute.credential = password ## where username and password are the same as logging in to the web console, and ## projectname can be found here: https://account.hpcloud.com/projects -#�brooklyn.location.named.HP\ Cloud\ Arizona-1 = jclouds:hpcloud-compute:az-1.region-a.geo-1 +#�brooklyn.location.named.HP\ Cloud\ Arizona-1 = jclouds:hpcloud-compute:az-1.region-a.geo-1 # brooklyn.location.named.HP\ Cloud\ Arizona-1.imageId = az-1.region-a.geo-1/75845 # brooklyn.location.named.HP\ Cloud\ Arizona-1.user = ubuntu @@ -172,7 +172,7 @@ brooklyn.location.named.aws-tokyo = jclouds:aws-ec2:ap-northeast-1 ## Brooklyn uses the jclouds multi-cloud library to access many clouds. ## http://www.jclouds.org/documentation/reference/supported-providers/ -## Templates for many other clouds, but remember the identity and credentials: +## Templates for many other clouds, but remember to add identity and credentials: # brooklyn.location.named.Bluelock = jclouds:bluelock-vcloud-zone01 @@ -222,23 +222,23 @@ brooklyn.location.named.aws-tokyo = jclouds:aws-ec2:ap-northeast-1 ## Production pool of machines for my application (deploy to named:On-Prem\ Iron\ Example) -#brooklyn.location.named.On-Prem\ Iron\ Example=byon:(hosts="10.9.1.1,10.9.1.2,produser2@10.9.2.{10,11,20-29}") -#brooklyn.location.named.On-Prem\ Iron\ Example.user=produser1 -#brooklyn.location.named.On-Prem\ Iron\ Example.privateKeyFile=~/.ssh/produser_id_rsa -#brooklyn.location.named.On-Prem\ Iron\ Example.privateKeyPassphrase=s3cr3tpassphrase +# brooklyn.location.named.On-Prem\ Iron\ Example=byon:(hosts="10.9.1.1,10.9.1.2,produser2@10.9.2.{10,11,20-29}") +# brooklyn.location.named.On-Prem\ Iron\ Example.user=produser1 +# brooklyn.location.named.On-Prem\ Iron\ Example.privateKeyFile=~/.ssh/produser_id_rsa +# brooklyn.location.named.On-Prem\ Iron\ Example.privateKeyPassphrase=s3cr3tpassphrase -## Various private clouds +## Various Private Clouds ## openstack identity and credential are random strings of letters and numbers (TBC - still the case?) -#brooklyn.location.named.My\ Openstack=jclouds:openstack-nova:https://9.9.9.9:9999/v2.0/ +# brooklyn.location.named.My\ Openstack=jclouds:openstack-nova:https://9.9.9.9:9999/v2.0/ ## cloudstack identity and credential are rather long random strings of letters and numbers ## you generate this in the cloudstack gui, under accounts, then "view users", then "generate key" ## use the "api key" as the identity and "secret key" as the credential -#brooklyn.location.named.My\ Cloudstack=jclouds:cloudstack:http://9.9.9.9:9999/client/api/ +# brooklyn.location.named.My\ Cloudstack=jclouds:cloudstack:http://9.9.9.9:9999/client/api/ ## abiquo identity and credential are your login username/passed -#brooklyn.location.named.My\ Abiquo=jclouds:abiquo:http://demonstration.abiquo.com/api/ +# brooklyn.location.named.My\ Abiquo=jclouds:abiquo:http://demonstration.abiquo.com/api/ ############################### Formatting Guide ####################################### http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/bd0e1e07/docs/use/guide/quickstart/images/add-application-catalog-web-cluster-with-db-large.png ---------------------------------------------------------------------- diff --git a/docs/use/guide/quickstart/images/add-application-catalog-web-cluster-with-db-large.png b/docs/use/guide/quickstart/images/add-application-catalog-web-cluster-with-db-large.png new file mode 100644 index 0000000..b566b1a Binary files /dev/null and b/docs/use/guide/quickstart/images/add-application-catalog-web-cluster-with-db-large.png differ http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/bd0e1e07/docs/use/guide/quickstart/images/add-application-catalog-web-cluster-with-db-location-large.png ---------------------------------------------------------------------- diff --git a/docs/use/guide/quickstart/images/add-application-catalog-web-cluster-with-db-location-large.png b/docs/use/guide/quickstart/images/add-application-catalog-web-cluster-with-db-location-large.png new file mode 100644 index 0000000..05e9b0c Binary files /dev/null and b/docs/use/guide/quickstart/images/add-application-catalog-web-cluster-with-db-location-large.png differ http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/bd0e1e07/docs/use/guide/quickstart/images/add-application-catalog-web-cluster-with-db-location.png ---------------------------------------------------------------------- diff --git a/docs/use/guide/quickstart/images/add-application-catalog-web-cluster-with-db-location.png b/docs/use/guide/quickstart/images/add-application-catalog-web-cluster-with-db-location.png new file mode 100644 index 0000000..c13fdd8 Binary files /dev/null and b/docs/use/guide/quickstart/images/add-application-catalog-web-cluster-with-db-location.png differ http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/bd0e1e07/docs/use/guide/quickstart/images/add-application-catalog-web-cluster-with-db.png ---------------------------------------------------------------------- diff --git a/docs/use/guide/quickstart/images/add-application-catalog-web-cluster-with-db.png b/docs/use/guide/quickstart/images/add-application-catalog-web-cluster-with-db.png new file mode 100644 index 0000000..ebb6f42 Binary files /dev/null and b/docs/use/guide/quickstart/images/add-application-catalog-web-cluster-with-db.png differ http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/bd0e1e07/docs/use/guide/quickstart/images/add-application-modal-yaml.png ---------------------------------------------------------------------- diff --git a/docs/use/guide/quickstart/images/add-application-modal-yaml.png b/docs/use/guide/quickstart/images/add-application-modal-yaml.png new file mode 100644 index 0000000..c50b7ab Binary files /dev/null and b/docs/use/guide/quickstart/images/add-application-modal-yaml.png differ http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/bd0e1e07/docs/use/guide/quickstart/images/jboss7-cluster-policies-large.png ---------------------------------------------------------------------- diff --git a/docs/use/guide/quickstart/images/jboss7-cluster-policies-large.png b/docs/use/guide/quickstart/images/jboss7-cluster-policies-large.png new file mode 100644 index 0000000..3d84477 Binary files /dev/null and b/docs/use/guide/quickstart/images/jboss7-cluster-policies-large.png differ http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/bd0e1e07/docs/use/guide/quickstart/images/jboss7-cluster-policies.png ---------------------------------------------------------------------- diff --git a/docs/use/guide/quickstart/images/jboss7-cluster-policies.png b/docs/use/guide/quickstart/images/jboss7-cluster-policies.png new file mode 100644 index 0000000..2f85328 Binary files /dev/null and b/docs/use/guide/quickstart/images/jboss7-cluster-policies.png differ http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/bd0e1e07/docs/use/guide/quickstart/images/my-db-activities-large.png ---------------------------------------------------------------------- diff --git a/docs/use/guide/quickstart/images/my-db-activities-large.png b/docs/use/guide/quickstart/images/my-db-activities-large.png new file mode 100644 index 0000000..c214d9e Binary files /dev/null and b/docs/use/guide/quickstart/images/my-db-activities-large.png differ http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/bd0e1e07/docs/use/guide/quickstart/images/my-db-activities.png ---------------------------------------------------------------------- diff --git a/docs/use/guide/quickstart/images/my-db-activities.png b/docs/use/guide/quickstart/images/my-db-activities.png new file mode 100644 index 0000000..0f2327c Binary files /dev/null and b/docs/use/guide/quickstart/images/my-db-activities.png differ http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/bd0e1e07/docs/use/guide/quickstart/images/my-web-cluster-starting.png ---------------------------------------------------------------------- diff --git a/docs/use/guide/quickstart/images/my-web-cluster-starting.png b/docs/use/guide/quickstart/images/my-web-cluster-starting.png new file mode 100644 index 0000000..c389b0b Binary files /dev/null and b/docs/use/guide/quickstart/images/my-web-cluster-starting.png differ http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/bd0e1e07/docs/use/guide/quickstart/images/my-web-cluster-stop-confirm-large.png ---------------------------------------------------------------------- diff --git a/docs/use/guide/quickstart/images/my-web-cluster-stop-confirm-large.png b/docs/use/guide/quickstart/images/my-web-cluster-stop-confirm-large.png new file mode 100644 index 0000000..c9bdab6 Binary files /dev/null and b/docs/use/guide/quickstart/images/my-web-cluster-stop-confirm-large.png differ http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/bd0e1e07/docs/use/guide/quickstart/images/my-web-cluster-stop-confirm.png ---------------------------------------------------------------------- diff --git a/docs/use/guide/quickstart/images/my-web-cluster-stop-confirm.png b/docs/use/guide/quickstart/images/my-web-cluster-stop-confirm.png new file mode 100644 index 0000000..179b00a Binary files /dev/null and b/docs/use/guide/quickstart/images/my-web-cluster-stop-confirm.png differ http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/bd0e1e07/docs/use/guide/quickstart/images/my-web-summary-large.png ---------------------------------------------------------------------- diff --git a/docs/use/guide/quickstart/images/my-web-summary-large.png b/docs/use/guide/quickstart/images/my-web-summary-large.png new file mode 100644 index 0000000..fc4bffe Binary files /dev/null and b/docs/use/guide/quickstart/images/my-web-summary-large.png differ http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/bd0e1e07/docs/use/guide/quickstart/images/my-web-summary.png ---------------------------------------------------------------------- diff --git a/docs/use/guide/quickstart/images/my-web-summary.png b/docs/use/guide/quickstart/images/my-web-summary.png new file mode 100644 index 0000000..e85752f Binary files /dev/null and b/docs/use/guide/quickstart/images/my-web-summary.png differ http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/bd0e1e07/docs/use/guide/quickstart/images/my-web.png ---------------------------------------------------------------------- diff --git a/docs/use/guide/quickstart/images/my-web.png b/docs/use/guide/quickstart/images/my-web.png new file mode 100644 index 0000000..2bd6ac3 Binary files /dev/null and b/docs/use/guide/quickstart/images/my-web.png differ http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/bd0e1e07/docs/use/guide/quickstart/index.md ---------------------------------------------------------------------- diff --git a/docs/use/guide/quickstart/index.md b/docs/use/guide/quickstart/index.md index 35db7f3..289acd8 100644 --- a/docs/use/guide/quickstart/index.md +++ b/docs/use/guide/quickstart/index.md @@ -7,30 +7,12 @@ categories: [use, guide] {% include fields.md %} -This guide will walk you through deploying an application to a public cloud, and managing that application. +This guide will walk you through deploying an application to a public cloud. We will be deploying an example 3-tier web application, described using this blueprint: {% highlight yaml %} -name: My Web Cluster -location: localhost - -services: - -- serviceType: brooklyn.entity.webapp.ControlledDynamicWebAppCluster - name: My Web - location: localhost - 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 - java.sysprops: - brooklyn.example.db.url: $brooklyn:formatString("jdbc:%s%s?user=%s\\&password=%s", - component("db").attributeWhenReady("database.url"), "visitors", "brooklyn", "br00k11n") - -- serviceType: brooklyn.entity.database.mysql.MySqlNode - id: db - name: My DB - brooklyn.config: - creationScriptUrl: classpath://visitors-creation-script.sql +{% readj my-web-cluster.yaml %} {% endhighlight %} (This is written in YAML, following the [camp specification](https://www.oasis-open.org/committees/camp/). ) @@ -58,12 +40,14 @@ $ tar -zxf brooklyn-dist-{{ site.brooklyn-version }}-dist.tar.gz This will create a `brooklyn-{{ site.brooklyn-version }}` folder. -Note: you'll also need Java JRE or SDK installed (version 6 or later). +Note: You'll need a Java JRE or SDK installed (version 6 or later), as Brooklyn is Java under the covers. ## Launch Brooklyn Let's setup some paths for easy commands. +(Click the clipboard on these code snippets for easier c&p.) + {% highlight bash %} $ cd brooklyn-{{ site.brooklyn-version }} $ BROOKLYN_DIR="$(pwd)" @@ -78,7 +62,10 @@ $ brooklyn launch Brooklyn will output the address of the management interface: -`... Started Brooklyn console at http://127.0.0.1:8081/` ([link](http://127.0.0.1:8081/)) + +`INFO Starting brooklyn web-console on loopback interface because no security config is set` + +`INFO Started Brooklyn console at http://127.0.0.1:8081/, running classpath://brooklyn.war and []` But before we really use Brooklyn, we need to setup some Locations. @@ -86,19 +73,23 @@ Stop Brooklyn with ctrl-c. ## Configuring a Location -Brooklyn deploys applications to Locations. Locations can be clouds, machines with fixed IPs or localhost (for testing). +Brooklyn deploys applications to Locations. + +Locations can be clouds, machines with fixed IPs or localhost (for testing). Brooklyn loads Location configuration from `~/.brooklyn/brooklyn.properties`. -Create a `.brooklyn` folder in your home directory: +Create a `.brooklyn` folder in your home directory and download the template [brooklyn.properties](brooklyn.properties) to that folder. {% highlight bash %} $ mkdir ~/.brooklyn +$ cd ~/.brooklyn +$ wget {{site.url}}/use/guide/quickstart/brooklyn.properties {% endhighlight %} -Download the template [brooklyn.properties](brooklyn.properties) and place this in `~/.brooklyn`. +Open brooklyn.properties in a text editor and add your cloud credentials. -Open the file in a text editor and add your cloud credentials. If you would rather test Brooklyn on localhost, follow [these instructions](/use/guide/locations/) to ensure that your Brooklyn can access your machine. +If you would rather test Brooklyn on localhost, follow [these instructions]({{site.url}}/use/guide/locations/) to ensure that your Brooklyn can access your machine. Restart Brooklyn: @@ -108,66 +99,83 @@ $ brooklyn launch ## Launching an Application -There are several ways to deploy a YAML blueprint: +There are several ways to deploy a YAML blueprint (including specifying the blueprint on the command line or submitting it via the REST API). -1. We can supply a blueprint file at startup: `brooklyn launch --app /path/to/myblueprint.yaml` -1. We can deploy using the web-console. -1. We can deploy using the brooklyn REST api. +For now, we will simply copy-and-paste the raw YAML blueprint into the web console. -We will use the second option to deploy a 3-tier web-app, using the YAML file at the top of this page. +Open the web console ([127.0.0.1:8081](http://127.0.0.1:8081)). As Brooklyn is not currently managing any applications the 'Create Application' dialog opens automatically. Select the YAML tab. -On the home page of the Brooklyn web-console, click the "add application" button (if no applications are currently running, this will be opened automatically). Select the YAML tab and paste your YAML code. + -### Chose your cloud / location -Edit the yaml to use the location you configured, e.g. replace: +### Chose your Cloud / Location + +Edit the 'location' parameter in the YAML template (repeated below) to use the location you configured. + +For example, replace: {% highlight yaml %} -location: localhost +location: location {% endhighlight %} -with: +with (one of): {% highlight yaml %} +location: aws-ec2:us-east-1 +location: rackspace-cloudservers-us:ORD location: google-compute-engine:europe-west1-a +location: localhost {% endhighlight %} -Click "finish". You should see your application listed, with status "STARTING". +**My Web Cluster Blueprint** -## Monitoring and managing applications +{% highlight yaml %} +{% readj my-web-cluster.yaml %} +{% endhighlight %} -In the Brooklyn web-console clicking on an application listed on the home page, or the Applications tab, will show all the applications currently running. +Paste the modified YAML into the dialog and click 'Finish'. +The dialog will close and Brooklyn will begin deploying your application. -We can explore the management hierarchy of an application, which will show us the entities it is composed of. If you have deployed the above YAML, then you'll see a standard 3-tier web-app. Clicking on the ControlledDynamicWebAppCluster will show if the cluster is ready to serve and, when ready, will provide a web address for the front of the loadbalancer. +Your application will be shown as 'Starting' on the web console's front page. -If the service.isUp, you can view the demo web application in your browser at the webapp.url. + -Through the Activities tab, you can drill into the activities each entity is doing or has recently done. Click on the task to see its details, and to drill into its "Children Tasks". For example, if you drill into MySqlNode's start operation, you can see the "Start (processes)", then "launch", and then the ssh command used including the stdin, stdout and stderr. +## Monitoring and Managing Applications -## Stopping the application +Click on the application name, or open the Applications tab. -To stop an application, select the application in the tree view, click on the Effectors tab, and invoke the "Stop" effector. This will cleanly shutdown all components in the application. +We can explore the management hierarchy of the application, which will show us the entities it is composed of. -### Testing the Policies + * My Web Cluster (A `BasicApplication`) + * My DB (A `MySqlNode`) + * My Web (A `ControlledDynamicWebAppCluster`) + * Cluster of JBoss7 Servers (A `DynamicWebAppCluster`) + * NginxController (An `NginxController`) -Brooklyn at its heart is a policy driven management plane which can implement business and technical policies. -The Web Cluster with DB demo comes pre-configured with an `AutoScalerPolicy`, attached to -the cluster of JBoss7 servers and a `targets` policy attached to the loadbalancer. You can - observe policies this in the management console using the Policy tab of the relevant - entity (e.g. `DynamicWebAppCluster` shows the `AutoScalerPolicy`. -The cluster autoscaler policy will automatically scale the cluster up or down to be the -right size for the current load. ('One server' is the minimum size allowed by the policy.) -The loadbalancer will automatically be updated by the targets policy as the cluster size -changes. +Clicking on the 'My Web' entity will show the Summary tab. Here we can see if the cluster is ready to serve and, when ready, grab the web address for the front of the loadbalancer. + + + + +The Activity tab allows us to drill down into what activities each entity is currently doing or has recently done. It is possible to drill down to all child tasks, and view the commands issued, and any errors or warnings that occured. + +Drill into the 'My DB' start operation. Working down through 'Start (processes)', then 'launch', we can discover the ssh command used including the stdin, stdout and stderr. + +[](images/my-db-activities-large.png) + + +## Stopping the Application + +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. + +[](images/my-web-cluster-stop-confirm-large.png) -Sitting idle, your cluster will only contain one server, but you can check that the policy -works using a tool like [jmeter](http://jmeter.apache.org/) pointed at the nginx endpoint -to create load on the cluster. ### 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. +So far we have touched on Brooklyn's ability to *deploy* an application blueprint to a cloud provider, but this a very small part of Brooklyn's capabilities! + +Brooklyn's real power is in using Policies to automatically *manage* applications. There is also the (very useful) ability to store a catalog of application blueprints, ready to go. + +[Getting Started - Policies and Catalogs](policies-and-catalogs.html) http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/bd0e1e07/docs/use/guide/quickstart/my-web-cluster.yaml ---------------------------------------------------------------------- diff --git a/docs/use/guide/quickstart/my-web-cluster.yaml b/docs/use/guide/quickstart/my-web-cluster.yaml new file mode 100644 index 0000000..bbafa00 --- /dev/null +++ b/docs/use/guide/quickstart/my-web-cluster.yaml @@ -0,0 +1,19 @@ +name: My Web Cluster +location: location +services: + +- serviceType: brooklyn.entity.webapp.ControlledDynamicWebAppCluster + name: My Web + brooklyn.config: + wars.root: http://search.maven.org/remotecontent?filepath=io/brooklyn/example/brooklyn-example-hello-world-sql-webapp/{{ site.brooklyn-version }}/brooklyn-example-hello-world-sql-webapp-{{ site.brooklyn-version }}.war + java.sysprops: + brooklyn.example.db.url: > + $brooklyn:formatString("jdbc:%s%s?user=%s\\&password=%s", + component("db").attributeWhenReady("datastore.url"), + "visitors", "brooklyn", "br00k11n") + +- serviceType: brooklyn.entity.database.mysql.MySqlNode + id: db + name: My DB + brooklyn.config: + creationScriptUrl: https://bit.ly/brooklyn-visitors-creation-script \ No newline at end of file http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/bd0e1e07/docs/use/guide/quickstart/policies-and-catalogs.md ---------------------------------------------------------------------- diff --git a/docs/use/guide/quickstart/policies-and-catalogs.md b/docs/use/guide/quickstart/policies-and-catalogs.md new file mode 100644 index 0000000..efa06ff --- /dev/null +++ b/docs/use/guide/quickstart/policies-and-catalogs.md @@ -0,0 +1,66 @@ +--- +title: Getting Started - Policies and Catalogs +layout: page +toc: ../guide_toc.json +categories: [use, guide] +--- + +{% include fields.md %} + +In the [previous step](index.html) we downloaded Brooklyn and used it to deploy an application to a cloud, but at its heart Brooklyn is a policy driven *management* plane. + +Here we will introduce Polices using a simple demo app, which we will load from a Service Catalog. + +## Service Catalogs + +Download the template [catalog.xml](catalog.xml) to your `~/.brooklyn/` folder, and relaunch Brooklyn. + +{% highlight bash %} +$ cd ~/.brooklyn +$ wget {{site.url}}/use/guide/quickstart/catalog.xml + +$ brooklyn launch +{% endhighlight %} + +Now when we open the web console, two applications are displayed from the catalog. + +Select the 'Demo Web Cluster with DB' and click 'Next'. + +[](add-application-catalog-web-cluster-with-db-largea.png) + +Select the Location that Brooklyn should deploy to, and name your application: + +[](images/add-application-catalog-web-cluster-with-db-location-large.png) + +Click 'Finish' to launch the application as before. + + +### Exploring and Testing Policies + +The Demo Web Cluster with DB application is pre-configured with two polices. + +The app server cluster has an `AutoScalerPolicy`, and the loadbalancer has a `targets` policy. + +Use the Applications tab in the web console to drill down into the Policies section of the ControlledDynamicWebAppCluster's Cluster of JBoss7Servers. + +You will see that the `AutoScalerPolicy` is running. + +[](images/jboss7-cluster-policies-large.png) + + +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 `targets` policy ensures that the loadbalancer is updated as the cluster size changes. + +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](https://github.com/brooklyncentral/brooklyn/blob/master/examples/simple-web-cluster/resources/jmeter-test-plan.jmx).) + +As load is added, 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. + +### Next + +The [Elastic Web Cluster Example]({{site.url}}/use/examples/webcluster/index.html) page +details how to build this demo application from scratch in Java. It shows in more detail how Brooklyn can +complement your application with policy driven management, and how applications can be +run from the command line. + + http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/bd0e1e07/docs/use/guide/quickstart/toc.json ---------------------------------------------------------------------- diff --git a/docs/use/guide/quickstart/toc.json b/docs/use/guide/quickstart/toc.json new file mode 100644 index 0000000..d65eddb --- /dev/null +++ b/docs/use/guide/quickstart/toc.json @@ -0,0 +1,4 @@ +[{ "title": "Download & Deploy", + "file": "{{ site.url }}/use/guide/quickstart/index.html" }, +{ "title": "Policies & Catalogs", + "file": "{{ site.url }}/use/guide/quickstart/policies-and-catalogs.html" }] http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/bd0e1e07/docs/use/guide/toc.json ---------------------------------------------------------------------- diff --git a/docs/use/guide/toc.json b/docs/use/guide/toc.json index 8bdb955..7c4aa13 100644 --- a/docs/use/guide/toc.json +++ b/docs/use/guide/toc.json @@ -1,12 +1,15 @@ [ { "title": "Quick Start", - "file": "{{ site.url }}/use/guide/quickstart/index.html" }, + "file": "{{ site.url }}/use/guide/quickstart/index.html", + "children": {% readj ./quickstart/toc.json %} }, { "title": "Defining Applications", "file": "{{ site.url }}/use/guide/defining-applications/basic-concepts.html", "children": {% readj ./defining-applications/toc.json %} }, { "title": "Management", "file": "{{ site.url }}/use/guide/management/index.html" , "children": {% readj ./management/toc.json %} }, +{ "title": "Locations", + "file": "{{ site.url }}/use/guide/locations/index.html" }, { "title": "Policies", "file": "{{ site.url }}/use/guide/policies/index.html", "children": {% readj ./policies/toc.json %} },
