brooklyn-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From henev...@apache.org
Subject [06/13] incubator-brooklyn git commit: add java_link.html for javadoc+src, tidy up and expand locations docs
Date Tue, 20 Jan 2015 16:12:24 GMT
add java_link.html for javadoc+src, tidy up and expand locations docs


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

Branch: refs/heads/master
Commit: 5cf0666f8e42bfbad720032bb4889265af0dd171
Parents: fa257f6
Author: Alex Heneveld <alex.heneveld@cloudsoftcorp.com>
Authored: Mon Jan 19 22:51:13 2015 +0000
Committer: Alex Heneveld <alex.heneveld@cloudsoftcorp.com>
Committed: Mon Jan 19 22:59:44 2015 +0000

----------------------------------------------------------------------
 docs/_includes/java_link.html                  |  18 ++
 docs/_includes/sitemap-item.html               |   2 +-
 docs/_plugins/brooklyn_metadata.rb             |  16 +-
 docs/guide/ops/index.md                        |   3 +-
 docs/guide/ops/locations/configuring.md        | 105 --------
 docs/guide/ops/locations/index.md              | 267 ++++++++++++++++----
 docs/guide/ops/locations/more-locations.md     |  55 ++++
 docs/guide/ops/locations/ssh-keys.md           |  60 +++++
 docs/guide/ops/persistence/index.md            |  23 +-
 docs/style/css/_code_blocks.scss               |   3 +
 docs/website/documentation/increase-entropy.md |   2 +-
 11 files changed, 378 insertions(+), 176 deletions(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/5cf0666f/docs/_includes/java_link.html
----------------------------------------------------------------------
diff --git a/docs/_includes/java_link.html b/docs/_includes/java_link.html
new file mode 100644
index 0000000..b296652
--- /dev/null
+++ b/docs/_includes/java_link.html
@@ -0,0 +1,18 @@
+{% comment %}
+
+includes a code-formatted class name with link to its javadoc and optionally its source code
+
+usage:  
+
+{ % include java_link.html class_name="JcloudsLocationConfig" package_path="brooklyn/location/jclouds"
project_subpath="location/jclouds" % }
+
+
+{% endcomment %}{% if include.project_subpath %}<code>{{ include.class_name }}</code>
+  (<a href="{{ site.guide.path }}/misc/javadoc/{{ include.package_path }}/{{ include.class_name
}}.html">javadoc</a>, 
+   <a href="{{ site.brooklyn.url.git }}/{{ include.project_subpath }}/src/main/java/{{
include.package_path }}/{{ include.class_name }}.java">src</a>)
+{% else %}<a href="{{ site.guide.path }}/misc/javadoc/{{ include.package_path }}/{{ include.class_name
}}.html">
+<code>{{ include.class_name }}</code></a>
+{% endif %}{% comment %}
+
+must NOT have a newline at the end here, as the include is often done inline
+{% endcomment %}
\ No newline at end of file

http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/5cf0666f/docs/_includes/sitemap-item.html
----------------------------------------------------------------------
diff --git a/docs/_includes/sitemap-item.html b/docs/_includes/sitemap-item.html
index 247fc5d..eebc513 100644
--- a/docs/_includes/sitemap-item.html
+++ b/docs/_includes/sitemap-item.html
@@ -1,6 +1,6 @@
 {% pop site_items item %}
 {% set_hash_entry item path item_path %}
- {% set_hash_entry item url item_url %}
+{% set_hash_entry item url item_url %}
 
 {% unless item_path %}
  {% unless item_url %}

http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/5cf0666f/docs/_plugins/brooklyn_metadata.rb
----------------------------------------------------------------------
diff --git a/docs/_plugins/brooklyn_metadata.rb b/docs/_plugins/brooklyn_metadata.rb
index b5fe81d..89d82aa 100644
--- a/docs/_plugins/brooklyn_metadata.rb
+++ b/docs/_plugins/brooklyn_metadata.rb
@@ -1,17 +1,18 @@
 # Inserts several useful fields that can be referenced using {{ name }} syntax
 #
-# TODO: remove, no need for a plugin i think, this is already set in fields.md
-# (although doing it in ruby might be better!)
+# TODO: move things from fields.md to here
 #
-# site.data.brooklyn.version: brooklyn version, such as 0.7.0-M1
-# site.data.brooklyn.is_snapshot: true if this is a snapshot version, otherwise false
+# site.brooklyn.version: brooklyn version, such as 0.7.0-M1 (taken from brooklyn-version
in _config.yml)
+# site.brooklyn.is_snapshot: true if this is a snapshot version, otherwise false
 #
 module BrooklynMetadata
 
-  BROOKLYN_VERSION = "0.7.0-M2-incubating" unless defined? BROOKLYN_VERSION
+  BROOKLYN_VERSION = "0.7.0-SNAPSHOT" unless defined? BROOKLYN_VERSION
 
   class Generator < Jekyll::Generator
     def generate(site)
+      raise "Brooklyn version mismatch" if BrooklynMetadata::BROOKLYN_VERSION != site.config['brooklyn-version']
+
       is_snapshot = BrooklynMetadata::BROOKLYN_VERSION.end_with?('-SNAPSHOT')
       
       if is_snapshot
@@ -55,14 +56,11 @@ module BrooklynMetadata
       
       url_set["git"] = "https://github.com/apache/incubator-brooklyn/tree/#{ git_branch }"
       
-      site.data['brooklyn'] = {
+      site.config['brooklyn'] = {
           "version" => BrooklynMetadata::BROOKLYN_VERSION,
           "is_snapshot" => is_snapshot,
           "url" => url_set
       }
-      
-      # TODO check that "#{ brooklyn['url']['git'] }/core/src/main/java/brooklyn/BrooklynVersion.java"
-      # exists AND contains "versionFromStatic = \"#{ brooklyn['version'] }\""
   
     end
   end

http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/5cf0666f/docs/guide/ops/index.md
----------------------------------------------------------------------
diff --git a/docs/guide/ops/index.md b/docs/guide/ops/index.md
index 60b7c6e..b224852 100644
--- a/docs/guide/ops/index.md
+++ b/docs/guide/ops/index.md
@@ -2,8 +2,7 @@
 title: Operations
 layout: website-normal
 children:
-- locations/index.md
-- locations/configuring.md
+- locations/
 - persistence/
 - launching/
 - catalog/

http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/5cf0666f/docs/guide/ops/locations/configuring.md
----------------------------------------------------------------------
diff --git a/docs/guide/ops/locations/configuring.md b/docs/guide/ops/locations/configuring.md
deleted file mode 100644
index cb3ee16..0000000
--- a/docs/guide/ops/locations/configuring.md
+++ /dev/null
@@ -1,105 +0,0 @@
----
-title: Configuring Locations
-layout: website-normal
----
-
-<a id="locations"></a>
-
-Brooklyn supports deploying to any machine which admits SSH access, as well as to
-a huge variety of external and on-premise clouds.  You can also connect to services,
-or use whatever technique for deployment suits you best (such as Xebia Overthere, in development!).
-
-Configuration is typically set in `~/.brooklyn/brooklyn.properties` using keys such as the
following:
-
-{% highlight bash %}
-# use this key for localhost (this is the default, although if you have a passphrase you
must set it)
-brooklyn.location.localhost.privateKeyFile=~/.ssh/id_rsa
-
-brooklyn.location.localhost.privateKeyPassphrase=s3cr3tPASSPHRASE
-   
-# use a special key when connecting to public clouds, and a particularly special one for
AWS
-brooklyn.location.jclouds.privateKeyFile=~/.ssh/public_clouds/id_rsa
-brooklyn.location.jclouds.aws-ec2.privateKeyFile=~/.ssh/public_clouds/aws_id_rsa
-
-# AWS credentials (when deploying to location jclouds:aws-ec2)
-brooklyn.location.jclouds.aws-ec2.identity=ABCDEFGHIJKLMNOPQRST  
-brooklyn.location.jclouds.aws-ec2.credential=s3cr3tsq1rr3ls3cr3tsq1rr3ls3cr3tsq1rr3l
-
-# credentials for 'geoscaling' service
-brooklyn.geoscaling.username=cloudsoft  
-brooklyn.geoscaling.password=xxx
-{% endhighlight %}
-
-These can also be set as environment variables (in the shell) or system properties (java
command line).
-(There are also ``BROOKLYN_JCLOUDS_PRIVATE_KEY_FILE`` variants accepted.)
-
-For any jclouds provider you will typically need to set ``identity`` and ``credential``
-in the ``brooklyn.location.jclouds.provider`` namespace.
-
-To deploy to sets of machines with known IP's, assuming you have the credentials,
-use the syntax ``byon:(hosts="user@10.9.1.1,user@10.9.1.2,user@10.9.1.3")``
-(this requires your default private key to have access; 
-see the ``prod1`` example below for specifying other credentials). 
-
-A wide range of other fields is available, because in the real world sometimes things do
get complicated.
-The following is supported from the configuration file (with whatever customization you might
want available in code): 
-
-- If there is a passphrase on the key file being used, you must supply it to Brooklyn for
it to work, of course!
-  ``privateKeyPassphrase`` does the trick (as in ``brooklyn.location.jclouds.privateKeyPassphrase``,
or other places
-  where ``privateKeyFile`` is valid).  If you don't like keys, you can just use a plain old
``password``.
-
-- Hardware requirements such as ``minRam`` and ``minCores`` can be supplied, or a ``hardwareId``
 (jclouds only)
-
-- Specific Secury Groups can be specified using `securityGroups`, if you want to reuse set
of existing ones (jclouds only)
-
-- Specific KeyPair can be specified using `keyPair`, if you want to reuse an existing keypair
(jclouds only).
-
-- Specific VM images can be specified using ``imageId`` or ``imageNameRegex`` (jclouds only)
-
-- User metadata can be attached, using the syntax ``userMetadata=key=value,key2="value 2"``
(jclouds only)
-
-- A ``user`` can be specified, with the property that -- in a jclouds world -- the user will
be *created* on the machine,
-  with admin rights, authorizing the relevant public key (corresponding to the private key,
or as described below). 
-  Login for the root account will be disabled, as will login by password if a public key
is supplied. 
-  (This is skipped if ``user`` is the ``root`` or other initial login user.)
-  
-- You can specify the user account to use to login to jclouds initially with the ``loginUser``
property.
-  Typically this is auto-detected by jclouds
-  (often ``root``, or ``ubuntu`` or ``ec2-user`` for known Ubuntu or Amazon Linux images),

-  but the strategy isn't foolproof, particularly in some private cloud setups. (jclouds only).
In some cases, you may need to specify a `loginUser.privateKeyFile` if the image you are using
doesn't allow ssh password login.
-
-- Public keys can be specified using ``publicKeyFile``, 
-  although these can usually be omitted if they follow the common pattern of being
-  the private key file with the suffix ``.pub`` appended.
-  (It is useful in the case of ``loginUser.publicKeyFile``, where you shouldn't need,
-  or might not even have, the private key of the ``root`` user in order to log in.)
-
-- You can specify the number of attempts Brooklyn should make to create
-  machines with ``machineCreateAttempts`` (jclouds only). This is useful for
-  working around the rare occasions in which cloud providers give machines that
-  are dead on arrival.
-
-You can also define named locations for commonly used groups of properties, 
-with the syntax ``brooklyn.location.named.your-group-name.``
-followed by the relevant properties.
-These can be accessed at runtime using the syntax ``named:your-group-name`` as the deployment
location.
-
-Some more advanced examples showing the syntax and properties above are as follows:
-
-{% highlight bash %}
-# Production pool of machines for my application (deploy to named:prod1)
-brooklyn.location.named.prod1=byon:(hosts="10.9.1.1,10.9.1.2,produser2@10.9.2.{10,11,20-29}")
-brooklyn.location.named.prod1.user=produser1
-brooklyn.location.named.prod1.privateKeyFile=~/.ssh/produser_id_rsa
-brooklyn.location.named.prod1.privateKeyPassphrase=s3cr3tCOMPANYpassphrase
-
-# AWS using my company's credentials and image standard, then labelling images so others
know they're mine
-brooklyn.location.named.company-jungle=jclouds:aws-ec2:us-west-1
-brooklyn.location.named.company-jungle.identity=BCDEFGHIJKLMNOPQRSTU  
-brooklyn.location.named.company-jungle.privateKeyFile=~/.ssh/public_clouds/company_aws_id_rsa
-brooklyn.location.named.company-jungle.imageId=ami-12345
-brooklyn.location.named.company-jungle.minRam=2048
-brooklyn.location.named.company-jungle.userMetadata=application=my-jungle-app,owner="Bob
Johnson"
-brooklyn.location.named.company-jungle.machineCreateAttempts=2
-{% endhighlight %}
-

http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/5cf0666f/docs/guide/ops/locations/index.md
----------------------------------------------------------------------
diff --git a/docs/guide/ops/locations/index.md b/docs/guide/ops/locations/index.md
index 3d2b99a..b5e5afd 100644
--- a/docs/guide/ops/locations/index.md
+++ b/docs/guide/ops/locations/index.md
@@ -1,101 +1,268 @@
 ---
-title: Locations Intro
+title: Locations
 layout: website-normal
+children:
+- { section: Clouds }
+- { section: Inheritance and Named Locations, title: Named Locations }
+- { section: Localhost }
+- { section: BYON }
+- more-locations.md
+- ssh-keys.md
 ---
 
-Locations are the environments to which Brooklyn deploys applications.
-These can be clouds (public or private), fixed infrastructure environments, or your laptop.
+Locations are the environments to which Brooklyn deploys applications, including:
 
-Brooklyn looks for Location configuration in `~/.brooklyn/brooklyn.properties`.
+Brooklyn supports a wide range of locations:
 
-## Setting up an SSH key
+* <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
 
-While some locations can be accessed using *user:password* credentials it is more common
to use authentication keys.
+Configuration can be set in `~/.brooklyn/brooklyn.properties`
+or directly in YAML when specifying a location.
+On some entities, config keys determining maching selection and provisioning behavior
+can also be set `in `provisioning.properties`.  
 
-To use keyfile based authentication, Brooklyn requires that the management machine has an
SSH key. By default Brooklyn looks for a key at `~/.ssh/id_rsa` and `~/.ssh/id_dsa`.
 
-If you do not already have an SSH key installed, create a new id_rsa key:
+### Clouds
 
-{% highlight bash %}
-$ ssh-keygen -t rsa -N "" -f ~/.ssh/id_rsa
-{% endhighlight %}
+For most cloud provisioning tasks, Brooklyn uses
+<a href="http://jclouds.org">Apache jclouds</a>.
+The identifiers for some of the most commonly used jclouds-supported clouds are
+(or [see the full list](http://jclouds.apache.org/reference/providers/)):
 
-If you wish to use an existing key SSH, or an SSH key
-that has a passphrase, or a location other than `~/.ssh`, you can specify this in
-`brooklyn.properties` using `brooklyn.location.localhost.privateKeyFile` and
-`brooklyn.location.localhost.privateKeyPassphrase`.
+* `jclouds:aws-ec2:<region>`: Amazon EC2, where `:<region>` might be `us-east-1`
or `eu-west-1` (or omitted)
+* `jclouds:softlayer:<region>`: IBM Softlayer, where `:<region>` might be `dal05`
or `ams01` (or omitted)
+* `jclouds:google-compute-engine`: Google Compute Engine
+* `jclouds:openstack-nova:<endpoint>`: OpenStack, where `:<endpoint>` is the
access URL (required)
+* `jclouds:cloudstack:<endpoint>`: Apache CloudStack, where `:<endpoint>` is
the access URL (required)
 
-## Localhost
+For any of these, of course, Brooklyn needs to be configured with an `identity` and a `credential`:
 
-Brooklyn can access localhost if there is an SSH key on the machine and if the SSH key has
been added to the list of  `authorized_keys` on that machine.
+{% highlight yaml %}
+location:
+  jclouds:aws-ec2:
+    identity: ABCDEFGHIJKLMNOPQRST
+    credential: s3cr3tsq1rr3ls3cr3tsq1rr3ls3cr3tsq1rr3l
+{% endhighlight %} 
+
+The above YAML can be embedded directly in blueprints, either at the root or on individual
services.
+If you prefer to keep the credentials separate, these can be set instead in `brooklyn.properties`

+in the `jclouds.<provider>` namespace:
 
 {% highlight bash %}
-# _Appends_ id_rsa.pub to authorized_keys. Other keys are unaffected.
-$ cat ~/.ssh/id_rsa.pub >> ~/.ssh/authorized_keys
+brooklyn.location.jclouds.aws-ec2.identity=ABCDEFGHIJKLMNOPQRST  
+brooklyn.location.jclouds.aws-ec2.credential=s3cr3tsq1rr3ls3cr3tsq1rr3ls3cr3tsq1rr3l
 {% endhighlight %}
 
-MacOS user? In addition to the above, enable 'Remote Login' in System Preferences >
- Sharing.
+And in this case you can reference the location in YAML with `location: jclouds:aws-ec2`.
 
+The Getting Started [template brooklyn.properties](../start/brooklyn.properties) contains
more examples 
+of configuring cloud endpoints, including information on credential types used in different
clouds.
 
-## Cloud Endpoints (via jclouds)
 
-[Apache jclouds](http://www.jclouds.org) is a multi-cloud library that Brooklyn uses to access
many clouds. The [full list of supported providers](http://jclouds.apache.org/reference/providers/)
is available on jclouds.apache.org.
+#### OS Initial Login and Setup
 
-Add your cloud provider's (API) credentials to `brooklyn.properties` and create an SSH key
on the management machine.
+Once a machine is provisioned, Brooklyn will normally attempt to log in via SSH and configure
the machine sensibly.
 
-Some clouds provide both API keys and SSH keys. In this case add only the API credentials
to `brooklyn.properties`. (jclouds will transparently use the API credentials to setup access
using the management machine's SSH key.)
+The credentials for the initial OS log on are typically discovered from the cloud, 
+but in some environments this is not possible.
+The keys `loginUser` and either `loginUser.password` or `loginUser.privateKeyFile` can be
used to force
+Brooklyn to use specific credentials for the initial login to a cloud-provisioned machine.
+(This is particularly useful when using a custom image templates where the cloud-side account
management logic is not enabled.)
 
-### Example: AWS Virginia Large Centos
+Following a successful logon, Brooklyn performs the following steps to configure the machine:
 
-{% highlight bash %}
-## Snippet from ~/.brooklyn/brooklyn.properties.
+1. to create a new user with the same name as the user `brooklyn` is running as locally
+  (this can be overridden with `user`, below)
+
+1. to install the local user's `~/.ssh/id_rsa.pub` as an `authorized_keys` on the new machine,
+   to make it easy for the operator to `ssh` in
+   (override with `privateKeyFile`; or if there is no `id_{r,d}sa{,.pub}` an ad hoc keypair
will be generated;
+   if there is a passphrase on the key, this must be supplied)  
+
+1. give `sudo` access to the newly created user (override with `grantUserSudo: false`)
+
+1. disable direct `root` login to the machine
+
+These steps can be skipped or customized as described below.
+
+
+
+#### jclouds Config Keys
+
+The following is a subset of the most commonly used configuration keys used to customize

+cloud provisioning.
+For more keys and more detail on the keys below, see 
+{% include java_link.html class_name="JcloudsLocationConfig" package_path="brooklyn/location/jclouds"
project_subpath="locations/jclouds" %}.
+
+###### OS Setup
+
+- `user` and `password` can be used to configure the operating user created on cloud-provisioned
machines
+
+- The `loginUser` config key (and subkeys) control the initial user to log in as,
+  in cases where this cannot be discovered from the cloud provider
+ 
+- Private keys can be specified using ``privateKeyFile``; 
+  these are not copied to provisioned machines, but are required if using a local public
key
+  or a pre-defined `authorized_keys` on the server.
+  (For more information on SSH keys, see [here](ssh-keys.html).) 
+
+- If there is a passphrase on the key file being used, you must supply it to Brooklyn for
it to work, of course!
+  ``privateKeyPassphrase`` does the trick (as in ``brooklyn.location.jclouds.privateKeyPassphrase``,
or other places
+  where ``privateKeyFile`` is valid).  If you don't like keys, you can just use a plain old
``password``.
+
+- Public keys can be specified using ``publicKeyFile``, 
+  although these can usually be omitted if they follow the common pattern of being
+  the private key file with the suffix ``.pub`` appended.
+  (It is useful in the case of ``loginUser.publicKeyFile``, where you shouldn't need,
+  or might not even have, the private key of the ``root`` user in order to log in.)
+
+- Use `dontCreateUser` to have Brooklyn run as the initial `loginUser` (usually `root`),
+  without creating any other user.
+
+- A post-provisioning `setup.script` can be specified (as a URL) to run an additional script,
+  before making the `Location` available to entities,
+  optionally also using `setup.script.vars` (set as `key1:value1,key2:value2`)
+
+
+###### VM Creation
+    
+- Most providers require exactly one of either `region` (e.g. `us-east-1`) or `endpoint`
(the URL, usually for private cloud deployments)
+
+- Hardware requirements can be specified, including 
+  ``minRam``, ``minCores``, and `os64Bit`; or as a specific ``hardwareId``
+
+- VM image constraints can be set using `osFamily` (e.g. `Ubuntu`, `CentOS`, `Debian`, `RHEL`)
+  and `osVersionRegex`, or specific VM images can be specified using ``imageId`` or ``imageNameRegex``
+
+- Specific VM images can be specified using ``imageId`` or ``imageNameRegex``
+
+- Specific Security Groups can be specified using `securityGroups`, as a list of strings
(the existing security group names),
+  or `inboundPorts` can be set, as a list of numeric ports (selected clouds only)
 
-# Provide jclouds with AWS API credentials.
-brooklyn.location.jclouds.aws-ec2.identity = AKA_YOUR_ACCESS_KEY_ID
-brooklyn.location.jclouds.aws-ec2.credential = YourSecretKeyWhichIsABase64EncodedString
+- A specific existing key pair for the cloud to set for `loginUser` can be specified using
`keyPair`
+  (selected clouds only)
 
-# Name this location 'AWS Virginia Large Centos' and wire to AWS US-East-1
-brooklyn.location.named.AWS\ Virginia\ Large\ Centos = jclouds:aws-ec2:us-east-1
+- User metadata can be attached, using the syntax ``userMetadata=key=value,key2="value 2"``
 
-# (Using the same name) specify image, user and minimum ram size (ie instance size)
+- You can specify the number of attempts Brooklyn should make to create
+  machines with ``machineCreateAttempts`` (jclouds only). This is useful for
+  working around the rare occasions in which cloud providers give machines that
+  are dead on arrival.
+
+- If you want to investigate failures, set `destroyOnFailure` to `false`
+  to keep failed VM's around. (You'll have to manually clean them up.)
+
+
+### Inheritance and Named Locations
+
+Named locations can be defined for commonly used groups of properties, 
+with the syntax ``brooklyn.location.named.your-group-name.``
+followed by the relevant properties.
+These can be accessed at runtime using the syntax ``named:your-group-name`` as the deployment
location.
+
+Some illustrative examples using named locations and
+showing the syntax and properties above are as follows:
+
+{% highlight bash %}
+# Production pool of machines for my application (deploy to named:prod1)
+brooklyn.location.named.prod1=byon:(hosts="10.9.1.1,10.9.1.2,produser2@10.9.2.{10,11,20-29}")
+brooklyn.location.named.prod1.user=produser1
+brooklyn.location.named.prod1.privateKeyFile=~/.ssh/produser_id_rsa
+brooklyn.location.named.prod1.privateKeyPassphrase=s3cr3tCOMPANYpassphrase
+
+# AWS using my company's credentials and image standard, then labelling images so others
know they're mine
+brooklyn.location.named.company-jungle=jclouds:aws-ec2:us-west-1
+brooklyn.location.named.company-jungle.identity=BCDEFGHIJKLMNOPQRSTU  
+brooklyn.location.named.company-jungle.privateKeyFile=~/.ssh/public_clouds/company_aws_id_rsa
+brooklyn.location.named.company-jungle.imageId=ami-12345
+brooklyn.location.named.company-jungle.minRam=2048
+brooklyn.location.named.company-jungle.userMetadata=application=my-jungle-app,owner="Bob
Johnson"
+brooklyn.location.named.company-jungle.machineCreateAttempts=2
+
+brooklyn.location.named.AWS\ Virginia\ Large\ Centos = jclouds:aws-ec2
+brooklyn.location.named.AWS\ Virginia\ Large\ Centos.region = us-east-1
 brooklyn.location.named.AWS\ Virginia\ Large\ Centos.imageId=us-east-1/ami-7d7bfc14
 brooklyn.location.named.AWS\ Virginia\ Large\ Centos.user=root
 brooklyn.location.named.AWS\ Virginia\ Large\ Centos.minRam=4096
+{% endhighlight %}
 
+If you are confused about inheritance order, the following test may be useful:
 
+{% highlight bash %}
+brooklyn.location.jclouds.KEY=VAL1
+brooklyn.location.jclouds.aws-ec2.KEY=VAL2
+brooklyn.location.named.my-aws=jclouds:aws-ec2
+brooklyn.location.named.my-aws.KEY=VAL3
 {% endhighlight %}
 
-This will  appear as 'AWS Virginia Large Centos' in the web console, but will need to be
escaped on the command line as:  `AWS\ Virginia\ Large\ Centos`.
+In the above example, if you deploy to `location: named:my-aws`,
+Brooklyn will get `VAL3` for `KEY`;
+this overrides `VAL2` which applies by default to all `aws-ec2` locations,
+which in turn overrides `VAL1`, which applies to all jclouds locations. 
 
-See the Getting Started [template brooklyn.properties](../start/brooklyn.properties) for
more examples of using cloud endpoints.
 
+### Localhost
 
-## Fixed Infrastructure
+If passwordless ssh login to `localhost` is enabled on your machine,
+you should be able to deploy blueprints with no special configuration,
+just by specifying `location: localhost` in YAML.
 
-Bringing your own nodes (BYON) to Brooklyn is straightforward.
+If you use a passpharse or prefer a different key, these can be configured as follows: 
 
-You will need the IP addresses of the nodes and the access credentials. Both SSH and password
based login are supported.
+{% highlight bash %}
+brooklyn.location.localhost.privateKeyFile=~/.ssh/brooklyn_key
+brooklyn.location.localhost.privateKeyPassphrase=s3cr3tPASSPHRASE
+{% endhighlight %}
 
-### Example: On-Prem Iron
+If you encounter issues or for more information, see [SSH Keys Localhost Setup](ssh-keys.html#localhost-setup).

 
-{% highlight bash %}
-## Snippet from ~/.brooklyn/brooklyn.properties.
 
-# Use the byon prefix, and provide the IP addresss (or IP ranges)
-brooklyn.location.named.On-Prem\ Iron\ Example=byon:(hosts="10.9.1.1,10.9.1.2,produser2@10.9.2.{10,11,20-29}")
-brooklyn.location.named.On-Prem\ Iron\ Example.user=produser1
-brooklyn.location.named.On-Prem\ Iron\ Example.privateKeyFile=~/.ssh/produser_id_rsa
-brooklyn.location.named.On-Prem\ Iron\ Example.privateKeyPassphrase=s3cr3tpassphrase
 
+### BYON
+
+"Bring-your-own-nodes" mode is useful in production, were machines have been provisioned
by someone else, 
+and during testing, to cut down provisioning time.
+
+To deploy to machines with known IP's in a blueprint, use the following syntax:
+
+{% highlight yaml %}
+location:
+  byon:
+    user: brooklyn
+    privateKeyFile: ~/.ssh/brooklyn.pem
+    hosts:
+    - 192.168.0.18
+    - 192.168.0.19
 {% endhighlight %}
 
+Some of the login properties as described above for jclouds are supported,
+but not `loginUser` (as no users are created), and not any of the
+VM creation parameters such as `minRam` and `imageId`.
+(These clearly do not apply in the same way, and they are *not* 
+by default treated as constraints, although an entity can confirm these
+where needed.)
+As before, if the brooklyn user and its default key are authorized for the hosts,
+those fields can be omitted.
 
-## Advanced Options
+Named locations can also be configured in your `brooklyn.properties`,
+using the format ``byon:(key=value,key2=value2)``.
+For convenience, for hosts wildcard globs are supported.
 
-Unusual provider? 'Featureful' API? Brooklyn can cope.
+{% highlight bash %}
+brooklyn.location.named.On-Prem\ Iron\ Example=byon:(hosts="10.9.1.1,10.9.1.2,produser2@10.9.2.{10,11,20-29}")
+brooklyn.location.named.On-Prem\ Iron\ Example.user=produser1
+brooklyn.location.named.On-Prem\ Iron\ Example.privateKeyFile=~/.ssh/produser_id_rsa
+brooklyn.location.named.On-Prem\ Iron\ Example.privateKeyPassphrase=s3cr3tpassphrase
+{% endhighlight %}
 
-[This spreadsheet](https://docs.google.com/a/cloudsoftcorp.com/spreadsheet/ccc?key=0Avy7Tdf2EOIqdGQzSlNiT2M0V19SejBScDhSdzMtT2c)
provides explanation, guidance, and examples for the majority of location options.
 
 
+### Other Location Topics
 
+* [More Locations](more-locations.md)
+* [SSH Keys](ssh-keys.md)

http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/5cf0666f/docs/guide/ops/locations/more-locations.md
----------------------------------------------------------------------
diff --git a/docs/guide/ops/locations/more-locations.md b/docs/guide/ops/locations/more-locations.md
new file mode 100644
index 0000000..35e2398
--- /dev/null
+++ b/docs/guide/ops/locations/more-locations.md
@@ -0,0 +1,55 @@
+---
+title: More Locations
+layout: website-normal
+children:
+- { section: Single Host }
+- { section: The Multi Location }
+- { section: The Server Pool }
+---
+
+Some additional location types are supported for specialized situations:
+
+### Single Host
+
+The spec `host`, taking a string argument (the address) or a map (`host`, `user`, `password`,
etc.),
+provides a convenient syntax when specifying a single host.
+For example:
+
+{% highlight yaml %}
+services:
+- type: brooklyn.entity.webapp.jboss.JBoss7Server 
+  location:
+    host: 192.168.0.1
+{% endhighlight %}
+
+Or, in `brooklyn.properties`, set `brooklyn.location.named.host1=host:(192.168.0.1)`.
+
+
+### The Multi Location
+
+The spec `multi` allows multiple locations, specified as `targets`,
+to be combined and treated as one location.
+When the first target is full, the next is tried, and so on:
+
+{% highlight yaml %}
+location:
+  multi:
+    targets:
+    - byon:(hosts=192.168.0.1)
+    - jclouds:aws-ec2:
+      identity: acct1
+    - jclouds:aws-ec2:
+      identity: acct2      
+{% endhighlight %}
+
+The example above provisions the first node to `192.168.0.1`,
+then it provisions into `acct1` at Amazon if possible,
+and then to `acct2`.
+
+
+
+### The Server Pool
+
+The {% include java_link.html package_path="brooklyn/entity/pool" project_subpath="software/base"
%}
+entity type allows defining an entity which becomes available as a location.
+

http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/5cf0666f/docs/guide/ops/locations/ssh-keys.md
----------------------------------------------------------------------
diff --git a/docs/guide/ops/locations/ssh-keys.md b/docs/guide/ops/locations/ssh-keys.md
new file mode 100644
index 0000000..6839f62
--- /dev/null
+++ b/docs/guide/ops/locations/ssh-keys.md
@@ -0,0 +1,60 @@
+---
+title: SSH Keys
+layout: website-normal
+---
+
+SSH keys are one of the simplest and most secure ways to access remote servers.
+They consist of two parts:
+
+* A private key (e.g. `id_rsa`) which is known only to one party or group
+  
+* A public key (e.g. `id_rsa.pub`) which can be given to anyone and everyone,
+  and which can be used to confirm that a party has a private key
+  (or has signed a communication with the private key)
+  
+In this way, someone -- such as you -- can have a private key,
+and can install a public key on a remote machine (in an `authorized_keys` file)
+for secure automated access.
+Commands such as `ssh` (and Brooklyn) can log in without
+revealing the private key to the remote machine,
+the remote machine can confirm it is you accessing it (if no one else has the private key),
+and no one snooping on the network can decrypt of any of the traffic.
+ 
+
+### Creating an SSH Key
+
+If you don't have an SSH key, create one with:
+
+{% highlight bash %}
+$ ssh-keygen -t rsa -N "" -f ~/.ssh/id_rsa
+{% endhighlight %}
+
+
+### Localhost Setup
+
+If you want to deploy to `localhost`, ensure that you have a public and private key,
+and that your key is authorized for ssh access:
+
+{% highlight bash %}
+# _Appends_ id_rsa.pub to authorized_keys. Other keys are unaffected.
+$ cat ~/.ssh/id_rsa.pub >> ~/.ssh/authorized_keys
+{% endhighlight %}
+
+You should be able to run `ssh localhost` without any password required.
+
+**Got a passphrase?** Set `brooklyn.location.localhost.privateKeyPassphrase`
+as described [here](index.html#os-setup)
+
+**MacOS user?** In addition to the above, enable "Remote Login" in "System Preferences >
Sharing".
+
+
+### Potential Problems
+
+* `~/.ssh/` or files in that directory too open: they should be visible only to the user
(apart from public keys),
+  both on the source machine and the target machine
+ 
+* Sometimes machines are configured with different sets of support SSL/TLS versions and ciphers;
+  if command-line `ssh` and `scp` work, but Brooklyn/java does not, check the versions enabled
in Java and on both servers.
+
+* Missing entropy: creating and using ssh keys requires randomness available on the servers,
+  usually in `/dev/random`; see [here]({{ site.path.website }}/documentation/increase-entropy.html)
for more information

http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/5cf0666f/docs/guide/ops/persistence/index.md
----------------------------------------------------------------------
diff --git a/docs/guide/ops/persistence/index.md b/docs/guide/ops/persistence/index.md
index 819e182..cbb3112 100644
--- a/docs/guide/ops/persistence/index.md
+++ b/docs/guide/ops/persistence/index.md
@@ -1,6 +1,13 @@
 ---
 title: Persistence
 layout: website-normal
+children:
+- { section: Command Line Options }
+- { section: File-based Persistence }
+- { section: Object Store Persistence }
+- { section: Rebinding to State }
+- { section: High Availability }
+- { section: Writing Persistable Code }
 ---
 
 Brooklyn can be configured to persist its state so that the Brooklyn server can be restarted,

@@ -92,8 +99,8 @@ brooklyn launch --persist auto --persistenceDir myContainerName --persistenceLoc
 {% endhighlight %}
 
 
-Rebind
-------
+Rebinding to State
+------------------
 
 When Brooklyn starts up pointing at existing state, it will recreate the entities, locations

 and policies based on that persisted state.
@@ -104,8 +111,7 @@ HTTP or JMX). This new state will be reported in the web-console and can
also tr
 any registered policies.
 
 
-Copying Persistence State
--------------------------
+## CLI Commands for Copying State
 
 Brooklyn includes a command to copy persistence state easily between two locations.
 The `copy-state` CLI command takes the following arguments:
@@ -122,10 +128,11 @@ The `copy-state` CLI command takes the following arguments:
   The local transformations file to be applied to the copy of the data before uploading it.
 
 
-Handling Rebind Failures
-------------------------
-If rebind were to fail for any reason, details of the underlying failures will be reported

-in the brooklyn.debug.log. There are several approaches to resolving problems.
+## Handling Rebind Failures
+
+If rebind fails fail for any reason, details of the underlying failures will be reported

+in the `brooklyn.debug.log`. There are several approaches to resolving problems.
+
 
 ### Determine Underlying Cause
 

http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/5cf0666f/docs/style/css/_code_blocks.scss
----------------------------------------------------------------------
diff --git a/docs/style/css/_code_blocks.scss b/docs/style/css/_code_blocks.scss
index 269c6a0..dd39dd8 100644
--- a/docs/style/css/_code_blocks.scss
+++ b/docs/style/css/_code_blocks.scss
@@ -41,6 +41,9 @@ code {
     padding: 4px 4px 2px 4px;
     border-radius: 3px;
 }
+a code {
+  color: inherit;
+}
 
 .nowrap { @include nowrap(); }
 

http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/5cf0666f/docs/website/documentation/increase-entropy.md
----------------------------------------------------------------------
diff --git a/docs/website/documentation/increase-entropy.md b/docs/website/documentation/increase-entropy.md
index bd0e8ea..53d5768 100644
--- a/docs/website/documentation/increase-entropy.md
+++ b/docs/website/documentation/increase-entropy.md
@@ -1,5 +1,5 @@
 ---
-title: Increase entropy
+title: Increase Entropy
 layout: website-normal
 ---
 If you are installing AMP on a virtual machine, you may find it useful to increase the Linux
kernel entropy to speed up the ssh connections to the managed entities. You can install and
configure `rng-tools` or just use /dev/urandom`.


Mime
View raw message