brooklyn-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From drigod...@apache.org
Subject [12/28] brooklyn-docs git commit: Refactor Blueprinting
Date Fri, 16 Jun 2017 15:21:52 GMT
Refactor Blueprinting

(cherry picked from commit f38b9e7bbcf745fdb6eb2526a334d26fd03cecfb)


Project: http://git-wip-us.apache.org/repos/asf/brooklyn-docs/repo
Commit: http://git-wip-us.apache.org/repos/asf/brooklyn-docs/commit/1330dcd3
Tree: http://git-wip-us.apache.org/repos/asf/brooklyn-docs/tree/1330dcd3
Diff: http://git-wip-us.apache.org/repos/asf/brooklyn-docs/diff/1330dcd3

Branch: refs/heads/0.11.x
Commit: 1330dcd30a6671d976e51dc007d5d5b6458cdbde
Parents: b98477b
Author: Duncan Godwin <duncan.godwin@cloudsoftcorp.com>
Authored: Wed Apr 12 18:02:16 2017 +0100
Committer: Richard Downer <richard@apache.org>
Committed: Wed May 31 15:24:22 2017 +0100

----------------------------------------------------------------------
 contributing/inline-children.md                 |   2 +-
 contributing/ordering.md                        |   4 +-
 contributing/site-structure.md                  |   2 +-
 guide/blueprints/advanced-example.md            | 283 +++++++++
 guide/blueprints/ansible/about-ansible.md       |  34 +
 .../ansible/creating-ansible-blueprints.md      | 213 +++++++
 guide/blueprints/ansible/index.md               |  16 +
 guide/blueprints/blueprinting-tips.md           | 183 ++++++
 .../catalog/images/add-to-catalog.png           | Bin 0 -> 4919 bytes
 guide/blueprints/catalog/index.md               | 400 ++++++++++++
 .../catalog/mysql-in-catalog-w700.png           | Bin 0 -> 92767 bytes
 guide/blueprints/catalog/mysql-in-catalog.png   | Bin 0 -> 168831 bytes
 guide/blueprints/chef/about-chef.md             |  50 ++
 .../chef/advanced-chef-integration.md           |  48 ++
 guide/blueprints/chef/chef-call-flow.png        | Bin 0 -> 36222 bytes
 guide/blueprints/chef/creating-blueprints.md    | 105 ++++
 .../chef/example_yaml/mysql-chef-1.yaml         |  24 +
 .../chef/example_yaml/mysql-chef-2.yaml         |  28 +
 guide/blueprints/chef/index.md                  |  18 +
 guide/blueprints/chef/writing-chef.md           |  79 +++
 guide/blueprints/clusters-and-policies.md       |  42 ++
 guide/blueprints/clusters.md                    |  34 +
 guide/blueprints/configuring-vms.md             |  31 +
 guide/blueprints/creating-yaml.md               |  78 +++
 guide/blueprints/custom-entities.md             | 269 ++++++++
 guide/blueprints/enrichers.md                   | 180 ++++++
 guide/blueprints/entity-configuration.md        | 548 ++++++++++++++++
 .../appserver-clustered-w-db-concise.yaml       |  15 +
 .../example_yaml/appserver-clustered-w-db.yaml  |  19 +
 .../appserver-configured-in-config.yaml         |   6 +
 .../example_yaml/appserver-configured.yaml      |   5 +
 .../appserver-w-db-other-flavor.yaml            |  17 +
 .../blueprints/example_yaml/appserver-w-db.yaml |  15 +
 .../example_yaml/appserver-w-policy.yaml        |  27 +
 guide/blueprints/example_yaml/cluster-vm.yaml   |  13 +
 .../fabric-with-multiple-locations.yaml         |  15 +
 .../simple-appserver-with-location-byon.yaml    |  10 +
 ...mple-appserver-with-location-per-entity.yaml |   8 +
 .../simple-appserver-with-location.yaml         |   8 +
 .../example_yaml/simple-appserver.yaml          |   4 +
 guide/blueprints/example_yaml/simple-vm.yaml    |   8 +
 ...est-app-with-enrichers-slightly-simpler.yaml |  58 ++
 .../vanilla-bash-netcat-catalog.bom             |  36 ++
 .../vanilla-bash-netcat-cluster.yaml            |  12 +
 .../example_yaml/vanilla-bash-netcat-env.yaml   |  12 +
 .../example_yaml/vanilla-bash-netcat-file.yaml  |   6 +
 .../vanilla-bash-netcat-more-commands.yaml      |  16 +
 .../vanilla-bash-netcat-port-parameter.yaml     |  21 +
 .../example_yaml/vanilla-bash-netcat-port.yaml  |  13 +
 .../vanilla-bash-netcat-reference.yaml          |   5 +
 .../vanilla-bash-netcat-restarter.yaml          |  20 +
 .../vanilla-bash-netcat-w-client.yaml           |  78 +++
 .../example_yaml/vanilla-bash-netcat.yaml       |   8 +
 guide/blueprints/index.md                       |  28 +
 guide/blueprints/java/archetype.md              | 114 ++++
 guide/blueprints/java/bundle-dependencies.md    | 135 ++++
 guide/blueprints/java/common-usage.md           | 205 ++++++
 guide/blueprints/java/defining-and-deploying.md | 177 ++++++
 guide/blueprints/java/entities.md               | 223 +++++++
 guide/blueprints/java/entitlements.md           |  42 ++
 guide/blueprints/java/entity.md                 | 104 +++
 guide/blueprints/java/feeds.md                  | 233 +++++++
 .../java/gist_generator/GistGenerator.java      |  29 +
 .../java/gist_generator/GistGeneratorImpl.java  |  47 ++
 .../java/gist_generator/GistGeneratorTest.java  |  20 +
 .../gist_generator/GistGeneratorYamlTest.java   |  39 ++
 .../java/gist_generator/gist_create_token.png   | Bin 0 -> 390046 bytes
 .../java/gist_generator/gist_generator.bom      |  14 +
 .../java/gist_generator/gist_grant_access.png   | Bin 0 -> 411974 bytes
 guide/blueprints/java/index.md                  |  36 ++
 .../blueprints/java/java_app/ExampleWebApp.java |  62 ++
 guide/blueprints/java/service-state.md          |  73 +++
 guide/blueprints/java/topology-dependencies.md  |  53 ++
 .../java/wt-deployed-application-700.png        | Bin 0 -> 176494 bytes
 .../blueprints/java/wt-deployed-application.png | Bin 0 -> 127347 bytes
 guide/blueprints/java/wt-starting-700.png       | Bin 0 -> 303892 bytes
 guide/blueprints/java/wt-starting.png           | Bin 0 -> 332710 bytes
 .../java/wt-tree-jboss-sensors-700.png          | Bin 0 -> 268853 bytes
 guide/blueprints/java/wt-tree-jboss-sensors.png | Bin 0 -> 169929 bytes
 guide/blueprints/logstash-snapshot.png          | Bin 0 -> 80486 bytes
 guide/blueprints/multiple-services.md           |  97 +++
 guide/blueprints/policies.md                    | 198 ++++++
 guide/blueprints/salt/about-salt.md             |  38 ++
 .../blueprints/salt/creating-salt-blueprints.md | 163 +++++
 guide/blueprints/salt/index.md                  |  16 +
 guide/blueprints/setting-locations.md           | 132 ++++
 ...infrastructuredeploymenttestcase-entity.yaml |  11 +
 .../entities/loopovergroupmembers-entity.yaml   |   6 +
 .../entities/paralleltestcase-entity.yaml       |   6 +
 .../test/example_yaml/entities/script1.sh       |   2 +
 .../example_yaml/entities/testcase-entity.yaml  |   6 +
 .../entities/testeffector-entity.yaml           |   8 +
 .../entities/testhttpcall-entity.yaml           |   7 +
 .../entities/testsensor-entity.yaml             |   7 +
 .../entities/testsshcommand-entity.yaml         |  28 +
 .../testcases/effector-test-snippet.yaml        |  28 +
 .../testcases/getting-started-test-example.yaml |  71 +++
 .../testcases/http-test-snippet.yaml            |  20 +
 .../testcases/sensor-test-snippet.yaml          |   7 +
 .../getting-started-blueprint-test-large.png    | Bin 0 -> 156553 bytes
 .../images/getting-started-blueprint-test.png   | Bin 0 -> 84906 bytes
 guide/blueprints/test/index.md                  |  33 +
 guide/blueprints/test/test-entities.md          | 198 ++++++
 guide/blueprints/test/usage-examples.md         |  58 ++
 guide/blueprints/web-console-yaml-700.png       | Bin 0 -> 138229 bytes
 guide/blueprints/web-console-yaml.png           | Bin 0 -> 661136 bytes
 guide/blueprints/winrm/client.md                | 125 ++++
 guide/blueprints/winrm/index.md                 | 630 +++++++++++++++++++
 guide/blueprints/yaml-reference.md              | 253 ++++++++
 guide/index.md                                  |   3 +-
 guide/java/archetype.md                         | 114 ----
 guide/java/bundle-dependencies.md               | 135 ----
 guide/java/common-usage.md                      | 205 ------
 guide/java/defining-and-deploying.md            | 177 ------
 guide/java/enrichers.md                         | 180 ------
 guide/java/entities.md                          | 223 -------
 guide/java/entitlements.md                      |  42 --
 guide/java/entity.md                            | 104 ---
 guide/java/feeds.md                             | 233 -------
 guide/java/gist_generator/GistGenerator.java    |  29 -
 .../java/gist_generator/GistGeneratorImpl.java  |  47 --
 .../java/gist_generator/GistGeneratorTest.java  |  20 -
 .../gist_generator/GistGeneratorYamlTest.java   |  39 --
 guide/java/gist_generator/gist_create_token.png | Bin 390046 -> 0 bytes
 guide/java/gist_generator/gist_generator.bom    |  14 -
 guide/java/gist_generator/gist_grant_access.png | Bin 411974 -> 0 bytes
 guide/java/index.md                             |  38 --
 guide/java/java_app/ExampleWebApp.java          |  62 --
 guide/java/policies.md                          | 198 ------
 guide/java/service-state.md                     |  73 ---
 guide/java/topology-dependencies.md             |  53 --
 guide/java/wt-deployed-application-700.png      | Bin 176494 -> 0 bytes
 guide/java/wt-deployed-application.png          | Bin 127347 -> 0 bytes
 guide/java/wt-starting-700.png                  | Bin 303892 -> 0 bytes
 guide/java/wt-starting.png                      | Bin 332710 -> 0 bytes
 guide/java/wt-tree-jboss-sensors-700.png        | Bin 268853 -> 0 bytes
 guide/java/wt-tree-jboss-sensors.png            | Bin 169929 -> 0 bytes
 guide/locations/_AWS.md                         | 141 +++++
 guide/locations/_GCE.md                         |  89 +++
 guide/locations/_azure-ARM.md                   | 102 +++
 guide/locations/_azure-classic.md               | 233 +++++++
 guide/locations/_byon.md                        |  77 +++
 guide/locations/_clouds.md                      | 302 +++++++++
 guide/locations/_cloudstack.md                  | 143 +++++
 guide/locations/_ibm-softlayer.md               | 135 ++++
 .../_inheritance-and-named-locations.md         |  80 +++
 guide/locations/_localhost.md                   |  48 ++
 guide/locations/_openstack.md                   | 269 ++++++++
 guide/locations/_special-locations.md           | 117 ++++
 guide/locations/_ssh-keys.md                    |  88 +++
 guide/locations/cloud-credentials.md            |   6 +
 guide/locations/index.md                        |  21 +
 guide/locations/location-customizers.md         | 169 +++++
 guide/ops/brooklyn_properties.md                |   4 +-
 guide/ops/catalog/images/add-to-catalog.png     | Bin 4919 -> 0 bytes
 guide/ops/catalog/index.md                      | 400 ------------
 guide/ops/catalog/mysql-in-catalog-w700.png     | Bin 92767 -> 0 bytes
 guide/ops/catalog/mysql-in-catalog.png          | Bin 168831 -> 0 bytes
 guide/ops/index.md                              |   8 +-
 guide/ops/locations/_AWS.md                     | 141 -----
 guide/ops/locations/_GCE.md                     |  89 ---
 guide/ops/locations/_azure-ARM.md               | 102 ---
 guide/ops/locations/_azure-classic.md           | 233 -------
 guide/ops/locations/_byon.md                    |  77 ---
 guide/ops/locations/_clouds.md                  | 302 ---------
 guide/ops/locations/_cloudstack.md              | 143 -----
 guide/ops/locations/_ibm-softlayer.md           | 135 ----
 .../_inheritance-and-named-locations.md         |  80 ---
 guide/ops/locations/_localhost.md               |  48 --
 guide/ops/locations/_openstack.md               | 269 --------
 guide/ops/locations/_special-locations.md       | 117 ----
 guide/ops/locations/_ssh-keys.md                |  88 ---
 guide/ops/locations/cloud-credentials.md        |   6 -
 guide/ops/locations/index.md                    |  21 -
 guide/ops/locations/location-customizers.md     | 169 -----
 guide/ops/persistence/index.md                  |   2 +-
 guide/ops/production-installation.md            |   4 +-
 guide/start/blueprints.md                       |   6 +-
 guide/start/brooklyn.properties                 |   2 +-
 guide/start/running.md                          |   2 +-
 guide/start/running/control.md                  |  25 +
 guide/start/running/index.md                    |  28 +
 guide/start/running/install.md                  | 101 +++
 guide/start/running/launch.md                   |  72 +++
 guide/yaml/advanced-example.md                  | 283 ---------
 guide/yaml/ansible/about-ansible.md             |  34 -
 .../yaml/ansible/creating-ansible-blueprints.md | 213 -------
 guide/yaml/ansible/index.md                     |  16 -
 guide/yaml/blueprinting-tips.md                 | 183 ------
 guide/yaml/chef/about-chef.md                   |  50 --
 guide/yaml/chef/advanced-chef-integration.md    |  48 --
 guide/yaml/chef/chef-call-flow.png              | Bin 36222 -> 0 bytes
 guide/yaml/chef/creating-blueprints.md          | 105 ----
 guide/yaml/chef/example_yaml/mysql-chef-1.yaml  |  24 -
 guide/yaml/chef/example_yaml/mysql-chef-2.yaml  |  28 -
 guide/yaml/chef/index.md                        |  18 -
 guide/yaml/chef/writing-chef.md                 |  79 ---
 guide/yaml/clusters-and-policies.md             |  42 --
 guide/yaml/clusters.md                          |  34 -
 guide/yaml/configuring-vms.md                   |  31 -
 guide/yaml/creating-yaml.md                     |  78 ---
 guide/yaml/custom-entities.md                   | 269 --------
 guide/yaml/entity-configuration.md              | 548 ----------------
 .../appserver-clustered-w-db-concise.yaml       |  15 -
 .../example_yaml/appserver-clustered-w-db.yaml  |  19 -
 .../appserver-configured-in-config.yaml         |   6 -
 .../yaml/example_yaml/appserver-configured.yaml |   5 -
 .../appserver-w-db-other-flavor.yaml            |  17 -
 guide/yaml/example_yaml/appserver-w-db.yaml     |  15 -
 guide/yaml/example_yaml/appserver-w-policy.yaml |  27 -
 guide/yaml/example_yaml/cluster-vm.yaml         |  13 -
 .../fabric-with-multiple-locations.yaml         |  15 -
 .../simple-appserver-with-location-byon.yaml    |  10 -
 ...mple-appserver-with-location-per-entity.yaml |   8 -
 .../simple-appserver-with-location.yaml         |   8 -
 guide/yaml/example_yaml/simple-appserver.yaml   |   4 -
 guide/yaml/example_yaml/simple-vm.yaml          |   8 -
 ...est-app-with-enrichers-slightly-simpler.yaml |  58 --
 .../vanilla-bash-netcat-catalog.bom             |  36 --
 .../vanilla-bash-netcat-cluster.yaml            |  12 -
 .../example_yaml/vanilla-bash-netcat-env.yaml   |  12 -
 .../example_yaml/vanilla-bash-netcat-file.yaml  |   6 -
 .../vanilla-bash-netcat-more-commands.yaml      |  16 -
 .../vanilla-bash-netcat-port-parameter.yaml     |  21 -
 .../example_yaml/vanilla-bash-netcat-port.yaml  |  13 -
 .../vanilla-bash-netcat-reference.yaml          |   5 -
 .../vanilla-bash-netcat-restarter.yaml          |  20 -
 .../vanilla-bash-netcat-w-client.yaml           |  78 ---
 .../yaml/example_yaml/vanilla-bash-netcat.yaml  |   8 -
 guide/yaml/index.md                             |  25 -
 guide/yaml/logstash-snapshot.png                | Bin 80486 -> 0 bytes
 guide/yaml/multiple-services.md                 |  97 ---
 guide/yaml/salt/about-salt.md                   |  38 --
 guide/yaml/salt/creating-salt-blueprints.md     | 163 -----
 guide/yaml/salt/index.md                        |  16 -
 guide/yaml/setting-locations.md                 | 132 ----
 ...infrastructuredeploymenttestcase-entity.yaml |  11 -
 .../entities/loopovergroupmembers-entity.yaml   |   6 -
 .../entities/paralleltestcase-entity.yaml       |   6 -
 .../yaml/test/example_yaml/entities/script1.sh  |   2 -
 .../example_yaml/entities/testcase-entity.yaml  |   6 -
 .../entities/testeffector-entity.yaml           |   8 -
 .../entities/testhttpcall-entity.yaml           |   7 -
 .../entities/testsensor-entity.yaml             |   7 -
 .../entities/testsshcommand-entity.yaml         |  28 -
 .../testcases/effector-test-snippet.yaml        |  28 -
 .../testcases/getting-started-test-example.yaml |  71 ---
 .../testcases/http-test-snippet.yaml            |  20 -
 .../testcases/sensor-test-snippet.yaml          |   7 -
 .../getting-started-blueprint-test-large.png    | Bin 156553 -> 0 bytes
 .../images/getting-started-blueprint-test.png   | Bin 84906 -> 0 bytes
 guide/yaml/test/index.md                        |  33 -
 guide/yaml/test/test-entities.md                | 198 ------
 guide/yaml/test/usage-examples.md               |  58 --
 guide/yaml/web-console-yaml-700.png             | Bin 138229 -> 0 bytes
 guide/yaml/web-console-yaml.png                 | Bin 661136 -> 0 bytes
 guide/yaml/winrm/client.md                      | 125 ----
 guide/yaml/winrm/index.md                       | 630 -------------------
 guide/yaml/yaml-reference.md                    | 253 --------
 website/index.md                                |   6 +-
 260 files changed, 9167 insertions(+), 8943 deletions(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/1330dcd3/contributing/inline-children.md
----------------------------------------------------------------------
diff --git a/contributing/inline-children.md b/contributing/inline-children.md
index 480f451..e16def5 100644
--- a/contributing/inline-children.md
+++ b/contributing/inline-children.md
@@ -26,7 +26,7 @@ in the YAML front matter of a page causes the site structure plug-in to look thr
 containing `section_type: inline` in the YAML front matter.
 
 The content from these inline sections can then be included in the page content using the liquid tag `child_content`. This is shown below
-in an example from [/guide/ops/locations/index.md](https://github.com/apache/brooklyn-docs/blob/master/guide/ops/locations/index.md){:target="_blank"}:
+in an example from [/guide/locations/index.md](https://github.com/apache/brooklyn-docs/blob/master/guide/locations/index.md){:target="_blank"}:
 
 <pre>
 ---

http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/1330dcd3/contributing/ordering.md
----------------------------------------------------------------------
diff --git a/contributing/ordering.md b/contributing/ordering.md
index 428360c..2f3a151 100644
--- a/contributing/ordering.md
+++ b/contributing/ordering.md
@@ -26,8 +26,8 @@ children:
 - { path: /guide/start/index.md, section_position: 3.1.2 }
 - { path: /guide/misc/download.md }
 - { path: /guide/concepts/index.md }
-- { path: /guide/yaml/index.md }
-- { path: /guide/java/index.md }
+- { path: /guide/blueprints/index.md }
+- { path: /guide/blueprints/java/index.md }
 - { path: /guide/ops/index.md, section_position: 2 }
 - { path: /guide/misc/index.md }
 {% endhighlight %}

http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/1330dcd3/contributing/site-structure.md
----------------------------------------------------------------------
diff --git a/contributing/site-structure.md b/contributing/site-structure.md
index c052e1c..0549d95 100644
--- a/contributing/site-structure.md
+++ b/contributing/site-structure.md
@@ -22,7 +22,7 @@ children:
 - { path: /guide/start/index.md }
 - { path: /guide/misc/download.md }
 - { path: /guide/concepts/index.md }
-- { path: /guide/yaml/index.md }
+- { path: /guide/blueprints/index.md }
 - { path: /guide/java/index.md }
 - { path: /guide/ops/index.md }
 - { path: /guide/misc/index.md }

http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/1330dcd3/guide/blueprints/advanced-example.md
----------------------------------------------------------------------
diff --git a/guide/blueprints/advanced-example.md b/guide/blueprints/advanced-example.md
new file mode 100644
index 0000000..6513191
--- /dev/null
+++ b/guide/blueprints/advanced-example.md
@@ -0,0 +1,283 @@
+---
+title: YAML Blueprint Advanced Example
+layout: website-normal
+---
+
+By this point you should be familiar with the fundamental concepts behind both Apache Brooklyn and YAML blueprints. This section of the documentation is intended to show a complete, advanced example of a YAML blueprint.
+
+The intention is that this example is used to learn the more in-depth concepts, and also to serve as a reference when writing your own blueprints. This page will first explain what the example application is and how to run it, then it will spotlight interesting features.
+
+
+### ELK Stack Example
+
+This example demonstrates the deployment of an ELK Stack (Elasticsearch, Logstash and Kibana), using the provided blueprint to deploy, install, run and manage all three. Briefly, the component parts are:
+
+* Elasticsearch: A clustered search engine
+* Logstash: Collects, parses and stores logs. For our example it will store logs in Elasticsearch
+* Kibana: A web front end to Elasticsearch
+
+We also deploy a simple webserver whose logs will be collected.
+
+* Tomcat 8: Web server whose logs will be stored in Elasticsearch by Logstash.
+
+For more about the ELK stack, please see the documentation [here](https://www.elastic.co/webinars/introduction-elk-stack).
+
+
+#### The Blueprints
+-----------
+
+There are four blueprints that make up this application. Each of them are used to add one or more catalog items to Brooklyn. You can find them below:
+
+* [Elasticsearch](https://github.com/brooklyncentral/brooklyn-elk/blob/master/brooklyn-elasticsearch-catalog.bom)
+* [Logstash](https://github.com/brooklyncentral/brooklyn-elk/blob/master/brooklyn-logstash-catalog.bom)
+* [Kibana](https://github.com/brooklyncentral/brooklyn-elk/blob/master/brooklyn-kibana-catalog.bom)
+* [ELK](https://github.com/brooklyncentral/brooklyn-elk/blob/master/brooklyn-elk-catalog.bom)
+
+#### Running the example
+First, add all four blueprints to the Brooklyn Catalog. This can be done by clicking the 'Catalog' tab, clicking the '+'
+ symbol and pasting the YAML. Once this is done, click the 'Application' tab, then the '+' button to bring up the add 
+application wizard. A new Catalog application will be available called 'ELK Stack'. Using the add application wizard, 
+you should be able to deploy an ELK stack to a location of your choosing.  Alternatively use the `br` Brooklyn
+command line tool and add the files with `br catalog add`.
+
+#### Exploring the example
+After the application has been deployed, you can ensure it is working as expected by checking the following:
+
+* There is a Kibana sensor called `main.uri`, the value of which points to the Kibana front end. You can explore this 
+front end, and observe the logs stored in Elasticsearch. Many Brooklyn applications have a `main.uri` set to point you 
+in the right direction.
+* You can also use the Elasticsearch REST API to explore further. The Elasticsearch Cluster entity has a `urls.http.list` 
+sensor. Using a host:port from that list you will be able to access the REST API. The following URL will give you the 
+state of the cluster `http://<host:port>/_cluster/health?pretty=true`. As you can see the `number_of_nodes` is 
+currently 2, indicating that the Elasticsearch nodes are communicating with each other.
+
+### Interesting Feature Spotlight
+We will mainly focus on the Elasticsearch blueprint, and will be clear when another blueprint is being discussed. This blueprint describes a cluster of Elasticsearch nodes. 
+
+#### Provisioning Properties
+Our Elasticsearch blueprint has a few requirements of the location in which it is run. Firstly, it must be run on an
+Ubuntu machine as the example has been written specifically for this OS. Secondly, two ports must opened to ensure
+that the entities can be accessed from the outside world. Both of these requirements are configured via 
+`provisioning.properties` as follows:
+
+~~~yaml
+brooklyn.config:
+  elasticsearch.http.port: 9220
+  elasticsearch.tcp.port: 9330
+  provisioning.properties:
+    osFamily: ubuntu
+    inboundPorts:
+    - $brooklyn:config("elasticsearch.http.port")
+    - $brooklyn:config("elasticsearch.tcp.port")
+~~~
+
+#### VanillaSoftwareProcess
+When composing a YAML blueprint, the VanillaSoftwareProcess is a very useful entity to be aware of. 
+A VanillaSoftwareProcess will instruct Brooklyn to provision an instance, and run a series of shell 
+commands to setup, run, monitor and teardown your program. The commands are specified as configuration 
+on the VanillaSoftwareProcess and there are several available. We will spotlight a few now. To simplify
+ this blueprint, we have specified ubuntu only installs so that our commands can be tailored to this 
+ system (e.g. use apt-get rather than yum).
+
+##### Customize Command
+The Customize Command is run after the application has been installed but before it is run. It is the perfect
+ place to create and amend config files. Please refer to the following section of the Elasticsearch blueprint:
+
+~~~yaml
+customize.command: |
+  sudo rm -fr sudo tee /etc/elasticsearch/elasticsearch.yml
+  echo discovery.zen.ping.multicast.enabled: false | sudo tee -a /etc/elasticsearch/elasticsearch.yml
+  echo discovery.zen.ping.unicast.enabled: true | sudo tee -a /etc/elasticsearch/elasticsearch.yml
+  echo discovery.zen.ping.unicast.hosts: ${URLS_WITH_BRACKETS} | sudo tee -a /etc/elasticsearch/elasticsearch.yml
+  echo http.port: ${ES_HTTP_PORT} | sudo tee -a /etc/elasticsearch/elasticsearch.yml
+  echo transport.tcp.port: ${ES_TCP_PORT} | sudo tee -a /etc/elasticsearch/elasticsearch.yml
+  echo network.host: ${IP_ADDRESS} | sudo tee -a /etc/elasticsearch/elasticsearch.yml
+~~~
+
+The purpose of this section is to create a YAML file with all of the required configuration. We use the YAML 
+literal style `|` indicator to write a multi line command. We start our series of commands by using the `rm` command to remove the 
+previous config file. We then use `echo` and `tee` to create the new config file and insert the config. Part 
+of the configuration is a list of all hosts that is set on the parent entity- this is done by using a combination
+ of the `component` and  `attributeWhenReady` DSL commands. More on how this is generated later.
+
+##### Check running
+After an app is installed and run, this command is scheduled to run regularly and used to populate the `service.isUp` 
+sensor. If this command is not specified, or returns an exit code of anything other than zero, then Brooklyn will 
+assume that your entity has failed and will display the fire status symbol. Please refer to the following section 
+of the Elasticsearch blueprint:
+
+~~~yaml
+checkRunning.command: sudo systemctl status kibana.service
+~~~
+
+There are many different ways to implement this command. For this example, we are simply using the systemctl status 
+of the appropriate service.
+
+#### Enrichers
+
+##### Elasticsearch URLS
+To ensure that all Elasticsearch nodes can communicate with each other they need to be configured with the TCP URL 
+of all other nodes. Similarly, the Logstash instances need to be configured with all the HTTP URLs of the Elasticsearch 
+nodes. The mechanism for doing this is the same, and involves using Transformers, Aggregators and Joiners, as follows:
+
+~~~yaml
+brooklyn.enrichers:
+  - type: org.apache.brooklyn.enricher.stock.Transformer
+    brooklyn.config:
+      enricher.sourceSensor: $brooklyn:sensor("host.subnet.address")
+      enricher.targetSensor: $brooklyn:sensor("url.tcp")
+      enricher.targetValue: $brooklyn:formatString("%s:%s", $brooklyn:attributeWhenReady("host.subnet.address"), $brooklyn:config("elasticsearch.tcp.port"))
+~~~
+
+In this example, we take the host.subnet.address and append the TCP port, outputting the result as `url.tcp`. 
+After this has been done, we now need to collect all the URLs into a list in the Cluster entity, as follows:
+
+~~~yaml
+brooklyn.enrichers:
+  - type: org.apache.brooklyn.enricher.stock.Aggregator
+    brooklyn.config:
+      enricher.sourceSensor: $brooklyn:sensor("url.tcp")
+      enricher.targetSensor: $brooklyn:sensor("urls.tcp.list")
+      enricher.aggregating.fromMembers: true
+
+~~~
+
+In the preceding example, we aggregated all of the TCP URLs generated in the early example. 
+These are then stored in a sensor called `urls.tcp.list`. This list is then joined together into one long string:
+
+~~~yaml
+- type: org.apache.brooklyn.enricher.stock.Joiner
+  brooklyn.config:
+    enricher.sourceSensor: $brooklyn:sensor("urls.tcp.list")
+    enricher.targetSensor: $brooklyn:sensor("urls.tcp.string")
+    uniqueTag: urls.quoted.string
+~~~
+
+Finally, the string has brackets added to the start and end:
+
+~~~yaml
+- type: org.apache.brooklyn.enricher.stock.Transformer
+  brooklyn.config:
+    enricher.sourceSensor: $brooklyn:sensor("urls.tcp.string")
+    enricher.targetSensor: $brooklyn:sensor("urls.tcp.withBrackets")
+    enricher.targetValue: $brooklyn:formatString("[%s]", $brooklyn:attributeWhenReady("urls.tcp.string"))
+~~~
+
+The resulting sensor will be called `urls.tcp.withBrackets` and will be used by all Elasticsearch nodes during setup.
+
+##### Kibana URL
+Kibana also needs to be configured such that it can access the Elasticsearch cluster. However, Kibana can
+ only be configured to point at one Elasticsearch instance. To enable this, we use another enricher in the 
+ cluster to select the first URL from the list, as follows:
+
+~~~yaml
+- type: org.apache.brooklyn.enricher.stock.Aggregator
+  brooklyn.config:
+    enricher.sourceSensor: $brooklyn:sensor("host.subnet.address")
+    enricher.targetSensor: $brooklyn:sensor("host.address.first")
+    enricher.aggregating.fromMembers: true
+    enricher.transformation:
+     $brooklyn:object:
+       type: "org.apache.brooklyn.util.collections.CollectionFunctionals$FirstElementFunction"
+~~~
+
+Similar to the above Aggregator, this Aggregator collects all the URLs from the members of the cluster. 
+However, this Aggregator specifies a transformation. In this instance a transformation is a Java class that 
+implements a Guava Function `<? super Collection<?>, ?>>`, i.e. a function that takes in a collection and 
+returns something. In this case we specify the FirstElementFunction from the CollectionFunctionals to ensure 
+that we only get the first member of the URL list.
+
+#### Latches
+In the ELK blueprint, there is a good example of a latch. Latches are used to force an entity to wait until 
+certain conditions are met before continuing. For example:
+
+~~~yaml
+- type: kibana-standalone
+  id: kibana
+  name: Kibana Server
+  customize.latch: $brooklyn:component("es").attributeWhenReady("service.isUp")
+~~~
+
+This latch is used to stop Kibana customizing until the Elasticsearch cluster is up. We do this to ensure 
+that the URL sensors have been setup, so that they can be passed into Kibana during the customization phase.
+
+Latches can also be used to control how many entities can execute the same step at any given moment. When
+a latch is given the value of a `MaxConcurrencySensor` it will unblock execution only when there are
+available "slots" to execute (think of it as a semaphore). For example to let a single entity execute the
+launch step of the start effector:
+
+~~~yaml
+services:
+- type: cluster
+
+  brooklyn.initializers:
+  - type: org.apache.brooklyn.core.sensor.MaxConcurrencySensor
+    brooklyn.config:
+      name: single-executor
+      latch.concurrency.max: 1
+
+  brooklyn.config: 
+    initialSize: 10
+    memberSpec:
+      $brooklyn:entitySpec:
+        type: vanilla-bash-server
+        brooklyn.config:
+          launch.command: sleep 2
+          checkRunning.command: true
+          launch.latch: $brooklyn:parent().attributeWhenReady("single-executor")
+~~~
+
+It's important to note that the above setup is not reentrant. This means that users should be careful to
+avoid deadlocks. For example having a start and launch latches against the `single-executor` from above.
+The launch latch will block forever since the start latch already would've acquired the free slot.
+
+#### Child entities
+The ELK blueprint also contains a good example of a child entity.
+
+~~~yaml
+- type: org.apache.brooklyn.entity.webapp.tomcat.Tomcat8Server
+  brooklyn.config:
+    children.startable.mode: background_late
+  ...
+  brooklyn.children:
+  - type: logstash-child
+~~~
+
+In this example, a logstash-child is started as a child of the parent Tomcat server. The Tomcat server needs 
+to be configured with a `children.startable.mode` to inform Brooklyn when to bring up the child. In this case
+ we have selected background so that the child is disassociated from the parent entity, and late to specify that
+  the parent entity should start before we start the child.
+
+The example also shows how to configure Logstash inputs and filters, if necessary, for a particular application, 
+in this case Tomcat.
+
+~~~yaml
+- type: logstash-child
+  name: Logstash
+  brooklyn.config:
+    logstash.elasticsearch.hosts: $brooklyn:entity("es").attributeWhenReady("urls.http.withBrackets")
+    logstash.config.input:
+      $brooklyn:formatString:
+      - |
+        input {
+          file {
+            path => "%s/logs/localhost_access_log.*"
+            start_position => "beginning"
+          }
+        }
+      - $brooklyn:entity("tomcat").attributeWhenReady("run.dir")
+    logstash.config.filter: |
+      filter {
+        grok {
+          match => { "message" => "%{COMBINEDAPACHELOG}" }
+        }
+        date {
+          match => [ "timestamp" , "dd/MMM/yyyy:HH:mm:ss Z" ]
+        }
+      }
+~~~
+
+Configuring an appropriate visualisation on the Kibana server (access it via the URL on the summary tab for 
+that entity) allows a dashboard to be created such as
+
+![kibana dashboard](logstash-snapshot.png)
\ No newline at end of file

http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/1330dcd3/guide/blueprints/ansible/about-ansible.md
----------------------------------------------------------------------
diff --git a/guide/blueprints/ansible/about-ansible.md b/guide/blueprints/ansible/about-ansible.md
new file mode 100644
index 0000000..9886993
--- /dev/null
+++ b/guide/blueprints/ansible/about-ansible.md
@@ -0,0 +1,34 @@
+---
+title: About Ansible
+title_in_menu: About Ansible
+layout: website-normal
+---
+
+## What you need to know about Ansible
+
+[Ansible](http://docs.ansible.com/ansible/) is a deployment tool designed to work in an agent-less manner, normally 
+performing its operations on a node over SSH from some central administrating node.  Brooklyn can deploy software 
+via Ansible on one of its managed nodes, by first installing Ansible on the node itself and then using Ansible to deploy
+the required software.
+
+A 'Playbook' in Ansible is a specification of the configuration and deployment of a system. 
+Playbooks are expressed in YAML format, and contain a number of 'plays', which are in turn lists of tasks to carry out
+to achieve the desired configuration on the system.  'Roles' are pre-written modular collections of tasks, and can
+be included in playbooks.
+
+Ansible comes with built-in support for many software systems, and has a community repository of roles exists at 
+[https://galaxy.ansible.com](https://galaxy.ansible.com).
+
+
+### How Brooklyn interacts with Ansible
+
+Brooklyn provides a Ansible entity type. An entity of this type can be specified in a blueprint in order to provision the 
+node through Ansible. The Ansible entity will download Ansible and install it on the node. The entity type supports the 
+configuration of Ansible playbooks to download, or write inline in the blueprint, for simple playbooks.
+Configuration values for the playbooks can be supplied in the blueprint.  
+
+Brooklyn will deploy the software specified in the playbook when the entity starts.  In addition, an effector is 
+provided on the entity that supports general purpose Ansible instructions.
+
+
+

http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/1330dcd3/guide/blueprints/ansible/creating-ansible-blueprints.md
----------------------------------------------------------------------
diff --git a/guide/blueprints/ansible/creating-ansible-blueprints.md b/guide/blueprints/ansible/creating-ansible-blueprints.md
new file mode 100644
index 0000000..845f542
--- /dev/null
+++ b/guide/blueprints/ansible/creating-ansible-blueprints.md
@@ -0,0 +1,213 @@
+---
+title: Creating Blueprints with Ansible
+title_in_menu: Creating Blueprints with Ansible
+layout: website-normal
+---
+
+To write a blueprint to use Ansible with Brooklyn it will help to have a degree of familiarity with Ansible itself. In the 
+sections below, when the Brooklyn configuration is described, the underlying Ansible operation is also noted briefly, for 
+clarity for readers who know Ansible.
+
+To manage a node with Ansible, create a blueprint containing a service of type `org.apache.brooklyn.entity.cm.ansible.AnsibleEntity`
+and define and minimum the `playbook` value, and one or other of `playbook.url` or `playbook.yaml`. You must also define
+the `service.name` that will be tested in order to determine if the entity is running successfully.
+
+For example:
+
+    name: myweb
+    location: ...
+    services:
+      - type: org.apache.brooklyn.entity.cm.ansible.AnsibleEntity
+        id: apache
+        name: apache
+        service.name: apache2
+        playbook: apache-playbook
+        playbook.url: http://myhost/projectX/apache-playbook.yaml
+
+    
+This example specifies that Brooklyn should use Ansible to download the playbook from the repository on
+"myhost". The playbook contains the instructions to install the Apache web server. To start the 
+entity, Brooklyn will use Ansible's "ansible-playbook" command to run the playbook, which will bring up the web server.
+
+
+### Lifecycle of AnsibleEntity
+
+The start effector applies the playbook and verifies that it has started the software correctly by checking the service
+defined as `service.name` is running.  This can be customized, see `ansible.service.start` configuration below.
+
+The stop effector will stop the service `service.name`.  Again, this can be customized, with `ansible.service.stop`. 
+
+The restart effector will apply stop and then start.
+
+
+### Configuration of AnsibleEntity
+
+The `playbook` configuration key names the top level list of states that will be applied using Ansible.  
+ This configuration key is mandatory.
+
+The playbook must be defined using one or other (both together are not permitted) of  `playbook.yaml` or `playbook.url`.
+The former allows the playbook content to be defined inline within the blueprint, using the normal YAML format of an 
+Ansible playbook.  The latter obtains the playbook from an external URL.
+
+The `ansible.service.start` configuration key allows the blueprint author to override the command used by default to 
+verify that the service `service.name` is running (or to start it, if the playbook did not specify it should run by
+default).  The default value is:
+
+    sudo ansible localhost -c local -m service -a "name=<service.name> state=started"
+
+Similarly the `ansible.service.stop` configuration key permits override of the instruction used to get Ansible to stop the
+service, by default
+
+    sudo ansible localhost -c local -m service -a "name=<service.name> state=stopped"
+
+The `ansible.service.checkPort` configuration key allows the user to override the mechanism used to check that the 
+service `service.name` is operating. By default Brooklyn checks that the service process is running. However, if the
+ service is one that listens on a particular port, this configuration key allows the blueprint author to instruct
+ Brooklyn to check that the port is being listened on, using the Ansible `wait_for` module. The value of the key is 
+ the port number to check.
+
+The `ansible.vars` configuration key allows the blueprint author to provide entity-specific values for configuration
+variables used in the playbook, so that one playbook can be used by multiple entities, each customized appropriately.
+The value of `ansible.vars` is an arbitrary block of YAML configuration that will be applied to the playbook using 
+Ansible's `--extra-vars` mechanism, as described in the
+Ansible [documentation](http://docs.ansible.com/ansible/playbooks_variables.html#passing-variables-on-the-command-line).
+For example, if the playbook in the example above contained configuration such as:
+ 
+    - hosts: all
+      vars:
+        http_port: 80
+        max_clients: 200
+      remote_user: root
+      tasks:
+      ...
+ 
+ then to change the port that the webserver in the example above runs on, it would be possible to define the following 
+ in the blueprint:
+ 
+    name: myweb
+    location: ...
+    services:
+      - type: org.apache.brooklyn.entity.cm.ansible.AnsibleEntity
+        id: apache
+        name: apache
+        service.name: apache2
+        playbook: apache-playbook
+        playbook.url: http://myhost/projectX/apache-playbook.yaml
+        ansible.vars:
+            http_port: 8080
+
+
+### ansibleCall Effector
+
+The Ansible entity includes a general purpose Ansible effector, `ansibleCommand`, which permits execution of Ansible 
+commands via `ansible`.  It contains a two parameters:
+1. `module` specifies the Ansible module to invoke.  The default is "command".
+2. `args` specifies the argument data for the Ansible module.  For example, to download an additional file for the 
+webserver, the command could be invoked with the following arguments. (For convenience this
+example uses the client CLI, "br", but the effector could be invoked by any applicable means, e.g. via the web UI 
+or REST API.)
+
+    $ br app myweb ent apache effector ansibleCommand invoke \
+       -P module=shell -P args='curl http://myhost:8080/additional.html > /var/www/html/additional.html'
+
+### Roles and Multi-Playbook Installations
+
+There is no specific configuration in AnsibleEntity for Ansible [Roles](http://docs.ansible.com/ansible/playbooks_roles.html),
+ or to install multiple playbooks. However, the installation of roles or multiple playbooks can be carried out first 
+ by taking advantage of Brooklyn's SameServerEntity. The installation step can be applied in one child of the same server
+ entity, while the AnsibleEntity can operate under the second child. It will typically be necessary to delay the start
+ of the AnsibleEntity until the first child has carried out whatever preparation is required. The examples below
+ illustrate the concept (with just one playbook, for brevity).
+ 
+ One way to a achieve this, as with any Brooklyn entity, is to use the idiom of making it a child of a BasicApplication 
+ with a start latch waiting on the first child, such as in the following example, which installs the standalone Tomcat example,
+ with its playbook and roles, from the "Ansible Examples" Github site. 
+ (Note, this is designed for installation on Redhat/Centos 6.)
+ The first child in the SameServerEntity downloads
+ and unpacks the Ansible examples. This might also install standalone Ansible roles, or whatever other resources the
+ AnsibleEntity might require.  The second child uses `attributeWhenReady` to block until the first is ready, before 
+ starting the AnsibleEntity to apply the desired playbook.
+ 
+
+    name: multi
+    location:
+      red1
+    services:
+    - serviceType: brooklyn.entity.basic.SameServerEntity
+      name: Entities
+      brooklyn.children:
+      
+      - serviceType: org.apache.brooklyn.entity.cm.ansible.AnsibleEntity
+        id: bootstrap
+        service.name: crond
+        playbook: bootstrap
+        playbook.yaml: |
+            ---
+            - hosts: localhost
+              tasks:
+              - shell: printf "[tomcat-servers]\nlocalhost ansible_connection=local\n" >> /etc/ansible/hosts
+              - file: path=/etc/ansible/playbooks state=directory mode=0755
+              - get_url: url=https://github.com/ansible/ansible-examples/archive/master.zip dest=/tmp/master.zip mode=0440
+              - command: unzip -o -d /etc/ansible/playbooks /tmp/master.zip
+    
+      - serviceType: org.apache.brooklyn.entity.stock.BasicApplication
+        start.latch: $brooklyn:entity("bootstrap").attributeWhenReady("service.isUp")
+        brooklyn.children:
+        - type: org.apache.brooklyn.entity.cm.ansible.AnsibleEntity
+          name: test
+          service.name: tomcat
+          playbook: tomcat
+          playbook.yaml: |
+              ---
+              - hosts: localhost
+              - include: /etc/ansible/playbooks/ansible-examples-master/tomcat-standalone/site.yml
+                vars:
+                    http_port: 8080
+                    https_port: 8443
+                    admin_username: admin
+                    admin_password: secret
+
+ 
+An alternative to the above is to use Ansible itself to do the waiting, as in the variant below, which uses AnsibleEntity
+itself in the first SameServerEntity child, to install the required material.  In the second child, which is simply an
+AnsibleEntity rather than a BasicApplication, Ansible's `wait_for` operation is used as the first step in the playbook, 
+to block the remaining steps in its playbook until the first is complete.
+
+    name: multi
+    location:
+      red1
+    services:
+    - serviceType: brooklyn.entity.basic.SameServerEntity
+      name: Entities
+      brooklyn.children:
+      
+      - serviceType: org.apache.brooklyn.entity.cm.ansible.AnsibleEntity
+        id: bootstrap
+        service.name: crond
+        playbook: bootstrap
+        playbook.yaml: |
+            ---
+            - hosts: localhost
+              tasks:
+              - command: rm -f /tmp/bootstrap.done
+              - shell: printf "[tomcat-servers]\nlocalhost ansible_connection=local\n" >> /etc/ansible/hosts
+              - file: path=/etc/ansible/playbooks state=directory mode=0755
+              - get_url: url=https://github.com/ansible/ansible-examples/archive/master.zip dest=/tmp/master.zip mode=0440
+              - command: unzip -o -d /etc/ansible/playbooks /tmp/master.zip
+              - file: path=/tmp/bootstrap.done state=touch
+    
+      - serviceType: org.apache.brooklyn.entity.cm.ansible.AnsibleEntity
+        name: test
+        service.name: tomcat
+        playbook: tomcat
+        playbook.yaml: |
+            ---
+            - tasks:
+              - wait_for: path=/tmp/bootstrap.done
+              include: /etc/ansible/playbooks/ansible-examples-master/tomcat-standalone/site.yml
+              vars:
+                http_port: 8080
+                https_port: 8443
+                admin_username: admin
+                admin_password: secret
+

http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/1330dcd3/guide/blueprints/ansible/index.md
----------------------------------------------------------------------
diff --git a/guide/blueprints/ansible/index.md b/guide/blueprints/ansible/index.md
new file mode 100644
index 0000000..a2376d1
--- /dev/null
+++ b/guide/blueprints/ansible/index.md
@@ -0,0 +1,16 @@
+---
+title: Ansible in YAML Blueprints
+layout: website-normal
+children:
+- about-ansible.md
+- creating-ansible-blueprints.md
+---
+
+This guide describes how Brooklyn entities can be created using the Ansible infrastructure management tool
+ ([ansible.com](http://ansible.com)).
+At present Brooklyn provides basic support for Ansible, operating in a 'masterless' mode. 
+Comments on this support and suggestions for further development are welcome.
+
+This guide assumes you are familiar with the basics of [creating YAML blueprints](../).
+
+{% include list-children.html %}

http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/1330dcd3/guide/blueprints/blueprinting-tips.md
----------------------------------------------------------------------
diff --git a/guide/blueprints/blueprinting-tips.md b/guide/blueprints/blueprinting-tips.md
new file mode 100644
index 0000000..9712fef
--- /dev/null
+++ b/guide/blueprints/blueprinting-tips.md
@@ -0,0 +1,183 @@
+---
+title: Blueprinting Tips
+layout: website-normal
+---
+
+## YAML Recommended
+
+The recommended way to write a blueprint is as a YAML file. This is true both for building
+an application out of existing blueprints, and for building new integrations.
+
+The use of Java is reserved for those use-cases where the provisioning or configuration logic 
+is very complicated.
+
+
+## Be Familiar with Brooklyn
+
+Be familiar with the stock entities available in Brooklyn. For example, prove you understand  
+the concepts by making a deployment of a cluster of Tomcat servers before you begin writing your 
+own blueprints.
+
+
+## Ask For Help
+
+Ask for help early. The community is keen to help, and also keen to find out what people find 
+hard and how people use the product. Such feedback is invaluable for improving future versions.
+
+
+## Faster Dev-Test
+
+Writing a blueprint is most efficient and simple when testing is fast, and when testing is
+done incrementally as features of the blueprint are written.
+
+The slowest stages of deploying a blueprint are usually VM provisioning and downloading/installing
+of artifacts (e.g. RPMs, zip files, etc).
+
+Options for speeding up provisioning include those below.
+
+#### Deploying to Bring Your Own Nodes (BYON)
+
+A [BYON location]({{ site.path.guide }}/locations/#byon) can be defined, which avoids the time 
+required to provision VMs. This is fast, but has the downside that artifacts installed during a 
+previous run can interfere with subsequent runs.
+
+A variant of this is to [use Vagrant]({{ site.path.guide }}/start/running.html) (e.g. with VirtualBox) 
+to create VMs on your local machine, and to use these as the target for a BYON location.
+
+These VMs should mirror the target environment as much as possible.
+
+
+#### Deploying to the "localhost" location
+
+This is fast and simple, but has some obvious downsides:
+
+* Artifacts are installed directly on your desktop/server.
+
+* The artifacts installed during previous runs can interfere with subsequent runs.
+
+* Some entities require `sudo` rights, which must be granted to the user running Brooklyn.
+
+
+#### Deploying to Clocker
+
+Docker containers provide a convenient way to test blueprints (and also to run blueprints in
+production!).
+
+The [Clocker project](http://www.clocker.io) allows the simple setup of Docker Engine(s), and for Docker
+containers to be used instead of VMs. For testing, this allows each run to start from a fresh 
+container (i.e. no install artifacts from previous runs), while taking advantage of the speed
+of starting containers.
+
+
+#### Local Repository of Install Artifacts
+
+To avoid re-downloading install artifacts on every run, these can be saved to `~/.brooklyn/repository/`.
+The file structure is a sub-directory with the entity's simple name, then a sub-directory with the
+version number, and then the files to be downloaded. For example, 
+`~/.brooklyn/repository/TomcatServer/7.0.56/apache-tomcat-7.0.56.tar.gz`.
+
+If possible, synchronise this directory with your test VMs. 
+
+
+#### Re-install on BYON
+
+If using BYON or localhost, the install artifacts will by default be installed to a directory like
+`/tmp/brooklyn-myname/installs/`. If install completed successfully, then the install stage will 
+be subsequently skipped (a marker file being used to indicate completion). To re-test the install 
+phase, delete the install directory (e.g. delete `/tmp/brooklyn-myname/installs/TomcatServer_7.0.56/`).
+
+Where installation used something like `apt-get install` or `yum install`, then re-testing the
+install phase will require uninstalling these artifacts manually.
+
+
+## Monitoring and Managing Applications
+
+Think about what it really means for an application to be running. The out-of-the-box default 
+for a software process is the lowest common denominator: that the process is still running. 
+Consider checking that the app responds over HTTP etc.
+
+If you have control of the app code, then consider adding an explicit health check URL that
+does more than basic connectivity tests. For example, can it reach the database, message broker,
+and other components that it will need for different operations.
+
+
+## Writing Composite Blueprints
+
+Write everything in discrete chunks that can be composed into larger pieces. Do not write a single 
+mega-blueprint. For example, ensure each component is added to the catalog independently, along 
+with a blueprint for the composite app.
+
+Experiment with lots of small blueprints to test independent areas before combining them into the 
+real thing.
+
+
+## Writing Entity Tests
+
+Use the [test framework]({{ site.path.guide }}/blueprints/test/) to write test cases. This will make 
+automated (regression) testing easier, and will allow others to easily confirm that the entity 
+works in their environment.
+
+If using Maven/Gradle then use the [Brooklyn Maven plugin](https://github.com/brooklyncentral/brooklyn-maven-plugin) 
+to test blueprints at build time.
+
+
+## Custom Entity Development
+
+If writing a custom integration, the following recommendations may be useful:
+
+* Always be comfortable installing and running the process yourself before attempting to automate 
+  it.
+
+* For the software to be installed, use its Installation and Admin guides to ensure best practices
+  are being followed. Use blogs and advice from experts, when available.
+
+* Where there is a choice of installation approaches, use the approach that is most appropriate for
+  production use-cases (even if this is harder to test on locahost). For example, 
+  prefer the use of RPMs versus unpacking zip files, and prefer the use of services versus invoking
+  a `bin/start` script.
+
+* Ensure every step is scriptable (e.g. manual install does not involve using a text editor to 
+  modify configuration files, or clicking on things in a web-console).
+
+* Write scripts (or Chef recipes, or Puppet manifests, etc), and test these by executing manually. 
+  Only once these work in isolation, add them to the entity blueprint.
+
+* Externalise the configuration where appropriate. For example, if there is a configuration file
+  then include a config key for the URL of the configuration file to use. Consider using FreeMarker
+  templating for such configuration files.
+
+* Focus on a single OS distro/version first, and clearly document these assumptions.
+
+* Breakdown the integration into separate components, where possible (and thus develop/test them separately). 
+  For example, if deploying a MongoDB cluster then first focus on single-node MongoDB, and then make that
+  configurable and composable for a cluster.
+
+* Where appropriate, share the new entity with the Brooklyn community so that it can be reviewed, 
+  tested and improved by others in the community!
+
+
+## Cloud Portability
+
+You get a lot of support out-of-the-box for deploying blueprints to different clouds. The points 
+below may also be of help:
+
+* Test (and regression test) on each target cloud.
+
+* Be aware that images on different clouds can be very different. For example, two CentOS 6.6 VMs 
+  might have different pre-installed libraries, different default iptables or SE Linux settings,
+  different repos, different sudo configuration, etc.
+
+* Different clouds handle private and public IPs differently. One must be careful about which 
+  address to advertise to for use by other entities.
+
+* VMs on some clouds may not have a well-configured hostname (e.g. `ping $(hostname)` can fail).
+
+* VMs in different clouds have a different number of NICs. This is important when choosing whether
+  to listen on 0.0.0.0 or on a specific NIC.
+
+
+## Investigating Errors
+
+ALWAYS keep logs when there is an error.
+
+See the [Troubleshooting]({{ site.path.guide }}/ops/troubleshooting/) guide for more information. 

http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/1330dcd3/guide/blueprints/catalog/images/add-to-catalog.png
----------------------------------------------------------------------
diff --git a/guide/blueprints/catalog/images/add-to-catalog.png b/guide/blueprints/catalog/images/add-to-catalog.png
new file mode 100644
index 0000000..0565e7e
Binary files /dev/null and b/guide/blueprints/catalog/images/add-to-catalog.png differ

http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/1330dcd3/guide/blueprints/catalog/index.md
----------------------------------------------------------------------
diff --git a/guide/blueprints/catalog/index.md b/guide/blueprints/catalog/index.md
new file mode 100644
index 0000000..d4605b0
--- /dev/null
+++ b/guide/blueprints/catalog/index.md
@@ -0,0 +1,400 @@
+---
+title: Catalog
+layout: website-normal
+children:
+- { section: General YAML Schema }
+- { section: Catalog Metadata }
+- { section: Catalog YAML Examples }
+- { section: Templates and the Add-Application Wizard, title: Templates }
+- { section: Adding to the Catalog, title: Adding and Deleting } 
+- { section: Versioning } 
+- { section: brooklyn-server-command-line-arguments, title: CLI Options }
+ 
+---
+
+Apache Brooklyn provides a **catalog**, which is a persisted collection of versioned blueprints 
+and other resources. A set of blueprints is loaded from the `default.catalog.bom` in the Brooklyn 
+folder by default and additional ones can be added through the web console or CLI.  Blueprints in 
+the catalog can be deployed directly, via the Brooklyn CLI or the web console, or referenced in 
+other blueprints using their `id`.
+
+ 
+### Catalog Items YAML Syntax
+
+An item or items to be added to the catalog is defined by a YAML file,
+specifying the catalog metadata for the items and the actual blueprint or resource definition.
+
+
+#### General YAML Schema
+
+Catalog items can be defined using the general structure below:
+
+~~~ yaml
+brooklyn.catalog:
+  <catalog-metadata>
+  items:
+  - <additional-catalog-metadata>
+    item:
+      <blueprint-or-resource-definition>
+  - <additional-catalog-metadata>
+    item:
+      <blueprint-or-resource-definition>
+~~~ 
+ 
+Alternatively, a single catalog item can be defined using the following general structure:
+
+~~~ yaml
+brooklyn.catalog:
+  <catalog-metadata>
+  item:
+    <blueprint-or-resource-definition>
+~~~ 
+
+For example, the YAML below adds to the catalog a Tomcat entity with some additional default 
+configuration:
+
+~~~ yaml
+brooklyn.catalog:
+  items:
+  - id: tomcat-server
+    version: "1.0.0"
+    itemType: entity
+    item:
+      type: org.apache.brooklyn.entity.webapp.tomcat.Tomcat8Server
+      brooklyn.config:
+        webapp.enabledProtocols: https
+        httpsSsl:
+          url: classpath://org/apache/brooklyn/entity/webapp/sample-java-keystore.jks
+          alias: myname
+          password: mypass
+~~~ 
+
+
+#### Catalog Metadata
+
+Catalog metadata fields supply the additional information required in order to register an item in the catalog. 
+These fields can be supplied as `key: value` entries 
+where either the `<catalog-metadata>` or `<additional-catalog-metadata>` placeholders are,
+with the latter overriding the former unless otherwise specified below.
+
+The following metadata is *required* for all items:
+
+- `id`: a human-friendly unique identifier for how this catalog item will be referenced from blueprints
+- `version`: multiple versions of a blueprint can be installed and used simultaneously;
+  this field disambiguates between blueprints of the same `id`.
+  Note that this is typically *not* the version of the software being installed,
+  but rather the version of the blueprint. For more information on versioning, see below.
+  (Also note YAML treats numbers differently to Strings. Explicit quotes are recommended, to avoid 
+  `1.10` being interpretted as the number `1.1`.)
+- `itemType`: the type of the item being defined. The supported item types are:
+  - `entity`
+  - `template`
+  - `policy`
+  - `location`
+
+To reference a catalog item in another blueprint, simply reference its ID and optionally its version number.
+For instance, if we've added an item with metadata `{ id: datastore, version: "1.0" }` (such as the example below),
+we could refer to it in another blueprint with: 
+
+~~~ yaml
+services:
+- type: datastore:1.0
+~~~ 
+
+In addition to the above fields, exactly **one** of the following is also required:
+
+- `item`: the YAML for an entity, or policy, or location specification 
+  (a map containing `type` and optional `brooklyn.config`). For a "template" item, it
+  should be a map containing `services` (i.e. the usual YAML format for a full application
+  blueprint). **Or**
+- `items`: a list of catalog items, where each entry in the map follows the same schema as
+  the `brooklyn.catalog` value, and the keys in these map override any metadata specified as
+  a sibling of this `items` key (or, in the case of `brooklyn.libraries` they add to the list);
+  if there are references between items, then order is important:
+  `items` are processed in order, depth-first, and forward references are not supported. Entries
+  can be URL to another catalog file to include, inheriting the metadata from the current hierarchy.
+  Libraries defined so far in the metadata will be used to load classpath entries. For example:
+
+~~~ yaml
+brooklyn.catalog:
+  brooklyn.libraries:
+  - http://some.server.or.other/path/my.jar
+  items:
+  - classpath://my-catalog-entries-inside-jar.bom
+  - some-property: value
+    include: classpath://more-catalog-entries-inside-jar.bom
+  - id: use-from-my-catalog
+    version: "1.0.0"
+    itemType: entity
+    item:
+      type: some-type-defined-in-my-catalog-entries
+      brooklyn.config:
+        some.config: "some value"
+~~~
+
+The following optional catalog metadata is supported:
+  
+- `name`: a nicely formatted display name for the item, used when presenting it in a GUI.
+- `description`: supplies an extended textual description for the item.
+- `iconUrl`: points to an icon for the item, used when presenting it in a GUI.
+  The URL prefix `classpath` is supported but these URLs may *not* refer to resources in any OSGi 
+  bundle in the `brooklyn.libraries` section (to prevent requiring all OSGi bundles to be loaded 
+  at launch). Icons are instead typically installed either at the web server from which the OSGi 
+  bundles or catalog items are supplied or in the `conf` folder of the Brooklyn distro.
+- `scanJavaAnnotations` [experimental; deprecated]: if provided (as `true`), this will scan any 
+  locally provided library URLs for types annotated `@Catalog` and extract metadata to include 
+  them as catalog items. If no libraries are specified this will scan the default classpath.
+  This feature will likely be removed.
+  Also note that external OSGi dependencies are not supported 
+  and other metadata (such as versions, etc) may not be applied.
+- `brooklyn.libraries`: a list of pointers to OSGi bundles required for the catalog item.
+  This can be omitted if blueprints are pure YAML and everything required is included in the classpath and catalog.
+  Where custom Java code or bundled resources is needed, however, OSGi JARs supply
+  a convenient packaging format and a very powerful versioning format.
+  Libraries should be supplied in the form 
+  `brooklyn.libraries: [ "http://...", "http://..." ]`, 
+  or as
+  `brooklyn.libraries: [ { name: symbolic-name, version: "1.0", url: http://... }, ... ]` if `symbolic-name:1.0` 
+  might already be installed from a different URL and you want to skip the download.
+  Note that these URLs should point at immutable OSGi bundles;
+  if the contents at any of these URLs changes, the behaviour of the blueprint may change 
+  whenever a bundle is reloaded in a Brooklyn server,
+  and if entities have been deployed against that version, their behavior may change in subtle or potentially incompatible ways.
+  To avoid this situation, it is highly recommended to use OSGi version stamps as part of the URL.
+- `include`: A URL to another catalog file to include, inheriting the meta from the current hierarchy.
+  Libraries defined so far in the meta will be used to load classpath entries. `include` must be used
+  when you have sibling properties. If it's the only property it may be skipped by having the URL as the
+  value - see `items` example above.
+
+
+#### Catalog YAML Examples
+
+##### A Simple Example
+
+The following example installs the `RiakNode` entity, making it also available as an application template,
+with a nice display name, description, and icon.
+It can be referred in other blueprints to as `datastore:1.0`,
+and its implementation will be the Java class `org.apache.brooklyn.entity.nosql.riak.RiakNode` included with Brooklyn.
+
+~~~ yaml
+brooklyn.catalog:
+  id: datastore
+  version: "1.0"
+  itemType: template
+  iconUrl: classpath://org/apache/brooklyn/entity/nosql/riak/riak.png
+  name: Datastore (Riak)
+  description: Riak is an open-source NoSQL key-value data store.
+  item:
+    services:
+    - type: org.apache.brooklyn.entity.nosql.riak.RiakNode
+      name: Riak Node
+~~~ 
+
+
+##### Multiple Items
+
+This YAML will install three items:
+
+~~~ yaml
+brooklyn.catalog:
+  version: "1.1"
+  iconUrl: classpath://org/apache/brooklyn/entity/nosql/riak/riak.png
+  description: Riak is an open-source NoSQL key-value data store.
+  items:
+    - id: riak-node
+      itemType: entity
+      item:
+        type: org.apache.brooklyn.entity.nosql.riak.RiakNode
+        name: Riak Node
+    - id: riak-cluster
+      itemType: entity
+      item:
+        type: org.apache.brooklyn.entity.nosql.riak.RiakCluster
+        name: Riak Cluster
+    - id: datastore
+      name: Datastore (Riak Cluster)
+      itemType: template
+      item:
+        services:
+        - type: riak-cluster
+          brooklyn.config:
+            # the default size is 3 but this can be changed to suit your requirements
+            initial.size: 3
+            provisioning.properties:
+              # you can also define machine specs
+              minRam: 8gb
+~~~ 
+
+The items this will add to the catalog are:
+
+- `riak-node`, as before, but with a different name
+- `riak-cluster` as a convenience short name for the `org.apache.brooklyn.entity.nosql.riak.RiakCluster` class
+- `datastore`, now pointing at the `riak-cluster` blueprint, in SoftLayer and with the given size and machine spec, 
+  as the default implementation for anyone
+  requesting a `datastore` (and if installed atop the previous example, new references to `datastore` 
+  will access this version because it is a higher number);
+  because it is a template, users will have the opportunity to edit the YAML (see below).
+  (This must be supplied after `riak-cluster`, because it refers to `riak-cluster`.)
+
+
+#### Locations in the Catalog
+
+In addition to blueprints, locations can be added to the Apache Brooklyn catalog. The example below shows a location for the vagrant configuration used in the [getting started guide]({{ site.path.guide }}/start/blueprints.html), formatted as a catalog entry.
+
+~~~ yaml
+brooklyn.catalog:
+  id: vagrant
+  version: "1.0"
+  itemType: location
+  name: Vagrant getting started location
+  item:
+    type: byon
+    brooklyn.config:
+      user: vagrant
+      password: vagrant
+      hosts:
+        - 10.10.10.101
+        - 10.10.10.102
+        - 10.10.10.103
+        - 10.10.10.104
+~~~
+
+Once this has been added to the catalog it can be used as a named location in yaml blueprints using:
+
+~~~ yaml
+location: vagrant
+~~~
+
+
+#### Legacy Syntax
+
+The following legacy and experimental syntax is also supported, but deprecated:
+
+~~~ yaml
+<blueprint-definition>
+brooklyn.catalog:
+  <catalog-metadata>
+~~~ 
+
+In this format, the `brooklyn.catalog` block is optional;
+and an `id` in the `<blueprint-definition>` will be used to determine the catalog ID. 
+This is primarily supplied for OASIS CAMP 1.1 compatibility,
+where the same YAML blueprint can be POSTed to the catalog endpoint to add to a catalog
+or POSTed to the applications endpoint to deploy an instance.
+(This syntax is discouraged as the latter usage, 
+POSTing to the applications endpoint,
+will ignored the `brooklyn.catalog` information;
+this means references to any `item` blocks in the `<catalog-metadata>` will not be resolved,
+and any OSGi `brooklyn.libraries` defined there will not be loaded.)
+
+
+
+### Templates and the Add-Application Wizard
+
+A `template` is a full application. It consists of one or more entities inside an application 
+(though this is also composable: it can be used as part of another application).
+When a `template` is added to the catalog, the blueprint will appear in the 'Create Application' dialog
+as shown here:
+
+[![MySQL in Brooklyn Catalog](mysql-in-catalog-w700.png "MySQL in Brooklyn Catalog")](mysql-in-catalog.png) 
+
+
+
+### Catalog Management
+
+The Catalog tab in the web console will show all versions of catalog items,
+and allow you to add new items.
+
+
+#### Adding to the Catalog
+
+On the UI the "add" button <img src="images/add-to-catalog.png" width="24" alt="add-to-catalog" /> at the top of the menu panel allows the
+addition of new Applications to the catalog, via YAML, and of new Locations.
+
+In addition to the GUI, items can be added to the catalog via the REST API
+with a `POST` of the YAML file to `/v1/catalog` endpoint.
+To do this using `curl`:
+
+~~~ bash
+curl -u admin:password http://127.0.0.1:8081/v1/catalog --data-binary @/path/to/riak.catalog.bom
+~~~ 
+
+Or using the CLI:
+
+~~~ bash
+br catalog add /path/to/riak.catalog.bom
+~~~ 
+
+
+
+#### Deleting from the Catalog
+
+On the UI, if an item is selected, a 'Delete' button in the detail panel can be used to delete it from the catalog.
+
+Using the REST API, you can delete a versioned item from the catalog using the corresponding endpoint. 
+For example, to delete the item with id `datastore` and version `1.0` with `curl`:
+
+~~~ bash
+curl -u admin:password -X DELETE http://127.0.0.1:8081/v1/catalog/applications/datastore/1.0
+~~~ 
+
+
+**Note:** Catalog items should not be deleted if there are running apps which were created using the same item. 
+During rebinding the catalog item is used to reconstruct the entity.
+
+If you have running apps which were created using the item you wish to delete, you should instead deprecate the catalog item.
+Deprecated catalog items will not appear in the add application wizard, or in the catalog list but will still
+be available to Brooklyn for rebinding. The option to display deprecated catalog items in the catalog list will be added
+in a future release.
+
+Deprecation applies to a specific version of a catalog item, so the full
+id including the version number is passed to the REST API as follows:
+
+~~~ bash
+curl -u admin:password -X POST http://127.0.0.1:8081/v1/catalog/entities/MySQL:1.0/deprecated/true
+~~~ 
+
+
+### Versioning
+
+Version numbers follow the OSGi convention. This can have a major, minor, micro and qualifier part.
+For example, `1.0`. `1.0.1` or `1.0.1-20150101`.
+
+The combination of `id:version` strings must be unique across the catalog.
+It is an error to deploy the same version of an existing item:
+to update a blueprint, it is recommended to increase its version number;
+alternatively in some cases it is permitted to delete an `id:version` instance
+and then re-deploy.
+If no version is specified, re-deploying will automatically
+increment an internal version number for the catalog item.
+
+When referencing a blueprint, if a version number is not specified 
+the latest non-snapshot version will be loaded when an entity is instantiated.
+
+
+### Brooklyn Server Command Line Arguments
+
+The command line arguments when launching `brooklyn` include several commands for working with the catalog.
+
+* `--catalogAdd <file.bom>` will add the catalog items in the `bom` file
+* `--catalogReset` will reset the catalog to the initial state 
+  (based on `brooklyn/default.catalog.bom` on the classpath, by default in a dist in the `conf/` directory)
+* `--catalogInitial <file.bom>` will set the catalog items to use on first run,
+  on a catalog reset, or if persistence is off
+
+If `--catalogInitial` is not specified, the default initial catalog at `brooklyn/default.catalog.bom` will be used.
+As `scanJavaAnnotations: true` is set in `default.catalog.bom`, Brooklyn will scan the classpath for catalog items,
+which will be added to the catalog.
+To launch Brooklyn without initializing the catalog, use `--catalogInitial classpath://brooklyn/empty.catalog.bom`
+
+If [persistence](../../ops/persistence/) is enabled, catalog additions will remain between runs. If items that were
+previously added based on items in `brooklyn/default.catalog.bom` or `--catalogInitial` are 
+deleted, they will not be re-added on subsequent restarts of brooklyn. I.e. `--catalogInitial` is ignored
+if persistence is enabled and persistent state has already been created.
+
+For more information on these commands, run `brooklyn help launch`.
+
+
+<!--
+TODO: make test cases from the code snippets here, and when building the docs assert that they match test cases
+-->

http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/1330dcd3/guide/blueprints/catalog/mysql-in-catalog-w700.png
----------------------------------------------------------------------
diff --git a/guide/blueprints/catalog/mysql-in-catalog-w700.png b/guide/blueprints/catalog/mysql-in-catalog-w700.png
new file mode 100644
index 0000000..f370249
Binary files /dev/null and b/guide/blueprints/catalog/mysql-in-catalog-w700.png differ

http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/1330dcd3/guide/blueprints/catalog/mysql-in-catalog.png
----------------------------------------------------------------------
diff --git a/guide/blueprints/catalog/mysql-in-catalog.png b/guide/blueprints/catalog/mysql-in-catalog.png
new file mode 100644
index 0000000..685455d
Binary files /dev/null and b/guide/blueprints/catalog/mysql-in-catalog.png differ

http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/1330dcd3/guide/blueprints/chef/about-chef.md
----------------------------------------------------------------------
diff --git a/guide/blueprints/chef/about-chef.md b/guide/blueprints/chef/about-chef.md
new file mode 100644
index 0000000..8f87d07
--- /dev/null
+++ b/guide/blueprints/chef/about-chef.md
@@ -0,0 +1,50 @@
+---
+title: About Chef
+title_in_menu: About Chef
+layout: website-normal
+---
+
+## What you need to know about Chef
+
+Chef works in two different modes, *server* and *solo*. *Server* is where the Chef client talks to a central server
+to retrieve information about its roles, policies and cookbooks (where a cookbook defines how to install and
+configure a particular piece of software). With *solo*, the client works in isolation, therefore its configuration
+and cookbooks must be supplied by another means.
+
+Chef *client* is the Chef agent. This is a Ruby application which is installed on each and every managed host. When
+invoked in server mode, it will contact the Chef server to check for updates to cookbooks and policy; it then "runs"
+the recipes in its run lists, to converge the machine to a known state. In solo mode, it reads the locally-maintained
+cookbooks and policies. The client may be run as a daemon that checks the server regularly, or it could merely be
+run manually when required.
+
+The *policy* is a set of rules on the Chef server. A client starts with a set of *attributes*, which could be as
+simple as its name and a recipe runlist, or which may involve a more complex set of attributes about how it is to be
+configured. The client then augments this with auto-detected metadata - a tool called `ohai` is run that collects
+detailed information about the host. Next, the policy on the server modifies these attributes - overriding some,
+setting defaults for others - to produce a final set of attributes. It is these which are the input to the recipes.
+Finally, the attributes are uploaded to the server where they are stored as metadata for the node, where they can be
+inspected and modified by the system operator.
+
+Also of interest is `knife`, which is the workstation toolkit for Chef. Typically this would be installed on the
+operation engineer's workstation, where it would be used to interact with the Chef server and clients. Of particular
+interest to us is the *bootstrap* operation, which is used for setting up new Chef clients - given a virtual machine,
+it will install the Chef client on it, configure it with enough information to find the Chef server and performs its
+first run, and then kicks off the Chef client for the first time.
+
+There is often a preconception about how a Chef client is bootstrapped; mistakenly, there is the belief that the
+`knife` tool configures the Chef server with information about the client, and the client finds out about itself from
+the server. This is not the case - the bootstrap operation does not involve `knife` talking to the server. Instead,
+`knife` packages up all of the required information and sends it to the client - the client will then introduce
+itself to the server, passing on its configuration.
+
+This diagram summarises the interaction between Brooklyn, the new node, and the various Chef tools. Note that there
+is no interaction between the Apache Brooklyn Server and the Chef Server.
+
+[![Chef Flow Diagram](chef-call-flow.png "Chef Flow Diagram" )](chef-call-flow.png)
+
+### How Brooklyn interacts with Chef
+
+Brooklyn understands both the *server* and *solo* modes of operation. Server mode utilises the `knife` toolkit, and
+therefore `knife` must be installed onto the Apache Brooklyn server and configured appropriately. Solo mode does not have any
+special requirements; when running in solo mode, Brooklyn will install and configure the Chef client over SSH, just
+like it does most other kinds of entities.

http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/1330dcd3/guide/blueprints/chef/advanced-chef-integration.md
----------------------------------------------------------------------
diff --git a/guide/blueprints/chef/advanced-chef-integration.md b/guide/blueprints/chef/advanced-chef-integration.md
new file mode 100644
index 0000000..0d65286
--- /dev/null
+++ b/guide/blueprints/chef/advanced-chef-integration.md
@@ -0,0 +1,48 @@
+---
+title: Advanced Chef Integration
+title_in_menu: Advanced Chef Integration
+layout: website-normal
+---
+
+### Adding Sensors and Effectors
+
+Custom sensors and effectors can be added using an `entity.initializer` section in the YAML blueprint.
+
+One common pattern is to have sensors which extract information from Ohai.
+Another common pattern is to install a monitoring agent as part of the run list,
+configured to talk to a monitoring store, and then to add a sensor feed which reads data from that store.
+
+On the effector side, you can add SSH-based effectors in the usual way.
+You can also describe additional chef converge targets following the pattern set down in
+`ChefLifecycleEffectorTasks`, making use of conveniences in `ChefSoloTasks` and `ChefServerTasks`,
+or provide effectors which invoke network API's of the systems under management
+(for example to supply the common `executeScript` effector as on the standard `MySqlNode`). 
+   
+
+### Next Steps: Simpifying sensors and effectors, transferring files, and configuring ports
+
+The Brooklyn-Chef integration is work in progress, with a few open issues we'd still like to add.
+Much of the thinking for this is set forth in the [Google document](https://docs.google.com/a/cloudsoftcorp.com/document/d/18ZwzmncbJgJeQjnSvMapTWg6N526cvGMz5jaqdkxMf8)
+indicated earlier.  If you'd like to work with us to implement these, please let us know.
+
+
+## Reference
+
+A general schema for the supported YAML is below: 
+
+{% highlight yaml %}
+- type: chef:cookbook_name
+  cookbook_urls:
+    cookbook_name: url://for/cookbook.tgz
+    dependency1: url://for/dependency1.tgz
+  launch_run_list: [ "cookbook_name::start" ]
+  launch_attributes: # map of arguments to set in the chef node
+  service_name: cookbook_service
+  pid_file: /var/run/cookbook.pid
+{% endhighlight %}
+
+If you are interested in exploring the Java code for creating blueprints,
+start with the `TypedToyMySqlEntiyChef` class, which essentially does what this tutorial has shown;
+and then move on to the `DynamicToyMySqlEntiyChef` which starts to look at more sophisticated constructs.
+(Familiarity with BASH and basic Java blueprints may be useful at that stage.)
+

http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/1330dcd3/guide/blueprints/chef/chef-call-flow.png
----------------------------------------------------------------------
diff --git a/guide/blueprints/chef/chef-call-flow.png b/guide/blueprints/chef/chef-call-flow.png
new file mode 100644
index 0000000..d899de2
Binary files /dev/null and b/guide/blueprints/chef/chef-call-flow.png differ

http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/1330dcd3/guide/blueprints/chef/creating-blueprints.md
----------------------------------------------------------------------
diff --git a/guide/blueprints/chef/creating-blueprints.md b/guide/blueprints/chef/creating-blueprints.md
new file mode 100644
index 0000000..8d30131
--- /dev/null
+++ b/guide/blueprints/chef/creating-blueprints.md
@@ -0,0 +1,105 @@
+---
+title: Creating Blueprints from Chef
+title_in_menu: Creating Blueprints from Chef
+layout: website-normal
+---
+
+In a nutshell, a new Chef-based entity can be defined as a service by specifying
+`chef:cookbook_name` as the `service_type`, along with a collection of optional configuration.
+An illustrative example is below:
+
+{% highlight yaml %}
+{% readj example_yaml/mysql-chef-1.yaml %}
+{% endhighlight %}
+
+*This works without any installation: try it now, copying-and-pasting to the Brooklyn console.
+(Don't forget to add your preferred `location: some-cloud` to the spec.)*  
+
+Notice, if you target `google-compute-engine` location, you may need to specify `bind_address: 0.0.0.0` for the `mysql` cookbook, as described [here](https://github.com/chef-cookbooks/mysql/blob/46dccac22d282a05ee6a401e10ae8f5f8114fd66/README.md#parameters).
+
+We'll now walk through the important constituent parts,
+and then proceed to describing things which can be done to simplify the deployment.
+
+
+### Cookbook Primary Name
+
+The first thing to note is the type definition:
+
+    - type: chef:mysql
+
+This indicates that the Chef entity should be used (`org.apache.brooklyn.entity.chef.ChefEntity`) 
+to interpret and pass the configuration,
+and that it should be parameterised with a `brooklyn.chef.cookbook.primary.name` of `mysql`.
+This is the cookbook namespace used by default for determining what to install and run.
+
+
+### Importing Cookbooks
+
+Next we specify which cookbooks are required and where they can be pulled from:
+
+      cookbook_urls:
+        mysql: https://github.com/opscode-cookbooks/mysql/archive/v4.0.12.tar.gz
+        openssl: https://github.com/opscode-cookbooks/openssl/archive/v1.1.0.tar.gz
+        build-essential: https://github.com/opscode-cookbooks/build-essential/archive/v1.4.4.tar.gz
+
+Here, specific versions are being downloaded from the canonical github repository.
+Any URL can be used, so long as it is resolvable on either the target machine or the
+Brooklyn server; this includes `file:` and `classpath:` URLs.
+
+The archive can be ZIP or TAR or TGZ.
+
+The structure of the archive must be that a single folder is off the root,
+and in that folder contains the usual Chef recipe and auxiliary files.
+For example, the archive might contain `mysql-master/recipes/server.rb`.
+Archives such as those above from github match this format.  
+The name of that folder does not matter, as often they contain version information.
+When deployed, these will be renamed to match the short name (the key in the `cookbooks_url` map,
+for instance `mysql` or `openssl`).
+
+If Chef server is configured (see below), this section can be omitted.
+
+
+### Launch Run List and Attributes
+
+The next part is to specify the Chef run list and attributes to store when launching the entity: 
+
+      launch_run_list:
+      - mysql::server
+      
+      launch_attributes:
+        mysql:
+          server_root_password: p4ssw0rd
+          server_repl_password: p4ssw0rd
+          server_debian_password: p4ssw0rd
+
+For the `launch_run_list`, you can use either the YAML `- recipe` syntax or the JSON `[ "recipe" ]` syntax.
+
+The `launch_attributes` key takes a map which will be stored against the `node` object in Chef.
+Thus in this example, the parameter `node['mysql']['server_root_password']` required by the mysql blueprint
+is set as specified.
+
+You can of course set many other attributes in this manner, in addition to those that are required!  
+
+
+### Simple Monitoring
+
+The final section determines how Brooklyn confirms that the service is up.
+Sophisticated solutions may install monitoring agents as part of the `launch_run_list`,
+with Brooklyn configured to read monitoring information to confirm the launch was successful.
+However for convenience, two common mechanisms are available out of the box:
+
+      #service_name: mysqld
+      pid_file: /var/run/mysqld/mysqld.pid
+
+If `service_name` is supplied, Brooklyn will check the return code of the `status` command
+run against that service, ensuring it is 0.  (Note that this is not universally reliable,
+although it is the same mechanism which Chef typically uses to test status when determining
+whether to start a service. Some services, e.g. postgres, will return 0 even if the service
+is not running.)
+
+If a `pid_file` is supplied, Brooklyn will check whether a process with the PID specified in that
+file is running. This has been selected for mysql because it appears to be more portable:
+the service name varies among OS's:  it is `mysqld` on CentOS but `mysql` on Ubuntu!
+
+
+

http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/1330dcd3/guide/blueprints/chef/example_yaml/mysql-chef-1.yaml
----------------------------------------------------------------------
diff --git a/guide/blueprints/chef/example_yaml/mysql-chef-1.yaml b/guide/blueprints/chef/example_yaml/mysql-chef-1.yaml
new file mode 100644
index 0000000..bdac530
--- /dev/null
+++ b/guide/blueprints/chef/example_yaml/mysql-chef-1.yaml
@@ -0,0 +1,24 @@
+name: chef-mysql-sample
+services:
+- type: chef:mysql
+  
+  cookbook_urls:
+    # only needed for chef solo; URL can be local to brooklyn, or github, etc...
+    mysql: https://github.com/opscode-cookbooks/mysql/archive/v4.0.12.tar.gz
+    openssl: https://github.com/opscode-cookbooks/openssl/archive/v1.1.0.tar.gz
+    build-essential: https://github.com/opscode-cookbooks/build-essential/archive/v1.4.4.tar.gz
+  
+  launch_run_list: [ "mysql::server" ]
+  launch_attributes:
+    mysql:
+      # these attrs are required by the mysql cookbook under node['mysql']
+      server_root_password: p4ssw0rd
+      server_repl_password: p4ssw0rd
+      server_debian_password: p4ssw0rd
+      # many others are attrs are supported by the cookbook and can be passed here...
+      
+  # how to determine if the process is running and how to kill it
+  # (supported options are `service_name` and `pid_file`; normally you should just pick one.
+  # here we use the pid_file because the service_name varies, mysql on centos, mysqld on ubuntu!)
+  #service_name: mysqld
+  pid_file: /var/run/mysqld/mysqld.pid

http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/1330dcd3/guide/blueprints/chef/example_yaml/mysql-chef-2.yaml
----------------------------------------------------------------------
diff --git a/guide/blueprints/chef/example_yaml/mysql-chef-2.yaml b/guide/blueprints/chef/example_yaml/mysql-chef-2.yaml
new file mode 100644
index 0000000..9e9de9b
--- /dev/null
+++ b/guide/blueprints/chef/example_yaml/mysql-chef-2.yaml
@@ -0,0 +1,28 @@
+name: chef-mysql-sample
+services:
+- type: chef:mysql
+  id: db
+  
+  cookbook_urls:
+    # only needed for chef solo; URL can be local to brooklyn, or github, etc...
+    mysql: https://github.com/opscode-cookbooks/mysql/archive/v4.0.12.tar.gz
+    openssl: https://github.com/opscode-cookbooks/openssl/archive/v1.1.0.tar.gz
+    build-essential: https://github.com/opscode-cookbooks/build-essential/archive/v1.4.4.tar.gz
+  
+  launch_run_list: [ "mysql::server" ]
+  launch_attributes:
+    mysql:
+      # these attrs are required by the mysql cookbook under node['mysql']
+      server_root_password: $brooklyn:entity("db").config("mysql.password")
+      server_repl_password: $brooklyn:entity("db").config("mysql.password")
+      server_debian_password: $brooklyn:entity("db").config("mysql.password")
+      # many others are attrs are supported by the cookbook and can be passed here...
+      
+  # how to determine if the process is running and how to kill it
+  # (supported options are `service_name` and `pid_file`; normally you should just pick one.
+  # here we use the pid_file because the service_name varies, mysql on centos, mysqld on ubuntu!)
+  #service_name: mysqld
+  pid_file: /var/run/mysqld/mysqld.pid
+    
+brooklyn.config:
+  mysql.password: p4ssw0rd


Mime
View raw message