brooklyn-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From aleds...@apache.org
Subject [3/5] brooklyn-docs git commit: improve location yaml-syntax docs
Date Wed, 03 Aug 2016 21:27:01 GMT
improve location yaml-syntax docs


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

Branch: refs/heads/master
Commit: de1e235b4e4689a814112574e7b733b445684b65
Parents: 2be644e
Author: Aled Sage <aled.sage@gmail.com>
Authored: Tue Aug 2 12:44:10 2016 +0100
Committer: Aled Sage <aled.sage@gmail.com>
Committed: Wed Aug 3 22:22:55 2016 +0100

----------------------------------------------------------------------
 guide/ops/locations/index.md                    |  22 ++--
 .../fabric-with-multiple-locations.yaml         |  14 +++
 .../simple-appserver-with-location-byon.yaml    |   4 +-
 ...mple-appserver-with-location-per-entity.yaml |   8 ++
 .../simple-appserver-with-location.yaml         |   2 +-
 guide/yaml/setting-locations.md                 | 109 ++++++++++++++++---
 6 files changed, 126 insertions(+), 33 deletions(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/de1e235b/guide/ops/locations/index.md
----------------------------------------------------------------------
diff --git a/guide/ops/locations/index.md b/guide/ops/locations/index.md
index fbcf35f..51f906a 100644
--- a/guide/ops/locations/index.md
+++ b/guide/ops/locations/index.md
@@ -6,21 +6,13 @@ children:
 check_directory_for_children: true
 ---
 
-Locations are the environments to which Brooklyn deploys applications, including:
+Locations are the environments to which Brooklyn deploys applications. Most commonly these

+are cloud services such as AWS, GCE, and IBM Softlayer. Brooklyn also supports deploying

+to a pre-provisioned network or to localhost (primarily useful for testing blueprints).
 
-Brooklyn supports a wide range of locations:
-
-* <a href="#clouds">Clouds</a>, where it will provision machines
-* <a href="#localhost">Localhost</a> (e.g. your laptop), 
-  where it will deploy via `ssh` to `localhost` for rapid testing
-* <a href="#byon">BYON</a>, where you "bring your own nodes",
-  specifying already-existing hosts to use
-* And many others, including object stores and online services
-
-Configuration can be set in `~/.brooklyn/brooklyn.properties`, through the
-location wizard tool available within the web console
-or directly in YAML when specifying a location.
-On some entities, config keys determining matching selection and provisioning behavior
-can also be set in `provisioning.properties`.
+Also see the [Locations yaml guide]({{ site.path.guide }}/yaml/setting-locations.html),
+use within an entity of [provisioning.properties]({{ site.path.guide }}/yaml/entity-configuration.html#entity-provisioningproperties-overriding-and-merging),
+how to add location definitions to the [Catalog]({{ site.path.guide }}/ops/catalog/), 
+and how to use [Externalized Configuration](({{ site.path.guide }}/ops/externalized-configuration.html).
 
 {% child_content %}

http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/de1e235b/guide/yaml/example_yaml/fabric-with-multiple-locations.yaml
----------------------------------------------------------------------
diff --git a/guide/yaml/example_yaml/fabric-with-multiple-locations.yaml b/guide/yaml/example_yaml/fabric-with-multiple-locations.yaml
new file mode 100644
index 0000000..3a7d3ab
--- /dev/null
+++ b/guide/yaml/example_yaml/fabric-with-multiple-locations.yaml
@@ -0,0 +1,14 @@
+name: fabric-of-app-server-clusters
+locations:
+- aws-ec2:us-east-1
+- aws-ec2:us-west-1
+services:
+- type: org.apache.brooklyn.entity.group.DynamicFabric
+  brooklyn.config:
+    memberSpec:
+      $brooklyn:entitySpec:
+        type: org.apache.brooklyn.entity.group.DynamicCluster
+        brooklyn.config:
+          memberSpec:
+            $brooklyn:entitySpec:
+              type: org.apache.brooklyn.entity.webapp.tomcat.Tomcat8Server

http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/de1e235b/guide/yaml/example_yaml/simple-appserver-with-location-byon.yaml
----------------------------------------------------------------------
diff --git a/guide/yaml/example_yaml/simple-appserver-with-location-byon.yaml b/guide/yaml/example_yaml/simple-appserver-with-location-byon.yaml
index 8e9c951..7e4c0ca 100644
--- a/guide/yaml/example_yaml/simple-appserver-with-location-byon.yaml
+++ b/guide/yaml/example_yaml/simple-appserver-with-location-byon.yaml
@@ -7,6 +7,4 @@ location:
     - 192.168.0.18
     - 192.168.0.19
 services:
-- type: org.apache.brooklyn.entity.webapp.jboss.JBoss7Server
-  location:
-    byon:(hosts="127.0.0.1")
+- type: org.apache.brooklyn.entity.webapp.tomcat.Tomcat8Server

http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/de1e235b/guide/yaml/example_yaml/simple-appserver-with-location-per-entity.yaml
----------------------------------------------------------------------
diff --git a/guide/yaml/example_yaml/simple-appserver-with-location-per-entity.yaml b/guide/yaml/example_yaml/simple-appserver-with-location-per-entity.yaml
new file mode 100644
index 0000000..a39e27d
--- /dev/null
+++ b/guide/yaml/example_yaml/simple-appserver-with-location-per-entity.yaml
@@ -0,0 +1,8 @@
+name: simple-appserver-with-location-per-entity
+services:
+- type: org.apache.brooklyn.entity.webapp.tomcat.Tomcat8Server
+  location:
+    byon(hosts="192.168.0.18",user="brooklyn",privateKeyFile="~/.ssh/brooklyn.pem")
+- type: org.apache.brooklyn.entity.webapp.jboss.JBoss7Server
+  location:
+    byon(hosts="192.168.0.19",user="brooklyn",privateKeyFile="~/.ssh/brooklyn.pem")

http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/de1e235b/guide/yaml/example_yaml/simple-appserver-with-location.yaml
----------------------------------------------------------------------
diff --git a/guide/yaml/example_yaml/simple-appserver-with-location.yaml b/guide/yaml/example_yaml/simple-appserver-with-location.yaml
index 79344c8..764eaac 100644
--- a/guide/yaml/example_yaml/simple-appserver-with-location.yaml
+++ b/guide/yaml/example_yaml/simple-appserver-with-location.yaml
@@ -5,4 +5,4 @@ location:
     identity: AKA_YOUR_ACCESS_KEY_ID
     credential: <access-key-hex-digits>
 services:
-- type: org.apache.brooklyn.entity.webapp.jboss.JBoss7Server
+- type: org.apache.brooklyn.entity.webapp.tomcat.Tomcat8Server

http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/de1e235b/guide/yaml/setting-locations.md
----------------------------------------------------------------------
diff --git a/guide/yaml/setting-locations.md b/guide/yaml/setting-locations.md
index ab92369..23ce6a4 100644
--- a/guide/yaml/setting-locations.md
+++ b/guide/yaml/setting-locations.md
@@ -7,8 +7,13 @@ categories: [use, guide, defining-applications]
 
 {% include fields.md %}
 
-Brooklyn supports a very wide range of target locations -- localhost is mainly a convenience
for testing.
-With deep integration to [Apache jclouds](http://jclouds.org), most well-known clouds and
cloud platforms are supported.
+Brooklyn supports a very wide range of target locations. 
+With deep integration to [Apache jclouds](https://jclouds.apache.org), most well-known clouds

+and cloud platforms are supported. See the [Locations guide]({{ site.path.guide }}/ops/locations/)

+for details and more examples.
+
+### Cloud Example
+
 The following example is for Amazon EC2:
 
 {% highlight yaml %}
@@ -24,22 +29,98 @@ Private cloud systems including `openstack-nova` and `cloudstack` are
also suppo
 although for these you'll supply an `endpoint: https://9.9.9.9:9999/v2.0/` 
 (or `client/api/` in the case of CloudStack) instead of the `region`.
 
+
+### "Bring Your Own Nodes" Example
+
 You can also specify pre-existing servers to use -- "bring-your-own-nodes".
-These can be a global pool or specific to a service.
-Both styles are shown here (though normally only one will be selected,
-<!-- TODO see #1377, currently it is *parent* location which is preferred typically -->

-depending on the blueprint):
+The example below shows a pool of machines that will be used by the entities within the 
+application.
 
 {% highlight yaml %}
 {% readj example_yaml/simple-appserver-with-location-byon.yaml %}
 {% endhighlight %}
 
-Note in this example that we've used JSON-style notation in the second `location` block.
-YAML supports this, and sometimes that makes more readable plans.
-(Although in this case a simple `location: localhost` is equivalent and even more succinct,

-but this is a tutorial.)
 
-For more information see the [Operations: Locations]({{ site.path.guide }}/ops/locations)
section of the User Guide.
-This includes support for defining locations externally in a [brooklyn.properties]({{ brooklyn_properties_url_path
}}) file,
-after which you can deploy to clouds or bring-your-own-nodes
-simply as `location: jclouds:aws-ec2:eu-west-1` or `location: named:my_cloudstack`.
+### Single Line and Multi Line Locations
+
+A simple location can be specified on a single line. Alternatively, it can be split to have
one
+configuration option per line (recommended for all but the simplest locations).
+
+For example, the two examples below are equivalent:
+
+{% highlight yaml %}
+location: byon(name="my loc",hosts="1.2.3.4",user="bob",privateKeyFile="~/.ssh/bob_id_rsa")
+{% endhighlight %}
+
+{% highlight yaml %}
+location:
+  byon:
+    name: "my loc"
+    hosts:
+    - "1.2.3.4"
+    user: "bob"
+    privateKeyFile: "~/.ssh/bob_id_rsa"
+{% endhighlight %}
+
+
+### Specific Locations for Specific Entities
+
+One can define specific locations on specific entities within the blueprint (instead of,
or as 
+well as, defining the location at the top-level of the blueprint).
+
+The example below will deploy Tomcat and JBoss App Server to different Bring Your Own Nodes
+locations:
+
+{% highlight yaml %}
+{% readj example_yaml/simple-appserver-with-location-per-entity.yaml %}
+{% endhighlight %}
+
+The rules for precedence when defining a location for an entity are:
+
+* The location defined on that specific entity.
+* If no location, then the first ancestor that defines an explicit location.
+* If still no location, then the location defined at the top-level of the blueprint.
+
+This means, for example, that if you define an explicit location on a cluster then it will
be used 
+for all members of that cluster.
+
+
+### Multiple Locations
+
+Some entities are written to expect a set of locations. For example, a `DynamicFabric` will
+create a member entity in each location that it is given. To supply multiple locations, simply
+use `locations` with a yaml list.
+
+In the example below, it will create a cluster of app-servers in each location:
+
+{% highlight yaml %}
+{% readj example_yaml/fabric-with-multiple-locations.yaml %}
+{% endhighlight %}
+
+For brevity, this example excludes the credentials for aws-ec2. These could either be specificed
+in-line or defined as named locations in the catalog (see below).
+
+
+### Adding Locations to the Catalog
+
+The examples above have given all the location details within the application blueprint.
+It is also possible (and indeed preferred) to add the location definitions to the catalog
+so that they can be referenced by name in any blueprint.
+
+For more information see the [Operations: Catalog]({{ site.path.guide }}/ops/catalog/) section
of 
+the User Guide.
+
+
+### Externalized Configuration
+
+For simplicity, the examples above have included the cloud credentials. For a production
system, 
+it is strongly recommended to use [Externalized Configuration]({{ site.path.guide }}/ops/externalized-configuration.html)
+to retrieve the credentials from a secure credentials store, such as [Vault](https://www.vaultproject.io).
+
+
+### Use of provisioning.properties
+
+An entity that represents a "software process" can use the configuration option 
+`provisioning.properties` to augment the location's configuration. For more information,
see
+[Entity Configuration]({{ site.path.guide }}/yaml/entity-configuration.html#entity-provisioningproperties-overriding-and-merging)
+details.


Mime
View raw message