You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@brooklyn.apache.org by al...@apache.org on 2016/03/10 11:32:26 UTC
[01/10] brooklyn-docs git commit: Fixed YAML in content bug
Repository: brooklyn-docs
Updated Branches:
refs/heads/master bf43bd004 -> ae8b0abb3
Fixed YAML in content bug
Project: http://git-wip-us.apache.org/repos/asf/brooklyn-docs/repo
Commit: http://git-wip-us.apache.org/repos/asf/brooklyn-docs/commit/f000a31a
Tree: http://git-wip-us.apache.org/repos/asf/brooklyn-docs/tree/f000a31a
Diff: http://git-wip-us.apache.org/repos/asf/brooklyn-docs/diff/f000a31a
Branch: refs/heads/master
Commit: f000a31a50abd4b8ac1c8a373ba6411df36b59bc
Parents: b5b2161
Author: Duncan Godwin <du...@cloudsoftcorp.com>
Authored: Mon Mar 7 15:48:49 2016 +0000
Committer: Duncan Godwin <du...@cloudsoftcorp.com>
Committed: Mon Mar 7 16:54:43 2016 +0000
----------------------------------------------------------------------
_plugins/page_structure.rb | 4 ++--
contributing/inline-children.md | 4 ++--
2 files changed, 4 insertions(+), 4 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/f000a31a/_plugins/page_structure.rb
----------------------------------------------------------------------
diff --git a/_plugins/page_structure.rb b/_plugins/page_structure.rb
index 07caf17..6b3a2a1 100644
--- a/_plugins/page_structure.rb
+++ b/_plugins/page_structure.rb
@@ -115,7 +115,7 @@ module PageStructureUtils
yamlContent['section_position'] = Integer::MAX
end
# if there's YAML, check it has the section_position tag and put it into child pages
- ($allPages ||= []) << ChildPage.new(yamlContent, $partitionedFileContent[2])
+ ($allPages ||= []) << ChildPage.new(yamlContent, $partitionedFileContent[2..-1].join('---'))
end
end
end
@@ -154,7 +154,7 @@ module PageStructureUtils
yamlContent = YAML.load($partitionedFileContent[1])
# if we can, use it
if yamlContent != nil && yamlContent != false
- $textContent = $partitionedFileContent[2]
+ $textContent = $partitionedFileContent[2..-1].join('---')
end
end
http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/f000a31a/contributing/inline-children.md
----------------------------------------------------------------------
diff --git a/contributing/inline-children.md b/contributing/inline-children.md
index d6270bb..08eaa38 100644
--- a/contributing/inline-children.md
+++ b/contributing/inline-children.md
@@ -29,11 +29,11 @@ The content from these inline sections can then be included in the page content
in an example from [/guide/ops/locations/index.md](https://github.com/apache/brooklyn-docs/blob/master/guide/ops/locations/index.md){:target="_blank"}:
<pre>
----
+---
title: Locations
layout: website-normal
check_directory_for_children: true
----
+---
Locations are the environments to which Brooklyn deploys applications, including:
[07/10] brooklyn-docs git commit: Merged conflicts from #19 & order
bug
Posted by al...@apache.org.
Merged conflicts from #19 & order bug
Project: http://git-wip-us.apache.org/repos/asf/brooklyn-docs/repo
Commit: http://git-wip-us.apache.org/repos/asf/brooklyn-docs/commit/5ee36ffd
Tree: http://git-wip-us.apache.org/repos/asf/brooklyn-docs/tree/5ee36ffd
Diff: http://git-wip-us.apache.org/repos/asf/brooklyn-docs/diff/5ee36ffd
Branch: refs/heads/master
Commit: 5ee36ffd47cbfd57433559322ae273092d42d6b3
Parents: f000a31
Author: Duncan Godwin <du...@cloudsoftcorp.com>
Authored: Tue Mar 8 10:14:16 2016 +0000
Committer: Duncan Godwin <du...@cloudsoftcorp.com>
Committed: Tue Mar 8 10:14:16 2016 +0000
----------------------------------------------------------------------
_plugins/page_structure.rb | 20 ++++-
guide/ops/locations/cloud-specific-setup.md | 88 --------------------
guide/ops/locations/clouds.md | 21 +++--
guide/ops/locations/index.md | 2 +
.../inheritance-and-named-locations.md | 2 +-
guide/ops/locations/localhost.md | 2 +-
guide/ops/locations/more-clouds.md | 8 +-
guide/ops/locations/more-locations.md | 54 ------------
guide/ops/locations/special-locations.md | 54 ++++++++++++
guide/ops/locations/ssh-keys.md | 2 +-
guide/ops/locations/vpc-issues.md | 32 -------
11 files changed, 95 insertions(+), 190 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/5ee36ffd/_plugins/page_structure.rb
----------------------------------------------------------------------
diff --git a/_plugins/page_structure.rb b/_plugins/page_structure.rb
index 6b3a2a1..d2e419b 100644
--- a/_plugins/page_structure.rb
+++ b/_plugins/page_structure.rb
@@ -45,6 +45,14 @@ module PageStructureUtils
yaml.sort{ |x,y| Gem::Version.new(x.yaml['section_position'].to_s) <=> Gem::Version.new(y.yaml['section_position'].to_s) }
end
##
+ # This goes through the hash looking for the keys for the different types of children
+ #
+ def self.getDefiningParameterFromHash(hash)
+ param_name = hash['path']
+ param_name = (param_name == nil ? hash['link'] : param_name)
+ (param_name == nil ? hash['section'] : param_name)
+ end
+ ##
# Sorts a list of yaml children, if there's no numbering, use the YAML order to create a numbering
# NOTE: doesn't alter the returned object as that seemed to break things downstream
#
@@ -57,12 +65,14 @@ module PageStructureUtils
if i.instance_of? String
position[i] = $major+"."+$minor.to_s
else
+ # get the key for this type of child
+ defining_param = getDefiningParameterFromHash(i)
if i['section_position'] == nil
- position[i['path']] = $major+"."+$minor.to_s
+ position[defining_param] = $major+"."+$minor.to_s
$minor += 1
else
# Store any major, start incrementing minor
- position[i['path']] = i['section_position'].to_s
+ position[defining_param] = i['section_position'].to_s
$major = i['section_position'].to_s
$minor = 1
end
@@ -75,12 +85,14 @@ module PageStructureUtils
if x.instance_of? String
$pos_x = position[x]
else
- $pos_x = position[x['path']]
+ defining_param = getDefiningParameterFromHash(x)
+ $pos_x = position[defining_param]
end
if y.instance_of? String
$pos_y = position[y]
else
- $pos_y = position[y['path']]
+ defining_param = getDefiningParameterFromHash(y)
+ $pos_y = position[defining_param]
end
Gem::Version.new($pos_x.to_s) <=> Gem::Version.new($pos_y.to_s)
}
http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/5ee36ffd/guide/ops/locations/cloud-specific-setup.md
----------------------------------------------------------------------
diff --git a/guide/ops/locations/cloud-specific-setup.md b/guide/ops/locations/cloud-specific-setup.md
deleted file mode 100644
index 56a701a..0000000
--- a/guide/ops/locations/cloud-specific-setup.md
+++ /dev/null
@@ -1,88 +0,0 @@
----
-section: Cloud Specific Setup
-section_type: inline
-section_position: 1.1
----
-
-### Cloud Specific Setup
-
-To connect to a Cloud, Brooklyn requires appropriate credentials. These comprise the "identity" and
-"credential" in Brooklyn terminology.
-
-For private clouds (and for some clouds being targeted using a standard API), the "endpoint"
-must also be specified, which is the cloud's URL.
-
-The [jclouds guides](https://jclouds.apache.org/guides) includes documentation on configuring
-different clouds.
-
-
-#### AWS
-
-##### Credentials
-
-AWS has an "access key" and a "secret key", which correspond to Brooklyn's identity and credential
-respectively.
-
-These keys are the way for any programmatic mechanism to access the AWS API.
-
-To generate an access key and a secret key, see [jclouds instructions](http://jclouds.apache.org/guides/aws)
-and [AWS IAM instructions](http://docs.aws.amazon.com/IAM/latest/UserGuide/ManagingCredentials.html).
-
-An example of the expected format is shown below:
-
- brooklyn.location.jclouds.aws-ec2.identity=ABCDEFGHIJKLMNOPQRST
- brooklyn.location.jclouds.aws-ec2.credential=abcdefghijklmnopqrstu+vwxyzabcdefghijklm
-
-
-##### Tidying up after jclouds
-
-Security groups are not always deleted by jclouds. This is due to a limitation in AWS (see
-https://issues.apache.org/jira/browse/JCLOUDS-207). In brief, AWS prevents the security group
-being deleted until there are no VMs using it. However, there is eventual consistency for
-recording which VMs still reference those security groups. After deleting the VM, it can sometimes
-take several minutes before the security group can be deleted. jclouds retries for 3 seconds, but
-does not block for longer.
-
-There is utility written by Cloudsoft for deleting these unused resources:
-http://www.cloudsoftcorp.com/blog/2013/03/tidying-up-after-jclouds.
-
-
-#### Google Compute Engine
-
-##### Credentials
-
-Google Compute Engine (GCE) uses a service account e-mail address for the identity, and a private key
-as the credential.
-
-To obtain these from GCE, see the [jclouds instructions](https://jclouds.apache.org/guides/google).
-
-An example of the expected format is shown below (note the credential is one long line,
-with `\n` to represent the new line characters):
-
- brooklyn.location.jclouds.google-compute-engine.identity=123456789012@developer.gserviceaccount.com
- brooklyn.location.jclouds.google-compute-engine.credential=-----BEGIN RSA PRIVATE KEY-----\nabcdefghijklmnopqrstuvwxyznabcdefghijk/lmnopqrstuvwxyzabcdefghij\nabcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrstuvwxyzabcdefghij+lm\nnopqrstuvwxyzabcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrstuvwxyzabcdefghijklm\nnopqrstuvwxyzabcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrstuvwxy\nzabcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrstuvwxyzabcdefghijk\nlmnopqrstuvwxyzabcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrstuvw\nxyzabcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrstuvwxyzabcdefghi\njklmnopqrstuvwxyzabcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrstu\nvwxyzabcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrstuvwxyzabcdefg\nhijklmnopqrstuvwxyzabcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrs\ntuvwxyzabcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrstuvwxyzabcde\nfghijklmnopqrstuvwxyzabcdefghijklmnopqrstuvw\n-----END RSA PRIVATE KEY-----
-
-
-##### Quotas
-
-GCE accounts can have low default [quotas](https://cloud.google.com/compute/docs/resource-quotas).
-
-It is easy to requesta quota increase by submitting a [quota increase form](https://support.google.com/cloud/answer/6075746?hl=en).
-
-
-##### Networks
-
-GCE accounts often have a limit to the number of networks that can be created. One work around
-is to manually create a network with the required open ports, and to refer to that named network
-in Brooklyn's location configuration.
-
-To create a network, see [GCE network instructions](https://cloud.google.com/compute/docs/networking#networks_1).
-
-For example, for dev/demo purposes an "everything" network could be created that opens all ports.
-
-| Name | everything |
-| Description | opens all tcp ports |
-| Source IP Ranges | 0.0.0.0/0 |
-| Allowed protocols and ports | tcp:0-65535 and udp:0-65535 |
-
-
http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/5ee36ffd/guide/ops/locations/clouds.md
----------------------------------------------------------------------
diff --git a/guide/ops/locations/clouds.md b/guide/ops/locations/clouds.md
index 90f9eb4..cac9083 100644
--- a/guide/ops/locations/clouds.md
+++ b/guide/ops/locations/clouds.md
@@ -1,7 +1,7 @@
---
section: Clouds
section_type: inline
-section_position: 1.0
+section_position: 1
---
### Clouds
@@ -37,8 +37,12 @@ brooklyn.location.jclouds.aws-ec2.credential=s3cr3tsq1rr3ls3cr3tsq1rr3ls3cr3tsq1
And in this case you can reference the location in YAML with `location: jclouds:aws-ec2`.
-The Getting Started [template brooklyn.properties]({{ site.path.guide }}/start/brooklyn.properties) contains more examples
-of configuring cloud endpoints, including information on credential types used in different clouds.
+Brooklyn irons out many of the differences between clouds so that blueprints run similarly
+in a wide range of locations, including setting up access and configuring images and machine specs.
+The configuration options are described in more detail below.
+
+In some cases, cloud providers have special features or unusual requirements.
+These are outlined in **[More Details for Specific Clouds](more-clouds.html)**.
#### OS Initial Login and Setup
@@ -65,7 +69,8 @@ Following a successful logon, Brooklyn performs the following steps to configure
1. 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;
+ (override with `privateKeyFile`; or if there is no `id_{r,d}sa{,.pub}` an ad hoc keypair will be generated
+ for the regular Brooklyn user;
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`)
@@ -96,8 +101,10 @@ For more keys and more detail on the keys below, see
- 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)
-- A specific existing key pair known at the cloud to use can be specified with `keyPair`
- (selected clouds only)
+- Where a key pair is registered with a target cloud for logging in to machines,
+ Brooklyn can be configured to request this when provisioning VMs by setting `keyPair` (selected clouds only).
+ Note that if this `keyPair` does not correspond your default `~/.ssh/id_rsa`, you must typically
+ also specify the corresponding `loginUser.privateKeyFile` as a file or URL accessible from Brooklyn.
- A specific VM name (often the hostname) base to be used can be specified by setting `groupId`.
By default, this name is constructed based on the entity which is creating it,
@@ -187,7 +194,7 @@ For more keys and more detail on the keys below, see
This setting prevents scripts executed on the VMs from being deleted on completion.
Note that some scripts run periodically so this can eventually fill a disk; it should only be used for dev/test.
-###### Custom template options
+###### Custom Template Options
jclouds supports many additional options for configuring how a virtual machine is created and deployed, many of which
are for cloud-specific features and enhancements. Brooklyn supports some of these, but if what you are looking for is
http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/5ee36ffd/guide/ops/locations/index.md
----------------------------------------------------------------------
diff --git a/guide/ops/locations/index.md b/guide/ops/locations/index.md
index dc0c1dc..29a80e4 100644
--- a/guide/ops/locations/index.md
+++ b/guide/ops/locations/index.md
@@ -1,6 +1,8 @@
---
title: Locations
layout: website-normal
+children:
+- { path: location-customizers.md, section_position: 8 }
check_directory_for_children: true
---
http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/5ee36ffd/guide/ops/locations/inheritance-and-named-locations.md
----------------------------------------------------------------------
diff --git a/guide/ops/locations/inheritance-and-named-locations.md b/guide/ops/locations/inheritance-and-named-locations.md
index 9854fea..53fe904 100644
--- a/guide/ops/locations/inheritance-and-named-locations.md
+++ b/guide/ops/locations/inheritance-and-named-locations.md
@@ -2,7 +2,7 @@
section: Inheritance and Named Locations
title: Named Locations
section_type: inline
-section_position: 2
+section_position: 3
---
### Inheritance and Named Locations
http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/5ee36ffd/guide/ops/locations/localhost.md
----------------------------------------------------------------------
diff --git a/guide/ops/locations/localhost.md b/guide/ops/locations/localhost.md
index 86ef5b5..27d19bf 100644
--- a/guide/ops/locations/localhost.md
+++ b/guide/ops/locations/localhost.md
@@ -1,6 +1,6 @@
---
section: Localhost
-section_position: 3
+section_position: 6
section_type: inline
---
http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/5ee36ffd/guide/ops/locations/more-clouds.md
----------------------------------------------------------------------
diff --git a/guide/ops/locations/more-clouds.md b/guide/ops/locations/more-clouds.md
index 5b776df..8e95625 100644
--- a/guide/ops/locations/more-clouds.md
+++ b/guide/ops/locations/more-clouds.md
@@ -1,8 +1,12 @@
---
-title: More Details on Specific Clouds
-layout: website-normal
+section: More Details on Specific Clouds
+title: More on Clouds
+section_type: inline
+section_position: 2
---
+### More Details on Specific Clouds
+
To connect to a Cloud, Brooklyn requires appropriate credentials. These comprise the `identity` and
`credential` in Brooklyn terminology.
http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/5ee36ffd/guide/ops/locations/more-locations.md
----------------------------------------------------------------------
diff --git a/guide/ops/locations/more-locations.md b/guide/ops/locations/more-locations.md
deleted file mode 100644
index 2ed2c83..0000000
--- a/guide/ops/locations/more-locations.md
+++ /dev/null
@@ -1,54 +0,0 @@
----
-section: Specialized Locations
-section_position: 5
-section_type: inline
----
-
-### Specialized Locations
-
-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: org.apache.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 class_name="ServerPool" package_path="org/apache/brooklyn/entity/machine/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/brooklyn-docs/blob/5ee36ffd/guide/ops/locations/special-locations.md
----------------------------------------------------------------------
diff --git a/guide/ops/locations/special-locations.md b/guide/ops/locations/special-locations.md
new file mode 100644
index 0000000..8f19fa4
--- /dev/null
+++ b/guide/ops/locations/special-locations.md
@@ -0,0 +1,54 @@
+---
+section: Specialized Locations
+section_position: 7
+section_type: inline
+---
+
+### Specialized Locations
+
+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: org.apache.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 class_name="ServerPool" package_path="org/apache/brooklyn/entity/machine/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/brooklyn-docs/blob/5ee36ffd/guide/ops/locations/ssh-keys.md
----------------------------------------------------------------------
diff --git a/guide/ops/locations/ssh-keys.md b/guide/ops/locations/ssh-keys.md
index e49d031..03ee84e 100644
--- a/guide/ops/locations/ssh-keys.md
+++ b/guide/ops/locations/ssh-keys.md
@@ -1,6 +1,6 @@
---
section: SSH Keys
-section_position: 3.1
+section_position: 5
section_type: inline
---
http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/5ee36ffd/guide/ops/locations/vpc-issues.md
----------------------------------------------------------------------
diff --git a/guide/ops/locations/vpc-issues.md b/guide/ops/locations/vpc-issues.md
deleted file mode 100644
index b2b362b..0000000
--- a/guide/ops/locations/vpc-issues.md
+++ /dev/null
@@ -1,32 +0,0 @@
-
-### AWS VPC issues which may affect users with older AWS accounts
-
-AWS now has different default behaviour depending on the age of your AWS account and whether you used the target region before, or during, 2013.
-In this case VM provisioning may fail with an error like:
-
-{% highlight text %}
-
-Detected that your EC2 account is a legacy 'classic' account, but the recommended instance type requires VPC.
-You can specify the 'eu-central-1' region to avoid this problem, or you can specify a classic-compatible instance type,
-or you can specify a subnet to use with 'networkName'
-taking care that the subnet auto-assigns public IP's and allows ingress on all ports,
-as Brooklyn does not currently configure security groups for non-default VPC's;
-or setting up Brooklyn to be in the subnet or have a jump host or other subnet access configuration).
-For more information on VPC vs classic see http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-vpc.html.
-
-{% endhighlight %}
-
-Specifically, there are issues with the certain AMIs and instance types. If these are specified or a recommended
-by brooklyn then you may see the above error. There are a few options for fixing this:
-
-- specify a different region which does not support EC2-classic.
- You can check this on the AWS console under "Supported Platforms.
- Frankfurt (eu-central-1) is guaranteed to be VPC only.
-
-- specify an instance type that is compatible with ec2-classic.
- Instance types C4, M4, T2 are only supported in VPC so should not be used.
- This is described [here](index.html#vm-creation)
-
-- create a subnet to use with the instance. Ensure that the subnet is set to auto-assign public IPs
- and allows ingress on all ports. Brooklyn cannot currently do this for you.
- Use the networkName parameter to specify this value in your blueprint.
\ No newline at end of file
[09/10] brooklyn-docs git commit: Clarified Numbering
Posted by al...@apache.org.
Clarified Numbering
Project: http://git-wip-us.apache.org/repos/asf/brooklyn-docs/repo
Commit: http://git-wip-us.apache.org/repos/asf/brooklyn-docs/commit/89843345
Tree: http://git-wip-us.apache.org/repos/asf/brooklyn-docs/tree/89843345
Diff: http://git-wip-us.apache.org/repos/asf/brooklyn-docs/diff/89843345
Branch: refs/heads/master
Commit: 898433458a47c4a93240ec4c18e6ec94d1d3a71a
Parents: e04b38e
Author: Duncan Godwin <du...@cloudsoftcorp.com>
Authored: Wed Mar 9 15:38:01 2016 +0000
Committer: Duncan Godwin <du...@cloudsoftcorp.com>
Committed: Wed Mar 9 15:38:01 2016 +0000
----------------------------------------------------------------------
_plugins/page_structure.rb | 1 +
contributing/ordering.md | 6 ++++--
2 files changed, 5 insertions(+), 2 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/89843345/_plugins/page_structure.rb
----------------------------------------------------------------------
diff --git a/_plugins/page_structure.rb b/_plugins/page_structure.rb
index d2e419b..b1697bd 100644
--- a/_plugins/page_structure.rb
+++ b/_plugins/page_structure.rb
@@ -64,6 +64,7 @@ module PageStructureUtils
yaml.each do |i|
if i.instance_of? String
position[i] = $major+"."+$minor.to_s
+ $minor += 1
else
# get the key for this type of child
defining_param = getDefiningParameterFromHash(i)
http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/89843345/contributing/ordering.md
----------------------------------------------------------------------
diff --git a/contributing/ordering.md b/contributing/ordering.md
index ff2a0f9..428360c 100644
--- a/contributing/ordering.md
+++ b/contributing/ordering.md
@@ -14,8 +14,10 @@ For inline children, sourced using `check_directory_for_children: true`, this `s
The format for `section_position` is that of software versioning, i.e `A.B... Z` where A, B etc are numbers of decreasing value. Position `1.1.0` would appear
before version `1.0.4` for example. This allows an infinite number of sub pages between each `section_position`.
-Any un-versioned pages are automatically numbered to follow on from the last numbered page, or `1.1` if no pages are yet numbered. For
-example, if a numbered page, `1.4` is followed by a non-numbered page, the non-numbered page would be auto-numbered as `1.4.1`.
+Any un-versioned pages are automatically numbered to add a new minor version from the last page if that was numbered or increment the minor
+if it was not. If no pages are yet numbered, the numbering is started at `1.1`. For example, if a numbered page, `1.4` is followed by a
+non-numbered page, the non-numbered page would be auto-numbered as `1.4.1`. If this page is followed by another non-numbered page it would
+be auto-numbered as `1.4.2`.
For example, a set of children pages numbered like this:
[10/10] brooklyn-docs git commit: This closes #20
Posted by al...@apache.org.
This closes #20
Project: http://git-wip-us.apache.org/repos/asf/brooklyn-docs/repo
Commit: http://git-wip-us.apache.org/repos/asf/brooklyn-docs/commit/ae8b0abb
Tree: http://git-wip-us.apache.org/repos/asf/brooklyn-docs/tree/ae8b0abb
Diff: http://git-wip-us.apache.org/repos/asf/brooklyn-docs/diff/ae8b0abb
Branch: refs/heads/master
Commit: ae8b0abb342505b2c008d14b0861a848c2324622
Parents: bf43bd0 8984334
Author: Aled Sage <al...@gmail.com>
Authored: Thu Mar 10 10:31:59 2016 +0000
Committer: Aled Sage <al...@gmail.com>
Committed: Thu Mar 10 10:31:59 2016 +0000
----------------------------------------------------------------------
README.md | 8 +-
_plugins/page_structure.rb | 220 ++++++++++
_plugins/site_structure.rb | 29 ++
contributing/index.md | 15 +
contributing/inline-children.md | 54 +++
contributing/ordering.md | 48 ++
contributing/pdf-manual.md | 58 +++
contributing/site-structure.md | 29 ++
guide/ops/locations/byon.md | 74 ++++
guide/ops/locations/clouds.md | 248 +++++++++++
guide/ops/locations/index.md | 439 +------------------
.../inheritance-and-named-locations.md | 80 ++++
guide/ops/locations/localhost.md | 33 ++
guide/ops/locations/more-clouds.md | 8 +-
guide/ops/locations/more-locations.md | 55 ---
guide/ops/locations/special-locations.md | 54 +++
guide/ops/locations/ssh-keys.md | 13 +-
guide/ops/locations/vpc-issues.md | 32 --
guide/start/policies.md | 95 +++-
style/css/singlePage.css | 12 +
20 files changed, 1057 insertions(+), 547 deletions(-)
----------------------------------------------------------------------
[04/10] brooklyn-docs git commit: Fixed single page bugs
Posted by al...@apache.org.
Fixed single page bugs
Project: http://git-wip-us.apache.org/repos/asf/brooklyn-docs/repo
Commit: http://git-wip-us.apache.org/repos/asf/brooklyn-docs/commit/a594c062
Tree: http://git-wip-us.apache.org/repos/asf/brooklyn-docs/tree/a594c062
Diff: http://git-wip-us.apache.org/repos/asf/brooklyn-docs/diff/a594c062
Branch: refs/heads/master
Commit: a594c062b6986492c1f3bf853b3e1cc49e776cd5
Parents: cfa914d
Author: Duncan Godwin <du...@cloudsoftcorp.com>
Authored: Fri Mar 4 14:25:11 2016 +0000
Committer: Duncan Godwin <du...@cloudsoftcorp.com>
Committed: Mon Mar 7 16:54:43 2016 +0000
----------------------------------------------------------------------
_plugins/page_structure.rb | 65 +++++++++++++++++-----------
guide/index.md | 4 +-
guide/start/policies.md | 95 ++++++++++++++++++++++++++++++++++-------
style/css/singlePage.css | 12 ++++++
4 files changed, 134 insertions(+), 42 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/a594c062/_plugins/page_structure.rb
----------------------------------------------------------------------
diff --git a/_plugins/page_structure.rb b/_plugins/page_structure.rb
index 2833be3..4e01559 100644
--- a/_plugins/page_structure.rb
+++ b/_plugins/page_structure.rb
@@ -10,6 +10,12 @@ require "kramdown"
module PageStructureUtils
+ class MyHash < Hash
+ def to_s
+ "cheese"
+ end
+ end
+
class ChildPage
def initialize(yaml, content)
@yaml=yaml
@@ -48,33 +54,42 @@ module PageStructureUtils
# Sorts a list of yaml children, if there's no numbering, use the YAML order to create a numbering
#
def self.sortYAMLSectionPositions(yaml)
-# puts "a > "+yaml.to_s
- hashArray = []
- $major = "1"
- $minor = 1
- # first check all the child pages are numbered, if not, number them in the order they are
- yaml.each do |i|
- hash = {}
- # if it's a string, convert it to a hash
- if i.instance_of? String
- hash = { "path" => i }
- else
- hash = i
- end
- if i['section_position'] == nil
- hash['section_position'] = $major+"."+$minor.to_s
- $minor += 1
- else
- # Store any major, start incrementing minor
- $major = i['section_position'].to_s
+ position = Hash.new
+ $major = "1"
$minor = 1
+ # go through and generate a position for each
+ yaml.each do |i|
+ if i.instance_of? String
+ position[i] = $major+"."+$minor.to_s
+ else
+ if i['section_position'] == nil
+ position[i['path']] = $major+"."+$minor.to_s
+ $minor += 1
+ else
+ # Store any major, start incrementing minor
+ position[i['path']] = i['section_position'].to_s
+ $major = i['section_position'].to_s
+ $minor = 1
+ end
+ end
+ end
+ # sort on the position (NB: sort! for in-place sorting)
+ yaml.sort!{ |x,y|
+ $pos_x = nil
+ $pos_y = nil
+ if x.instance_of? String
+ $pos_x = position[x]
+ else
+ $pos_x = position[x['path']]
+ end
+ if y.instance_of? String
+ $pos_y = position[y]
+ else
+ $pos_y = position[y['path']]
+ end
+ Gem::Version.new($pos_x.to_s) <=> Gem::Version.new($pos_y.to_s)
+ }
end
- hashArray << hash
- end
- # return the comparison between the versions (NB: sort! for in-place sorting)
- hashArray.sort!{ |x,y| Gem::Version.new(x['section_position'].to_s) <=> Gem::Version.new(y['section_position'].to_s) }
-# puts "2 > "+hashArray.to_s
- end
##
# This function looks at all the *.md files at the YAML in the headers and produces a list of children ordered by section_position
http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/a594c062/guide/index.md
----------------------------------------------------------------------
diff --git a/guide/index.md b/guide/index.md
index cdb3b46..5c7ced3 100644
--- a/guide/index.md
+++ b/guide/index.md
@@ -5,12 +5,12 @@ breadcrumbs:
- /website/documentation/index.md
- index.md
children:
-- { path: /guide/start/index.md }
+- { 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/ops/index.md }
+- { path: /guide/ops/index.md, section_position: 2 }
- { path: /guide/misc/index.md }
---
http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/a594c062/guide/start/policies.md
----------------------------------------------------------------------
diff --git a/guide/start/policies.md b/guide/start/policies.md
index edef90c..a12e77f 100644
--- a/guide/start/policies.md
+++ b/guide/start/policies.md
@@ -16,6 +16,69 @@ review and/or change the the location where the application will be deployed.
You will need four machines for this example: one for the load-balancer (nginx), and three for the
Tomcat cluster (but you can reduce this by changing the `maxPoolSize` below).
+<div class="usermanual-pdf-include" style="display: none;">
+{% highlight yaml %}
+name: Tomcat Cluster
+
+location:
+ byon:
+ user: vagrant
+ password: vagrant
+ hosts:
+ - 10.10.10.101
+ - 10.10.10.102
+ - 10.10.10.103
+ - 10.10.10.104
+
+services:
+- type: org.apache.brooklyn.entity.group.DynamicCluster
+ name: Cluster
+ id: cluster
+ brooklyn.config:
+ initialSize: 1
+ memberSpec:
+ $brooklyn:entitySpec:
+ type: org.apache.brooklyn.entity.webapp.tomcat.TomcatServer
+ name: Tomcat Server
+ brooklyn.config:
+ wars.root: http://search.maven.org/remotecontent?filepath=org/apache/brooklyn/example/brooklyn-example-hello-world-webapp/0.8.0-incubating/brooklyn-example-hello-world-webapp-0.8.0-incubating.war
+
+ brooklyn.policies:
+ - type: org.apache.brooklyn.policy.ha.ServiceRestarter
+ brooklyn.config:
+ failOnRecurringFailuresInThisDuration: 5m
+ brooklyn.enrichers:
+ - type: org.apache.brooklyn.policy.ha.ServiceFailureDetector
+ brooklyn.config:
+ entityFailed.stabilizationDelay: 30s
+
+ brooklyn.policies:
+ - type: org.apache.brooklyn.policy.ha.ServiceReplacer
+
+ - type: org.apache.brooklyn.policy.autoscaling.AutoScalerPolicy
+ brooklyn.config:
+ metric: webapp.reqs.perSec.perNode
+ metricUpperBound: 3
+ metricLowerBound: 1
+ resizeUpStabilizationDelay: 2s
+ resizeDownStabilizationDelay: 1m
+ maxPoolSize: 3
+
+ brooklyn.enrichers:
+ - type: org.apache.brooklyn.enricher.stock.Aggregator
+ brooklyn.config:
+ enricher.sourceSensor: $brooklyn:sensor("webapp.reqs.perSec.windowed")
+ enricher.targetSensor: $brooklyn:sensor("webapp.reqs.perSec.perNode")
+ enricher.aggregating.fromMembers: true
+ transformation: average
+
+- type: org.apache.brooklyn.entity.proxy.nginx.NginxController
+ name: Load Balancer (nginx)
+ brooklyn.config:
+ loadbalancer.serverpool: $brooklyn:entity("cluster")
+ nginx.sticky: false
+{% endhighlight %}
+</div>
<!-- WARNING: if modifying either mycluster.yaml or the yaml below, be sure to keep them both in-sync -->
@@ -194,21 +257,23 @@ Tomcat cluster (but you can reduce this by changing the `maxPoolSize` below).
See blueprint-tour.md for where this CSS/javascript was copied from.
{% endcomment %}
-$(function() {
- maxCodeWidth = Math.max.apply(Math, $(".annotated_blueprint div.block > div:last-child").map(function(){ return this.scrollWidth; }).get());
- $(".annotated_blueprint div.block").width(maxCodeWidth);
-})
-
-$(".annotated_blueprint .code_scroller .initial_notice > div").height($(".annotated_blueprint .code_scroller .code_viewer").height());
-$(".annotated_blueprint .code_scroller .initial_notice > div").width($(".annotated_blueprint .code_scroller").width());
-$(".annotated_blueprint .code_scroller").hover(function() {
- $(".annotated_blueprint .initial_notice").css("display", "none");
-});
-$(function() {
- setTimeout(function() { $(".annotated_blueprint .initial_notice").hide(400); }, 3000);
- setTimeout(function() { $(".annotated_blueprint #countdown").text("2s"); }, 1000);
- setTimeout(function() { $(".annotated_blueprint #countdown").text("1s"); }, 2000);
-});
+if (window.$ != null) {
+ $(function() {
+ maxCodeWidth = Math.max.apply(Math, $(".annotated_blueprint div.block > div:last-child").map(function(){ return this.scrollWidth; }).get());
+ $(".annotated_blueprint div.block").width(maxCodeWidth);
+ })
+
+ $(".annotated_blueprint .code_scroller .initial_notice > div").height($(".annotated_blueprint .code_scroller .code_viewer").height());
+ $(".annotated_blueprint .code_scroller .initial_notice > div").width($(".annotated_blueprint .code_scroller").width());
+ $(".annotated_blueprint .code_scroller").hover(function() {
+ $(".annotated_blueprint .initial_notice").css("display", "none");
+ });
+ $(function() {
+ setTimeout(function() { $(".annotated_blueprint .initial_notice").hide(400); }, 3000);
+ setTimeout(function() { $(".annotated_blueprint #countdown").text("2s"); }, 1000);
+ setTimeout(function() { $(".annotated_blueprint #countdown").text("1s"); }, 2000);
+ });
+ }
</script>
http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/a594c062/style/css/singlePage.css
----------------------------------------------------------------------
diff --git a/style/css/singlePage.css b/style/css/singlePage.css
index 9c87950..8c3a639 100644
--- a/style/css/singlePage.css
+++ b/style/css/singlePage.css
@@ -43,6 +43,9 @@ pre, pre code{
white-space: -o-pre-wrap; /* Opera 7 */
word-wrap: break-word; /* Internet Explorer 5.5+ */
}
+pre {
+ font-family: "Lucida Console", Monaco, monospace;
+}
.goToTop{
padding-right: 25px;
padding-top: 75px;
@@ -53,4 +56,13 @@ pre, pre code{
#content_container h1{
display: inline-block;
width: 90%;
+}
+.jumobotron.annotated_blueprint{
+ display: none;
+}
+.usermanual-pdf-include{
+ display: inline !important;
+}
+.usermanual-pdf-exclude{
+ display: none !important;
}
\ No newline at end of file
[08/10] brooklyn-docs git commit: Visibility correction
Posted by al...@apache.org.
Visibility correction
Project: http://git-wip-us.apache.org/repos/asf/brooklyn-docs/repo
Commit: http://git-wip-us.apache.org/repos/asf/brooklyn-docs/commit/e04b38e3
Tree: http://git-wip-us.apache.org/repos/asf/brooklyn-docs/tree/e04b38e3
Diff: http://git-wip-us.apache.org/repos/asf/brooklyn-docs/diff/e04b38e3
Branch: refs/heads/master
Commit: e04b38e3261fbfd58fc0b7f7a6361b5825eaf5c5
Parents: 5ee36ff
Author: Duncan Godwin <du...@cloudsoftcorp.com>
Authored: Wed Mar 9 13:50:19 2016 +0000
Committer: Duncan Godwin <du...@cloudsoftcorp.com>
Committed: Wed Mar 9 13:50:19 2016 +0000
----------------------------------------------------------------------
guide/start/policies.md | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/e04b38e3/guide/start/policies.md
----------------------------------------------------------------------
diff --git a/guide/start/policies.md b/guide/start/policies.md
index a12e77f..a1b2001 100644
--- a/guide/start/policies.md
+++ b/guide/start/policies.md
@@ -16,7 +16,7 @@ review and/or change the the location where the application will be deployed.
You will need four machines for this example: one for the load-balancer (nginx), and three for the
Tomcat cluster (but you can reduce this by changing the `maxPoolSize` below).
-<div class="usermanual-pdf-include" style="display: none;">
+<div class="usermanual-pdf-include started-pdf-include" style="display: none;">
{% highlight yaml %}
name: Tomcat Cluster
[02/10] brooklyn-docs git commit: Docs for the docs
Posted by al...@apache.org.
Docs for the 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/b5b21614
Tree: http://git-wip-us.apache.org/repos/asf/brooklyn-docs/tree/b5b21614
Diff: http://git-wip-us.apache.org/repos/asf/brooklyn-docs/diff/b5b21614
Branch: refs/heads/master
Commit: b5b21614cc03280860ff80883e7f22e939662e54
Parents: 5d6d845
Author: Duncan Godwin <du...@cloudsoftcorp.com>
Authored: Mon Mar 7 14:59:48 2016 +0000
Committer: Duncan Godwin <du...@cloudsoftcorp.com>
Committed: Mon Mar 7 16:54:43 2016 +0000
----------------------------------------------------------------------
README.md | 8 +++--
_plugins/page_structure.rb | 6 ----
contributing/index.md | 15 ++++++++++
contributing/inline-children.md | 54 +++++++++++++++++++++++++++++++++
contributing/ordering.md | 46 ++++++++++++++++++++++++++++
contributing/pdf-manual.md | 58 ++++++++++++++++++++++++++++++++++++
contributing/site-structure.md | 29 ++++++++++++++++++
7 files changed, 208 insertions(+), 8 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/b5b21614/README.md
----------------------------------------------------------------------
diff --git a/README.md b/README.md
index 5b6cf54..7d7d1e3 100644
--- a/README.md
+++ b/README.md
@@ -14,6 +14,10 @@ familiarise yourself with the standard workflow for Apache Brooklyn:
[CONTRIB]: https://brooklyn.apache.org/community/how-to-contribute-docs.html
[COMMIT]: https://brooklyn.apache.org/developers/committers/index.html
+The documents are written in [kramdown](http://kramdown.gettalong.org/syntax.html) a superset of Markdown
+which is processed into HTML using [Jekyll](https://jekyllrb.com/). In addition to the standard set of options
+and notation available with these platforms, a number of custom plug-ins have been implemented specifically
+for the Brooklyn docs. These are detailed in the [contributing to docs](https://brooklyn.apache.org/contributing) doc.
Workstation Setup
-----------------
@@ -21,8 +25,8 @@ Workstation Setup
First, if you have not already done so, clone the `brooklyn` repository and subprojects
and set up the remotes as described in [Guide for committers][COMMIT].
-The Brooklyn documentation uses Markdown notation (what this file is written in)
-and the Jekyll process. This in turn requires Ruby and gems as described in the `Gemfile`:
+The Brooklyn documentation uses [Jekyll](https://jekyllrb.com/) to process the site content into HTML.
+This in turn requires Ruby and gems as described in the `Gemfile`:
install [RVM](http://rvm.io/) to manage Ruby installations and sets of Ruby gems.
\curl -sSL https://get.rvm.io | bash -s stable
http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/b5b21614/_plugins/page_structure.rb
----------------------------------------------------------------------
diff --git a/_plugins/page_structure.rb b/_plugins/page_structure.rb
index fbfd5a2..07caf17 100644
--- a/_plugins/page_structure.rb
+++ b/_plugins/page_structure.rb
@@ -10,12 +10,6 @@ require "kramdown"
module PageStructureUtils
- class MyHash < Hash
- def to_s
- "cheese"
- end
- end
-
class ChildPage
def initialize(yaml, content)
@yaml=yaml
http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/b5b21614/contributing/index.md
----------------------------------------------------------------------
diff --git a/contributing/index.md b/contributing/index.md
new file mode 100644
index 0000000..21576dd
--- /dev/null
+++ b/contributing/index.md
@@ -0,0 +1,15 @@
+---
+layout: website-normal
+title: Contributing to the Docs
+check_directory_for_children: true
+---
+
+The Apache Brooklyn documentation is written in [kramdown](http://kramdown.gettalong.org/syntax.html){:target="_blank"} a superset of Markdown
+which is processed into HTML using [Jekyll](https://jekyllrb.com/){:target="_blank"}. In addition to the standard set of options
+and notation available with these platforms, a number of custom plug-ins have been implemented specifically
+for the Apache Brooklyn docs. These are detailed below:
+
+Jekyll plug-ins are written in ruby and kept in the `_plugins` folder. Note that if you're using `jekyll serve` to
+display the site, changes to these plug-ins will not be reflected in the rendered site until jekyll is restarted.
+
+{% child_content %}
http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/b5b21614/contributing/inline-children.md
----------------------------------------------------------------------
diff --git a/contributing/inline-children.md b/contributing/inline-children.md
new file mode 100644
index 0000000..d6270bb
--- /dev/null
+++ b/contributing/inline-children.md
@@ -0,0 +1,54 @@
+---
+section: Inline Children
+section_position: 2
+section_type: inline
+---
+
+### Inline Children
+
+In addition to the `children` property defining lower pages in the site structure, they can also be used to define
+inline sections within the current document. Inclusion in this way produces a menu link to an anchor in the current page.
+
+Below is an example from [/guide/ops/persistence/index.md](https://github.com/apache/brooklyn-docs/blob/master/guide/ops/persistence/index.md){:target="_blank"}:
+
+{% highlight yaml %}
+children:
+- { section: Command Line Options }
+- { section: File-based Persistence }
+- { section: Object Store Persistence }
+- { section: Rebinding to State }
+- { section: Writing Persistable Code }
+- { section: Persisted State Backup }
+{% endhighlight %}
+
+Inline sections can also be detected from separate, child `.md` files. Including the tag `check_directory_for_children: true`
+in the YAML front matter of a page causes the site structure plug-in to look through the current directory for any `.md` files
+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"}:
+
+<pre>
+---
+title: Locations
+layout: website-normal
+check_directory_for_children: true
+---
+
+Locations are the environments to which Brooklyn deploys applications, including:
+
+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`
+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`.
+
+{% child_content %}</pre>
http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/b5b21614/contributing/ordering.md
----------------------------------------------------------------------
diff --git a/contributing/ordering.md b/contributing/ordering.md
new file mode 100644
index 0000000..ff2a0f9
--- /dev/null
+++ b/contributing/ordering.md
@@ -0,0 +1,46 @@
+---
+section: Child Page Ordering
+section_position: 3
+section_type: inline
+---
+
+### Child Page Ordering
+
+Child pages are by default, ordered by their position in the `children` YAML front matter field. This can be changed using the property
+`section_position` in the child YAML. For children defined in the front matter this is put in the child object of the `children` array.
+
+For inline children, sourced using `check_directory_for_children: true`, this `section_position` property is put in the child file's YAML front matter.
+
+The format for `section_position` is that of software versioning, i.e `A.B... Z` where A, B etc are numbers of decreasing value. Position `1.1.0` would appear
+before version `1.0.4` for example. This allows an infinite number of sub pages between each `section_position`.
+
+Any un-versioned pages are automatically numbered to follow on from the last numbered page, or `1.1` if no pages are yet numbered. For
+example, if a numbered page, `1.4` is followed by a non-numbered page, the non-numbered page would be auto-numbered as `1.4.1`.
+
+For example, a set of children pages numbered like this:
+
+{% highlight yaml %}
+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/ops/index.md, section_position: 2 }
+- { path: /guide/misc/index.md }
+{% endhighlight %}
+
+Would end up numbered like this:
+
+{% highlight yaml %}
+children:
+- { path: /guide/ops/index.md, section_position: 2 }
+- { path: /guide/misc/index.md, section_position: 2.1 }
+- { path: /guide/start/index.md, section_position: 3.1.2 }
+- { path: /guide/misc/download.md, section_position: 3.1.2.1 }
+- { path: /guide/concepts/index.md, section_position: 3.1.2.2 }
+- { path: /guide/yaml/index.md, section_position: 3.1.2.3 }
+- { path: /guide/java/index.md, section_position: 3.1.2.4 }
+{% endhighlight %}
+
+This ordering affects both the position of the child in the html menu and the order of content included with `child_content`.
http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/b5b21614/contributing/pdf-manual.md
----------------------------------------------------------------------
diff --git a/contributing/pdf-manual.md b/contributing/pdf-manual.md
new file mode 100644
index 0000000..ef9e950
--- /dev/null
+++ b/contributing/pdf-manual.md
@@ -0,0 +1,58 @@
+---
+section: Single Page Manual & PDF
+section_position: 4
+section_type: inline
+---
+
+## Single Page Manual & PDF
+
+A single page overview of selections of the site are available in `zoneMergeManual` and `zoneMergeStarted`. These overviews are for the user manual
+and getting started guide respectively. The zone merge pages go through the [site structure](#site-structure), described above, and compile the files from this into a
+single HTML page.
+
+In order to do this, each page is iterated over in order and it's rendered content included in the page. The plug-in `regex_filter.rb` is used to re-write
+ <a> links from the structured site into a form which works on a single page. Links are re-written in the following manner:
+
+- If the link is from an external domain, leave it as an unaltered link
+- If the link is an anchor, convert to the anchor scheme used in the single page
+- If the link target is in the single page, change the link to point at the anchor in the single page
+- If the link is pointing at somewhere on the brooklyn site which is not included in this single page, point to the website with a specific version, so https://brooklyn.apache.org/v/0.9.0-SNAPSHOT/start/concept-quickstart.html for instance
+
+In addition, all images src's are re-written relative to the root directory.
+
+Pages can be masked from the compilation process by defining a `page_mask` in the YAML front matter of the zone merge file, then including this mask as `true` in the child page to exclude.
+These pages will then not be included in the compiled single page. Note that this will mask both the child page and any children of this masked page.
+For example [zoneMergeStarted](https://github.com/apache/brooklyn-docs/blob/master/zoneMergeStarted.html){:target="_blank"} uses the mask `started-pdf-exclude`:
+
+{% highlight yaml %}
+title: Apache Brooklyn Manual
+layout: singlePage
+page_mask: started-pdf-exclude
+...
+{% endhighlight %}
+
+Then in latter pages, such as [/guide/ops/index.md](https://github.com/apache/brooklyn-docs/blob/master/guide/ops/index.md){:target="_blank"} include `started-pdf-exclude: true` to
+exclude this section from the getting started guide.
+
+{% highlight yaml %}
+title: Operations
+started-pdf-exclude: true
+...
+{% endhighlight %}
+
+This will exclude not only the operations page but all of the operations section.
+
+Specific content can be also be masked or unmasked at a page component level by specifying CSS show and hide classes:
+
+{% highlight yaml %}
+css_hide_class: usermanual-pdf-exclude
+css_show_class: usermanual-pdf-include
+{% endhighlight %}
+
+If the above YAML is included in the front matter of a zone merge file, the classes `usermanual-pdf-exclude` and `usermanual-pdf-include` will add or remove a
+`display: none` to a HTML object. In addition the single page theme files [singlePage.html](https://github.com/apache/brooklyn-docs/blob/master/_layouts/singlePage.html){:target="_blank"} and
+[singlePage.css](https://github.com/apache/brooklyn-docs/blob/master/style/css/singlePage.css) can be used to style only the single merged pages.
+
+### Conversion to PDF
+
+These single merged pages are then converted to PDF using wkhtmltopdf in the build scripts of this site.
http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/b5b21614/contributing/site-structure.md
----------------------------------------------------------------------
diff --git a/contributing/site-structure.md b/contributing/site-structure.md
new file mode 100644
index 0000000..c052e1c
--- /dev/null
+++ b/contributing/site-structure.md
@@ -0,0 +1,29 @@
+---
+section: Site Structure
+section_position: 1
+section_type: inline
+---
+
+## Site Structure
+
+The site structure and menus are built by a plug-in in `site_structure.rb`. This plug-in looks in the [YAML front matter](https://jekyllrb.com/docs/frontmatter/){:target="_blank"}
+for child pages to build the structure, and breadcrumbs to determine the parent pages to display.
+
+Child pages are a list of objects, stored in the field `children`. These are defined by string path to a file or a YAML
+object with a `path` to another file, or a `link` to an external URL. In addition a `title` can be defined
+for the text content of the HTML menu option. See the example below from
+[/guide/index.md](https://github.com/apache/brooklyn-docs/blob/master/guide/index.md){:target="_blank"}
+
+{% highlight yaml %}
+breadcrumbs:
+- /website/documentation/index.md
+- index.md
+children:
+- { path: /guide/start/index.md }
+- { path: /guide/misc/download.md }
+- { path: /guide/concepts/index.md }
+- { path: /guide/yaml/index.md }
+- { path: /guide/java/index.md }
+- { path: /guide/ops/index.md }
+- { path: /guide/misc/index.md }
+{% endhighlight %}
[03/10] brooklyn-docs git commit: Fixed typo
Posted by al...@apache.org.
Fixed typo
Project: http://git-wip-us.apache.org/repos/asf/brooklyn-docs/repo
Commit: http://git-wip-us.apache.org/repos/asf/brooklyn-docs/commit/5d6d8452
Tree: http://git-wip-us.apache.org/repos/asf/brooklyn-docs/tree/5d6d8452
Diff: http://git-wip-us.apache.org/repos/asf/brooklyn-docs/diff/5d6d8452
Branch: refs/heads/master
Commit: 5d6d84527241ee845f70083ae91da3e1e8060b2c
Parents: a594c06
Author: Duncan Godwin <du...@cloudsoftcorp.com>
Authored: Fri Mar 4 14:34:02 2016 +0000
Committer: Duncan Godwin <du...@cloudsoftcorp.com>
Committed: Mon Mar 7 16:54:43 2016 +0000
----------------------------------------------------------------------
_plugins/page_structure.rb | 1 +
guide/index.md | 4 ++--
2 files changed, 3 insertions(+), 2 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/5d6d8452/_plugins/page_structure.rb
----------------------------------------------------------------------
diff --git a/_plugins/page_structure.rb b/_plugins/page_structure.rb
index 4e01559..fbfd5a2 100644
--- a/_plugins/page_structure.rb
+++ b/_plugins/page_structure.rb
@@ -52,6 +52,7 @@ module PageStructureUtils
end
##
# Sorts a list of yaml children, if there's no numbering, use the YAML order to create a numbering
+ # NOTE: doesn't alter the returned object as that seemed to break things downstream
#
def self.sortYAMLSectionPositions(yaml)
position = Hash.new
http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/5d6d8452/guide/index.md
----------------------------------------------------------------------
diff --git a/guide/index.md b/guide/index.md
index 5c7ced3..cdb3b46 100644
--- a/guide/index.md
+++ b/guide/index.md
@@ -5,12 +5,12 @@ breadcrumbs:
- /website/documentation/index.md
- index.md
children:
-- { path: /guide/start/index.md, section_position: 3.1.2 }
+- { path: /guide/start/index.md }
- { path: /guide/misc/download.md }
- { path: /guide/concepts/index.md }
- { path: /guide/yaml/index.md }
- { path: /guide/java/index.md }
-- { path: /guide/ops/index.md, section_position: 2 }
+- { path: /guide/ops/index.md }
- { path: /guide/misc/index.md }
---
[05/10] brooklyn-docs git commit: Updated page structure & locations
Posted by al...@apache.org.
Updated page structure & locations
Project: http://git-wip-us.apache.org/repos/asf/brooklyn-docs/repo
Commit: http://git-wip-us.apache.org/repos/asf/brooklyn-docs/commit/95eb8a47
Tree: http://git-wip-us.apache.org/repos/asf/brooklyn-docs/tree/95eb8a47
Diff: http://git-wip-us.apache.org/repos/asf/brooklyn-docs/diff/95eb8a47
Branch: refs/heads/master
Commit: 95eb8a4749de2993a5bc63cd9431d8df05a8f506
Parents: bf43bd0
Author: Duncan Godwin <du...@cloudsoftcorp.com>
Authored: Mon Feb 29 11:32:04 2016 +0000
Committer: Duncan Godwin <du...@cloudsoftcorp.com>
Committed: Mon Mar 7 16:54:43 2016 +0000
----------------------------------------------------------------------
_plugins/page_structure.rb | 103 +++++
_plugins/site_structure.rb | 20 +
guide/ops/locations/1.1_cloud-setup.md | 86 ++++
guide/ops/locations/1_clouds.md | 239 ++++++++++
.../2_inheritance-and-named-locations.md | 78 ++++
guide/ops/locations/3.1_ssh-keys.md | 86 ++++
guide/ops/locations/3_localhost.md | 31 ++
guide/ops/locations/4_byon.md | 72 +++
guide/ops/locations/6_more-locations.md | 52 +++
guide/ops/locations/index.md | 439 +------------------
10 files changed, 769 insertions(+), 437 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/95eb8a47/_plugins/page_structure.rb
----------------------------------------------------------------------
diff --git a/_plugins/page_structure.rb b/_plugins/page_structure.rb
new file mode 100644
index 0000000..9579397
--- /dev/null
+++ b/_plugins/page_structure.rb
@@ -0,0 +1,103 @@
+#
+# Adds a liquid tag to build a page on the contents of the folder it's in
+#
+# Pulls in files in the format <Number>_<title>.md in the order of version number. Ignores files not in this format.
+#
+
+require 'rubygems'
+require 'yaml'
+require "kramdown"
+
+module PageStructureUtils
+
+ class ChildPage
+ def initialize(yaml, content)
+ @page_yaml=yaml
+ @page_content=content
+ end
+ def content()
+ @page_content
+ end
+ def yaml()
+ @page_yaml
+ end
+ def to_s # called with print / puts
+ "YAML : #{@page_yaml}, Content : #{@page_content}"
+ end
+
+ def self.parseChildPagesFromParent(page)
+ # get the base directory of the current file
+ $baseFile = Dir.pwd+page['dir']
+ # list all of the files in that directory
+ $listings = Dir[$baseFile+"/*"]
+ # filter by the key pattern
+ $listings = $listings.select{ |i| i[/[\d\.]\_.*\.md/] }
+ # Sort the files based on the Gem::Version of the prefix
+ $listings = $listings.sort{ |x,y| Gem::Version.new((File.basename x).partition('_').first) <=> Gem::Version.new((File.basename y).partition('_').first) }
+ # loop through them and merge the content
+ $allPages = []
+
+ for $listing in $listings
+ $textContent = ""
+ yamlContent = nil
+
+ # read the file
+ $fileContent = IO.read($listing)
+ # try and split of any YAML
+ $partitionedFileContent = $fileContent.split('---');
+ # if there's potentially partitioned YAML try and parse it
+ if $partitionedFileContent.size > 2
+ # try and parse the YAML
+ yamlContent = YAML.load($partitionedFileContent[1])
+ # if we can, use it
+ if yamlContent != nil && yamlContent != false
+ $textContent = $partitionedFileContent[2]
+ end
+ end
+
+ # if there's no text content set yet, just use the whole file
+ if $textContent == ""
+ # use the whole file content
+ $textContent = $fileContent
+ end
+ # append the current file to the content
+ ($allPages ||= []) << ChildPage.new(yamlContent, $textContent)
+
+ end
+ # return the combined content
+ $allPages
+ end
+ end
+
+ class IncludePageContentTag < Liquid::Tag
+ def initialize(tag_name, text, tokens)
+ super
+ @text = text.strip
+ end
+ def render(context)
+ $childPages = ChildPage.parseChildPagesFromParent(context['page'])
+ $content = ""
+ for $childPage in $childPages
+ #append the content
+ $content = $content+$childPage.content()
+ end
+ site = context.registers[:site]
+ pageHash = context.registers[:page]
+
+ # not sure how to get the page object so look through site.pages for the current URL
+ page = nil;
+ for currPage in site.pages
+ if currPage['url'] == pageHash['url']
+ page = currPage
+ break
+ end
+ end
+
+ # render the included content with the current page renderer
+ info = { :filters => [Jekyll::Filters], :registers => { :site => site, :page => page } }
+ page.render_liquid($content, site.site_payload, info)
+ end
+ end
+end
+
+Liquid::Template.register_tag('child_content', PageStructureUtils::IncludePageContentTag)
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/95eb8a47/_plugins/site_structure.rb
----------------------------------------------------------------------
diff --git a/_plugins/site_structure.rb b/_plugins/site_structure.rb
index 5b0c488..88331b8 100644
--- a/_plugins/site_structure.rb
+++ b/_plugins/site_structure.rb
@@ -221,6 +221,26 @@ module SiteStructure
data['data'] = data
result = data
end
+
+ ##
+ # This is added for inline seperate child files
+ # see: page_structure.rb
+ #
+ # require show_inline_children to be set to true to show in the menu
+ if page['show_inline_children'] == true
+ $childPages = PageStructureUtils::ChildPage.parseChildPagesFromParent(page)
+ # add the child pages in before the site structure has been created
+ for $childPage in $childPages
+ if $childPage.yaml() != nil && $childPage.yaml() != false
+ # now add the YAML on as a child context to the page
+ if data['children'] == nil
+ data['children'] = []
+ end
+ data['children'] << $childPage.yaml()
+ end
+ end
+ end
+
data['path'] = page.path
if item['href_path']
href_page = find_page_with_path_absolute_or_relative_to(site, render_liquid(site, page, item['href_path']), parent, structure_processed_pages)
http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/95eb8a47/guide/ops/locations/1.1_cloud-setup.md
----------------------------------------------------------------------
diff --git a/guide/ops/locations/1.1_cloud-setup.md b/guide/ops/locations/1.1_cloud-setup.md
new file mode 100644
index 0000000..1f60b5b
--- /dev/null
+++ b/guide/ops/locations/1.1_cloud-setup.md
@@ -0,0 +1,86 @@
+---
+section: Cloud Specific Setup
+---
+
+### Cloud Specific Setup
+
+To connect to a Cloud, Brooklyn requires appropriate credentials. These comprise the "identity" and
+"credential" in Brooklyn terminology.
+
+For private clouds (and for some clouds being targeted using a standard API), the "endpoint"
+must also be specified, which is the cloud's URL.
+
+The [jclouds guides](https://jclouds.apache.org/guides) includes documentation on configuring
+different clouds.
+
+
+#### AWS
+
+##### Credentials
+
+AWS has an "access key" and a "secret key", which correspond to Brooklyn's identity and credential
+respectively.
+
+These keys are the way for any programmatic mechanism to access the AWS API.
+
+To generate an access key and a secret key, see [jclouds instructions](http://jclouds.apache.org/guides/aws)
+and [AWS IAM instructions](http://docs.aws.amazon.com/IAM/latest/UserGuide/ManagingCredentials.html).
+
+An example of the expected format is shown below:
+
+ brooklyn.location.jclouds.aws-ec2.identity=ABCDEFGHIJKLMNOPQRST
+ brooklyn.location.jclouds.aws-ec2.credential=abcdefghijklmnopqrstu+vwxyzabcdefghijklm
+
+
+##### Tidying up after jclouds
+
+Security groups are not always deleted by jclouds. This is due to a limitation in AWS (see
+https://issues.apache.org/jira/browse/JCLOUDS-207). In brief, AWS prevents the security group
+being deleted until there are no VMs using it. However, there is eventual consistency for
+recording which VMs still reference those security groups. After deleting the VM, it can sometimes
+take several minutes before the security group can be deleted. jclouds retries for 3 seconds, but
+does not block for longer.
+
+There is utility written by Cloudsoft for deleting these unused resources:
+http://www.cloudsoftcorp.com/blog/2013/03/tidying-up-after-jclouds.
+
+
+#### Google Compute Engine
+
+##### Credentials
+
+Google Compute Engine (GCE) uses a service account e-mail address for the identity, and a private key
+as the credential.
+
+To obtain these from GCE, see the [jclouds instructions](https://jclouds.apache.org/guides/google).
+
+An example of the expected format is shown below (note the credential is one long line,
+with `\n` to represent the new line characters):
+
+ brooklyn.location.jclouds.google-compute-engine.identity=123456789012@developer.gserviceaccount.com
+ brooklyn.location.jclouds.google-compute-engine.credential=-----BEGIN RSA PRIVATE KEY-----\nabcdefghijklmnopqrstuvwxyznabcdefghijk/lmnopqrstuvwxyzabcdefghij\nabcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrstuvwxyzabcdefghij+lm\nnopqrstuvwxyzabcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrstuvwxyzabcdefghijklm\nnopqrstuvwxyzabcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrstuvwxy\nzabcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrstuvwxyzabcdefghijk\nlmnopqrstuvwxyzabcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrstuvw\nxyzabcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrstuvwxyzabcdefghi\njklmnopqrstuvwxyzabcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrstu\nvwxyzabcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrstuvwxyzabcdefg\nhijklmnopqrstuvwxyzabcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrs\ntuvwxyzabcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrstuvwxyzabcde\nfghijklmnopqrstuvwxyzabcdefghijklmnopqrstuvw\n-----END RSA PRIVATE KEY-----
+
+
+##### Quotas
+
+GCE accounts can have low default [quotas](https://cloud.google.com/compute/docs/resource-quotas).
+
+It is easy to requesta quota increase by submitting a [quota increase form](https://support.google.com/cloud/answer/6075746?hl=en).
+
+
+##### Networks
+
+GCE accounts often have a limit to the number of networks that can be created. One work around
+is to manually create a network with the required open ports, and to refer to that named network
+in Brooklyn's location configuration.
+
+To create a network, see [GCE network instructions](https://cloud.google.com/compute/docs/networking#networks_1).
+
+For example, for dev/demo purposes an "everything" network could be created that opens all ports.
+
+| Name | everything |
+| Description | opens all tcp ports |
+| Source IP Ranges | 0.0.0.0/0 |
+| Allowed protocols and ports | tcp:0-65535 and udp:0-65535 |
+
+
http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/95eb8a47/guide/ops/locations/1_clouds.md
----------------------------------------------------------------------
diff --git a/guide/ops/locations/1_clouds.md b/guide/ops/locations/1_clouds.md
new file mode 100644
index 0000000..13112cd
--- /dev/null
+++ b/guide/ops/locations/1_clouds.md
@@ -0,0 +1,239 @@
+---
+section: Clouds
+---
+
+### Clouds
+
+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/)):
+
+* `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)
+
+For any of these, of course, Brooklyn needs to be configured with an `identity` and a `credential`:
+
+{% 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, you can instead store them as a [catalog entry]({{ site.path.guide }}/ops/catalog/index.html#locations-in-catalog) or set them in `brooklyn.properties`
+in the `jclouds.<provider>` namespace:
+
+{% highlight bash %}
+brooklyn.location.jclouds.aws-ec2.identity=ABCDEFGHIJKLMNOPQRST
+brooklyn.location.jclouds.aws-ec2.credential=s3cr3tsq1rr3ls3cr3tsq1rr3ls3cr3tsq1rr3l
+{% endhighlight %}
+
+And in this case you can reference the location in YAML with `location: jclouds:aws-ec2`.
+
+The Getting Started [template brooklyn.properties]({{ site.path.guide }}/start/brooklyn.properties) contains more examples
+of configuring cloud endpoints, including information on credential types used in different clouds.
+
+#### OS Initial Login and Setup
+
+Once a machine is provisioned, Brooklyn will normally attempt to log in via SSH and configure the machine sensibly.
+
+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 custom login is particularly useful when using a custom image templates where the cloud-side account
+management logic is not enabled. For example, a vCloud (vCD) template can have guest customization that will change
+the root password. This setting tells AMP to only use the given password, rather than the initial
+randomly generated password that vCD returns. Without this property, there is a race for such templates:
+does Brooklyn manage to create the admin user before the guest customization changes the login and reboots,
+or is the password reset first (the latter means Brooklyn can never ssh to the VM). With this property,
+Brooklyn will always wait for guest customization to complete before it is able to ssh at all. In such
+cases, it is also recommended to use `useJcloudsSshInit=false`.)
+
+Following a successful logon, Brooklyn performs the following steps to configure the machine:
+
+1. creates a new user with the same name as the user `brooklyn` is running as locally
+ (this can be overridden with `user`, below).
+
+1. 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="org/apache/brooklyn/location/jclouds" project_subpath="locations/jclouds" %}.
+
+###### 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)
+
+- A specific existing key pair known at the cloud to use can be specified with `keyPair`
+ (selected clouds only)
+
+- A specific VM name (often the hostname) base to be used can be specified by setting `groupId`.
+ By default, this name is constructed based on the entity which is creating it,
+ including the ID of the app and of the entity.
+ (As many cloud portals let you filter views, this can help find a specific entity or all machines for a given application.)
+ For more sophisticated control over host naming, you can supply a custom
+ {% include java_link.html class_name="CloudMachineNamer" package_path="org/apache/brooklyn/core/location/cloud/names" project_subpath="core" %},
+ for example
+ `cloudMachineNamer: CustomMachineNamer`.
+ {% include java_link.html class_name="CustomMachineNamer" package_path="org/apache/brooklyn/core/location/cloud/names" project_subpath="core" %}
+ will use the entity's name or following a template you supply.
+ On many clouds, a random suffix will be appended to help guarantee uniqueness;
+ this can be removed by setting `vmNameSaltLength: 0` (selected clouds only).
+ <!-- TODO jclouds softlayer includes a 3-char hex suffix -->
+
+- A DNS domain name where this host should be placed can be specified with `domainName`
+ (in selected clouds only)
+
+- User metadata can be attached using the syntax `userMetadata: { key: value, key2: "value 2" }`
+ (or `userMetadata=key=value,key2="value 2"` in a properties file)
+
+- By default, several pieces of user metadata are set to correlate VMs with Brooklyn entities,
+ prefixed with `brooklyn-`.
+ This user metadata can be omitted by setting `includeBrooklynUserMetadata: false`.
+
+- You can specify the number of attempts Brooklyn should make to create
+ machines with `machineCreateAttempts` (jclouds only). This is useful as an efficient low-level fix
+ for those occasions when cloud providers give machines that are dead on arrival.
+ You can of course also resolve it at a higher level with a policy such as
+ {% include java_link.html class_name="ServiceRestarter" package_path="org/apache/brooklyn/policy/ha" project_subpath="policy" %}.
+
+- If you want to investigate failures, set `destroyOnFailure: false`
+ to keep failed VM's around. (You'll have to manually clean them up.)
+ The default is false: if a VM fails to start, or is never ssh'able, then the VM will be terminated.
+
+ ###### 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 when you log in.)
+
+- Provide a list of URLs to public keys in `extraSshPublicKeyUrls`,
+ or the data of one key in `extraSshPublicKeyData`,
+ to have additional public keys added to the `authorized_keys` file for logging in.
+ (This is supported in most but not all locations.)
+
+- 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`)
+
+- Use `openIptables: true` to automatically configure `iptables`, to open the TCP ports required by
+ the software process. One can alternatively use `stopIptables: true` to entirely stop the
+ iptables service.
+
+- Use `installDevUrandom: true` to fall back to using `/dev/urandom` rather than `/dev/random`. This setting
+ is useful for cloud VMs where there is not enough random entropy, which can cause `/dev/random` to be
+ extremely slow (causing `ssh` to be extremely slow to respond).
+
+- Use `useJcloudsSshInit: false` to disable the use of the native jclouds support for initial commands executed
+ on the VM (e.g. for creating new users, setting root passwords, etc.). Instead, Brooklyn's ssh support will
+ be used. Timeouts and retries are more configurable within Brooklyn itself. Therefore this option is particularly
+ recommended when the VM startup is unusual (for example, if guest customizations will cause reboots and/or will
+ change login credentials).
+
+- Use `brooklyn.ssh.config.noDeleteAfterExec: true` to keep scripts on the server after execution.
+ The contents of the scripts and the stdout/stderr of their execution are available in the Brooklyn web console,
+ but sometimes it can also be useful to have them on the box.
+ This setting prevents scripts executed on the VMs from being deleted on completion.
+ Note that some scripts run periodically so this can eventually fill a disk; it should only be used for dev/test.
+
+###### Custom template options
+
+jclouds supports many additional options for configuring how a virtual machine is created and deployed, many of which
+are for cloud-specific features and enhancements. Brooklyn supports some of these, but if what you are looking for is
+not supported directly by Brooklyn, we instead offer a mechanism to set any parameter that is supported by the jclouds
+template options for your cloud.
+
+Part of the process for creating a virtual machine is the creation of a jclouds `TemplateOptions` object. jclouds
+providers extends this with extra options for each cloud - so when using the AWS provider, the object will be of
+type `AWSEC2TemplateOptions`. By [examining the source code](https://github.com/jclouds/jclouds/blob/jclouds-1.9.0/providers/aws-ec2/src/main/java/org/jclouds/aws/ec2/compute/AWSEC2TemplateOptions.java),
+you can see all of the options available to you.
+
+The `templateOptions` config key takes a map. The keys to the map are method names, and Brooklyn will find the method on
+the `TemplateOptions` instance; it then invokes the method with arguments taken from the map value. If a method takes a
+single parameter, then simply give the argument as the value of the key; if the method takes multiple parameters, the
+value of the key should be an array, containing the argument for each parameter.
+
+For example, here is a complete blueprint that sets some AWS EC2 specific options:
+
+ location: AWS_eu-west-1
+ services:
+ - type: org.apache.brooklyn.entity.software.base.EmptySoftwareProcess
+ provisioningProperties:
+ templateOptions:
+ subnetId: subnet-041c8373
+ mapNewVolumeToDeviceName: ["/dev/sda1", 100, true]
+ securityGroupIds: ['sg-4db68928']
+
+Here you can see that we set three template options:
+
+- `subnetId` is an example of a single parameter method. Brooklyn will effectively try to run the statement
+ `templateOptions.subnetId("subnet-041c88373");`
+- `mapNewVolumeToDeviceName` is an example of a multiple parameter method, so the value of the key is an array.
+ Brooklyn will effectively true to run the statement `templateOptions.mapNewVolumeToDeviceName("/dev/sda1", 100, true);`
+- `securityGroupIds` demonstrates an ambiguity between the two types; Brooklyn will first try to parse the value as
+ a multiple parameter method, but there is no method that matches this parameter. In this case, Brooklyn will next try
+ to parse the value as a single parameter method which takes a parameter of type `List`; such a method does exist so
+ the operation will succeed.
+
+If the method call cannot be matched to the template options available - for example if you are trying to set an AWS EC2
+specific option but your location is an OpenStack cloud - then a warning is logged and the option is ignored.
+
+
+
+
+See the following resources for more information:
+
+- [AWS VPC issues which may affect users with older AWS accounts](vpc-issues.html)
+- [Amazon EC2 and Amazon Virtual Private Cloud](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-vpc.html#vpc-only-instance-types)
+- [Your Default VPC and Subnets](http://docs.aws.amazon.com/AmazonVPC/latest/UserGuide/default-vpc.html)
+- [Amazon VPC FAQs](http://aws.amazon.com/vpc/faqs/#Default_VPCs)
+
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/95eb8a47/guide/ops/locations/2_inheritance-and-named-locations.md
----------------------------------------------------------------------
diff --git a/guide/ops/locations/2_inheritance-and-named-locations.md b/guide/ops/locations/2_inheritance-and-named-locations.md
new file mode 100644
index 0000000..3e7b50a
--- /dev/null
+++ b/guide/ops/locations/2_inheritance-and-named-locations.md
@@ -0,0 +1,78 @@
+---
+section: Inheritance and Named Locations
+title: Named Locations
+---
+
+### 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 %}
+
+Named locations can refer to other named locations using `named:xxx` as their value.
+These will inherit the configuration and can override selected keys.
+Properties set in the namespace of the provider (e.g. `b.l.jclouds.aws-ec2.KEY=VALUE`)
+will be inherited by everything which extends AWS
+Sub-prefix strings are also inherited up to `brooklyn.location.*`,
+except that they are filtered for single-word and other
+known keys
+(so that we exclude provider-scoped properties when looking at sub-prefix keys).
+The precedence for configuration defined at different levels is that the value
+defined in the most specific context will apply.
+
+This is rather straightforward and powerful to use,
+although it sounds rather more complicated than it is!
+The examples below should make it clear.
+You could use the following to install
+a public key on all provisioned machines,
+an additional public key in all AWS machines,
+and no extra public key in `prod1`:
+
+<!-- tested in JcloudsLocationResolverTest -->
+{% highlight bash %}
+brooklyn.location.extraSshPublicKeyUrls=http://me.com/public_key
+brooklyn.location.jclouds.aws-ec2.extraSshPublicKeyUrls="[ \"http://me.com/public_key\", \"http://me.com/aws_public_key\" ]"
+brooklyn.location.named.prod1.extraSshPublicKeyUrls=
+{% endhighlight %}
+
+And in the example below, a config key is repeatedly overridden.
+Deploying `location: named:my-extended-aws` will result in an `aws-ec2` machine in `us-west-1` (by inheritance)
+with `VAL6` for `KEY`:
+
+{% highlight bash %}
+brooklyn.location.KEY=VAL1
+brooklyn.location.jclouds.KEY=VAL2
+brooklyn.location.jclouds.aws-ec2.KEY=VAL3
+brooklyn.location.jclouds.aws-ec2@us-west-1.KEY=VAL4
+brooklyn.location.named.my-aws=jclouds:aws-ec2:us-west-1
+brooklyn.location.named.my-aws.KEY=VAL5
+brooklyn.location.named.my-extended-aws=named:my-aws
+brooklyn.location.named.my-extended-aws.KEY=VAL6
+{% endhighlight %}
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/95eb8a47/guide/ops/locations/3.1_ssh-keys.md
----------------------------------------------------------------------
diff --git a/guide/ops/locations/3.1_ssh-keys.md b/guide/ops/locations/3.1_ssh-keys.md
new file mode 100644
index 0000000..4adda4b
--- /dev/null
+++ b/guide/ops/locations/3.1_ssh-keys.md
@@ -0,0 +1,86 @@
+---
+section: SSH Keys
+---
+
+### SSH Keys
+
+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 %}
+
+Now verify that your setup by running the command: `ssh localhost echo hello world`
+
+If your setup is correct, you should see `hello world` printed back at you.
+
+On the first connection, you may see a message similar to this:
+
+<pre>
+The authenticity of host 'localhost (::1)' can't be established.
+RSA key fingerprint is 7b:e3:8e:c6:5b:2a:05:a1:7c:8a:cf:d1:6a:83:c2:ad.
+Are you sure you want to continue connecting (yes/no)?
+</pre>
+
+Simply answer 'yes' and then repeat the command again.
+
+If this isn't the case, see below.
+
+
+
+
+#### Potential Problems
+
+* **MacOS user?** In addition to the above, enable "Remote Login" in "System Preferences > Sharing".
+
+* **Got a passphrase?** Set `brooklyn.location.localhost.privateKeyPassphrase`
+ as described [here](index.html#os-setup).
+ If you're not sure, or you don't know what a passphrase is, you can test this by executing `ssh-keygen -y`.
+ If it does *not* ask for a passphrase, then your key has no passphrase.
+ If your key does have a passphrase, you can remove it by running `ssh-keygen -p`.
+
+* Check that you have an `~/.ssh/id_rsa` file (or `id_dsa`) and a corresponding public key with a `.pub` extension;
+ if not, create one as described above
+
+* `~/.ssh/` or files in that directory may have permissions they shouldn't:
+ they should be visible only to the user (apart from public keys),
+ both on the source machine and the target machine.
+ You can verify this with `ls -l ~/.ssh/`: lines should start with `-rw-------` or `-r--------` (or `-rwx------` for directories).
+ If it does not, execute `chmod go-rwx ~/.ssh ~/.ssh/*`.
+
+* 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/brooklyn-docs/blob/95eb8a47/guide/ops/locations/3_localhost.md
----------------------------------------------------------------------
diff --git a/guide/ops/locations/3_localhost.md b/guide/ops/locations/3_localhost.md
new file mode 100644
index 0000000..13e1435
--- /dev/null
+++ b/guide/ops/locations/3_localhost.md
@@ -0,0 +1,31 @@
+---
+section: Localhost
+---
+
+### Localhost
+
+If passwordless ssh login to `localhost` and passwordless `sudo` is enabled on your
+machine, you should be able to deploy blueprints with no special configuration,
+just by specifying `location: localhost` in YAML.
+
+If you use a passpharse or prefer a different key, these can be configured as follows:
+
+{% highlight bash %}
+brooklyn.location.localhost.privateKeyFile=~/.ssh/brooklyn_key
+brooklyn.location.localhost.privateKeyPassphrase=s3cr3tPASSPHRASE
+{% endhighlight %}
+
+If you encounter issues or for more information, see [SSH Keys Localhost Setup](ssh-keys.html#localhost-setup).
+
+If you are normally prompted for a password when executing `sudo` commands, passwordless `sudo` must also be enabled. To enable passwordless `sudo` for your account, a line must be added to the system `/etc/sudoers` file. To edit the file, use the `visudo` command:
+{% highlight bash %}
+sudo visudo
+{% endhighlight %}
+Add this line at the bottom of the file, replacing `username` with your own user:
+{% highlight bash %}
+username ALL=(ALL) NOPASSWD: ALL
+{% endhighlight %}
+If executing the following command does not ask for your password, then `sudo` should be setup correctly:
+{% highlight bash %}
+sudo ls
+{% endhighlight %}
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/95eb8a47/guide/ops/locations/4_byon.md
----------------------------------------------------------------------
diff --git a/guide/ops/locations/4_byon.md b/guide/ops/locations/4_byon.md
new file mode 100644
index 0000000..42a52ca
--- /dev/null
+++ b/guide/ops/locations/4_byon.md
@@ -0,0 +1,72 @@
+---
+section: BYON
+---
+
+### BYON
+
+"Bring-your-own-nodes" mode is useful in production, where machines have been provisioned by someone else,
+and during testing, to cut down provisioning time.
+
+Your nodes must meet the following prerequisites:
+
+- A suitable OS must have been installed on all nodes
+- The node must be running sshd (or similar)
+- the brooklyn user must be able to ssh to each node as root or as a user with passwordless sudo permission. (For more information on SSH keys, see [here](ssh-keys.html).)
+
+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.
+
+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.
+
+{% 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 %}
+
+For more complex host configuration, one can define custom config values per machine. In the example
+below, there will be two machines. The first will be a machine reachable on
+`ssh -i ~/.ssh/brooklyn.pem -p 8022 myuser@50.51.52.53`. The second is a windows machine, reachable
+over WinRM. Each machine has also has a private address (e.g. for within a private network).
+
+{% highlight yaml %}
+location:
+ byon:
+ hosts:
+ - ssh: 50.51.52.53:8022
+ privateAddresses: [10.0.0.1]
+ privateKeyFile: ~/.ssh/brooklyn.pem
+ user: myuser
+ - winrm: 50.51.52.54:8985
+ privateAddresses: [10.0.0.2]
+ password: mypassword
+ user: myuser
+ osFamily: windows
+{% endhighlight %}
+
+The BYON location also supports a machine chooser, using the config key `byon.machineChooser`.
+This allows one to plugin logic to choose from the set of available machines in the pool. For
+example, additional config could be supplied for each machine. This could be used (during the call
+to `location.obtain()`) to find the config that matches the requirements of the entity being
+provisioned. See `FixedListMachineProvisioningLocation.MACHINE_CHOOSER`.
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/95eb8a47/guide/ops/locations/6_more-locations.md
----------------------------------------------------------------------
diff --git a/guide/ops/locations/6_more-locations.md b/guide/ops/locations/6_more-locations.md
new file mode 100644
index 0000000..39099d9
--- /dev/null
+++ b/guide/ops/locations/6_more-locations.md
@@ -0,0 +1,52 @@
+---
+section: Specialized Locations
+---
+
+### Specialized Locations
+
+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: org.apache.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 class_name="ServerPool" package_path="org/apache/brooklyn/entity/machine/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/brooklyn-docs/blob/95eb8a47/guide/ops/locations/index.md
----------------------------------------------------------------------
diff --git a/guide/ops/locations/index.md b/guide/ops/locations/index.md
index 3cd5640..0698996 100644
--- a/guide/ops/locations/index.md
+++ b/guide/ops/locations/index.md
@@ -1,15 +1,7 @@
---
title: Locations
layout: website-normal
-children:
-- { section: Clouds }
-- { section: Inheritance and Named Locations, title: Named Locations }
-- { section: Localhost }
-- { section: BYON }
-- { title: More on Clouds, path: more-clouds.md }
-- more-locations.md
-- location-customizers.md
-- ssh-keys.md
+show_inline_children: true
---
Locations are the environments to which Brooklyn deploys applications, including:
@@ -28,431 +20,4 @@ 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`.
-
-### Clouds
-
-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/)):
-
-* `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)
-
-For any of these, of course, Brooklyn needs to be configured with an `identity` and a `credential`:
-
-{% 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, you can instead store them as a [catalog entry]({{ site.path.guide }}/ops/catalog/index.html#locations-in-catalog) or set them in `brooklyn.properties`
-in the `jclouds.<provider>` namespace:
-
-{% highlight bash %}
-brooklyn.location.jclouds.aws-ec2.identity=ABCDEFGHIJKLMNOPQRST
-brooklyn.location.jclouds.aws-ec2.credential=s3cr3tsq1rr3ls3cr3tsq1rr3ls3cr3tsq1rr3l
-{% endhighlight %}
-
-And in this case you can reference the location in YAML with `location: jclouds:aws-ec2`.
-
-Brooklyn irons out many of the differences between clouds so that blueprints run similarly
-in a wide range of locations, including setting up access and configuring images and machine specs.
-The configuration options are described in more detail below.
-
-In some cases, cloud providers have special features or unusual requirements.
-These are outlined in **[More Details for Specific Clouds](more-clouds.html)**.
-
-
-#### OS Initial Login and Setup
-
-Once a machine is provisioned, Brooklyn will normally attempt to log in via SSH and configure the machine sensibly.
-
-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 custom login is particularly useful when using a custom image templates where the cloud-side account
-management logic is not enabled. For example, a vCloud (vCD) template can have guest customization that will change
-the root password. This setting tells AMP to only use the given password, rather than the initial
-randomly generated password that vCD returns. Without this property, there is a race for such templates:
-does Brooklyn manage to create the admin user before the guest customization changes the login and reboots,
-or is the password reset first (the latter means Brooklyn can never ssh to the VM). With this property,
-Brooklyn will always wait for guest customization to complete before it is able to ssh at all. In such
-cases, it is also recommended to use `useJcloudsSshInit=false`.)
-
-Following a successful logon, Brooklyn performs the following steps to configure the machine:
-
-1. creates a new user with the same name as the user `brooklyn` is running as locally
- (this can be overridden with `user`, below).
-
-1. 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
- for the regular Brooklyn user;
- 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="org/apache/brooklyn/location/jclouds" project_subpath="locations/jclouds" %}.
-
-###### 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)
-
-- Where a key pair is registered with a target cloud for logging in to machines,
- Brooklyn can be configured to request this when provisioning VMs by setting `keyPair` (selected clouds only).
- Note that if this `keyPair` does not correspond your default `~/.ssh/id_rsa`, you must typically
- also specify the corresponding `loginUser.privateKeyFile` as a file or URL accessible from Brooklyn.
-
-- A specific VM name (often the hostname) base to be used can be specified by setting `groupId`.
- By default, this name is constructed based on the entity which is creating it,
- including the ID of the app and of the entity.
- (As many cloud portals let you filter views, this can help find a specific entity or all machines for a given application.)
- For more sophisticated control over host naming, you can supply a custom
- {% include java_link.html class_name="CloudMachineNamer" package_path="org/apache/brooklyn/core/location/cloud/names" project_subpath="core" %},
- for example
- `cloudMachineNamer: CustomMachineNamer`.
- {% include java_link.html class_name="CustomMachineNamer" package_path="org/apache/brooklyn/core/location/cloud/names" project_subpath="core" %}
- will use the entity's name or following a template you supply.
- On many clouds, a random suffix will be appended to help guarantee uniqueness;
- this can be removed by setting `vmNameSaltLength: 0` (selected clouds only).
- <!-- TODO jclouds softlayer includes a 3-char hex suffix -->
-
-- A DNS domain name where this host should be placed can be specified with `domainName`
- (in selected clouds only)
-
-- User metadata can be attached using the syntax `userMetadata: { key: value, key2: "value 2" }`
- (or `userMetadata=key=value,key2="value 2"` in a properties file)
-
-- By default, several pieces of user metadata are set to correlate VMs with Brooklyn entities,
- prefixed with `brooklyn-`.
- This user metadata can be omitted by setting `includeBrooklynUserMetadata: false`.
-
-- You can specify the number of attempts Brooklyn should make to create
- machines with `machineCreateAttempts` (jclouds only). This is useful as an efficient low-level fix
- for those occasions when cloud providers give machines that are dead on arrival.
- You can of course also resolve it at a higher level with a policy such as
- {% include java_link.html class_name="ServiceRestarter" package_path="org/apache/brooklyn/policy/ha" project_subpath="policy" %}.
-
-- If you want to investigate failures, set `destroyOnFailure: false`
- to keep failed VM's around. (You'll have to manually clean them up.)
- The default is false: if a VM fails to start, or is never ssh'able, then the VM will be terminated.
-
-
-###### 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 when you log in.)
-
-- Provide a list of URLs to public keys in `extraSshPublicKeyUrls`,
- or the data of one key in `extraSshPublicKeyData`,
- to have additional public keys added to the `authorized_keys` file for logging in.
- (This is supported in most but not all locations.)
-
-- 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`)
-
-- Use `openIptables: true` to automatically configure `iptables`, to open the TCP ports required by
- the software process. One can alternatively use `stopIptables: true` to entirely stop the
- iptables service.
-
-- Use `installDevUrandom: true` to fall back to using `/dev/urandom` rather than `/dev/random`. This setting
- is useful for cloud VMs where there is not enough random entropy, which can cause `/dev/random` to be
- extremely slow (causing `ssh` to be extremely slow to respond).
-
-- Use `useJcloudsSshInit: false` to disable the use of the native jclouds support for initial commands executed
- on the VM (e.g. for creating new users, setting root passwords, etc.). Instead, Brooklyn's ssh support will
- be used. Timeouts and retries are more configurable within Brooklyn itself. Therefore this option is particularly
- recommended when the VM startup is unusual (for example, if guest customizations will cause reboots and/or will
- change login credentials).
-
-- Use `brooklyn.ssh.config.noDeleteAfterExec: true` to keep scripts on the server after execution.
- The contents of the scripts and the stdout/stderr of their execution are available in the Brooklyn web console,
- but sometimes it can also be useful to have them on the box.
- This setting prevents scripts executed on the VMs from being deleted on completion.
- Note that some scripts run periodically so this can eventually fill a disk; it should only be used for dev/test.
-
-###### Custom Template Options
-
-jclouds supports many additional options for configuring how a virtual machine is created and deployed, many of which
-are for cloud-specific features and enhancements. Brooklyn supports some of these, but if what you are looking for is
-not supported directly by Brooklyn, we instead offer a mechanism to set any parameter that is supported by the jclouds
-template options for your cloud.
-
-Part of the process for creating a virtual machine is the creation of a jclouds `TemplateOptions` object. jclouds
-providers extends this with extra options for each cloud - so when using the AWS provider, the object will be of
-type `AWSEC2TemplateOptions`. By [examining the source code](https://github.com/jclouds/jclouds/blob/jclouds-1.9.0/providers/aws-ec2/src/main/java/org/jclouds/aws/ec2/compute/AWSEC2TemplateOptions.java),
-you can see all of the options available to you.
-
-The `templateOptions` config key takes a map. The keys to the map are method names, and Brooklyn will find the method on
-the `TemplateOptions` instance; it then invokes the method with arguments taken from the map value. If a method takes a
-single parameter, then simply give the argument as the value of the key; if the method takes multiple parameters, the
-value of the key should be an array, containing the argument for each parameter.
-
-For example, here is a complete blueprint that sets some AWS EC2 specific options:
-
- location: AWS_eu-west-1
- services:
- - type: org.apache.brooklyn.entity.software.base.EmptySoftwareProcess
- provisioningProperties:
- templateOptions:
- subnetId: subnet-041c8373
- mapNewVolumeToDeviceName: ["/dev/sda1", 100, true]
- securityGroupIds: ['sg-4db68928']
-
-Here you can see that we set three template options:
-
-- `subnetId` is an example of a single parameter method. Brooklyn will effectively try to run the statement
- `templateOptions.subnetId("subnet-041c88373");`
-- `mapNewVolumeToDeviceName` is an example of a multiple parameter method, so the value of the key is an array.
- Brooklyn will effectively true to run the statement `templateOptions.mapNewVolumeToDeviceName("/dev/sda1", 100, true);`
-- `securityGroupIds` demonstrates an ambiguity between the two types; Brooklyn will first try to parse the value as
- a multiple parameter method, but there is no method that matches this parameter. In this case, Brooklyn will next try
- to parse the value as a single parameter method which takes a parameter of type `List`; such a method does exist so
- the operation will succeed.
-
-If the method call cannot be matched to the template options available - for example if you are trying to set an AWS EC2
-specific option but your location is an OpenStack cloud - then a warning is logged and the option is ignored.
-
-
-
-
-See the following resources for more information:
-
-- [AWS VPC issues which may affect users with older AWS accounts](vpc-issues.html)
-- [Amazon EC2 and Amazon Virtual Private Cloud](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-vpc.html#vpc-only-instance-types)
-- [Your Default VPC and Subnets](http://docs.aws.amazon.com/AmazonVPC/latest/UserGuide/default-vpc.html)
-- [Amazon VPC FAQs](http://aws.amazon.com/vpc/faqs/#Default_VPCs)
-
-
-### 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 %}
-
-Named locations can refer to other named locations using `named:xxx` as their value.
-These will inherit the configuration and can override selected keys.
-Properties set in the namespace of the provider (e.g. `b.l.jclouds.aws-ec2.KEY=VALUE`)
-will be inherited by everything which extends AWS
-Sub-prefix strings are also inherited up to `brooklyn.location.*`,
-except that they are filtered for single-word and other
-known keys
-(so that we exclude provider-scoped properties when looking at sub-prefix keys).
-The precedence for configuration defined at different levels is that the value
-defined in the most specific context will apply.
-
-This is rather straightforward and powerful to use,
-although it sounds rather more complicated than it is!
-The examples below should make it clear.
-You could use the following to install
-a public key on all provisioned machines,
-an additional public key in all AWS machines,
-and no extra public key in `prod1`:
-
-<!-- tested in JcloudsLocationResolverTest -->
-{% highlight bash %}
-brooklyn.location.extraSshPublicKeyUrls=http://me.com/public_key
-brooklyn.location.jclouds.aws-ec2.extraSshPublicKeyUrls="[ \"http://me.com/public_key\", \"http://me.com/aws_public_key\" ]"
-brooklyn.location.named.prod1.extraSshPublicKeyUrls=
-{% endhighlight %}
-
-And in the example below, a config key is repeatedly overridden.
-Deploying `location: named:my-extended-aws` will result in an `aws-ec2` machine in `us-west-1` (by inheritance)
-with `VAL6` for `KEY`:
-
-{% highlight bash %}
-brooklyn.location.KEY=VAL1
-brooklyn.location.jclouds.KEY=VAL2
-brooklyn.location.jclouds.aws-ec2.KEY=VAL3
-brooklyn.location.jclouds.aws-ec2@us-west-1.KEY=VAL4
-brooklyn.location.named.my-aws=jclouds:aws-ec2:us-west-1
-brooklyn.location.named.my-aws.KEY=VAL5
-brooklyn.location.named.my-extended-aws=named:my-aws
-brooklyn.location.named.my-extended-aws.KEY=VAL6
-{% endhighlight %}
-
-
-### Localhost
-
-If passwordless ssh login to `localhost` and passwordless `sudo` is enabled on your
-machine, you should be able to deploy blueprints with no special configuration,
-just by specifying `location: localhost` in YAML.
-
-If you use a passpharse or prefer a different key, these can be configured as follows:
-
-{% highlight bash %}
-brooklyn.location.localhost.privateKeyFile=~/.ssh/brooklyn_key
-brooklyn.location.localhost.privateKeyPassphrase=s3cr3tPASSPHRASE
-{% endhighlight %}
-
-If you encounter issues or for more information, see [SSH Keys Localhost Setup](ssh-keys.html#localhost-setup).
-
-If you are normally prompted for a password when executing `sudo` commands, passwordless `sudo` must also be enabled. To enable passwordless `sudo` for your account, a line must be added to the system `/etc/sudoers` file. To edit the file, use the `visudo` command:
-{% highlight bash %}
-sudo visudo
-{% endhighlight %}
-Add this line at the bottom of the file, replacing `username` with your own user:
-{% highlight bash %}
-username ALL=(ALL) NOPASSWD: ALL
-{% endhighlight %}
-If executing the following command does not ask for your password, then `sudo` should be setup correctly:
-{% highlight bash %}
-sudo ls
-{% endhighlight %}
-
-
-### BYON
-
-"Bring-your-own-nodes" mode is useful in production, where machines have been provisioned by someone else,
-and during testing, to cut down provisioning time.
-
-Your nodes must meet the following prerequisites:
-
-- A suitable OS must have been installed on all nodes
-- The node must be running sshd (or similar)
-- the brooklyn user must be able to ssh to each node as root or as a user with passwordless sudo permission. (For more information on SSH keys, see [here](ssh-keys.html).)
-
-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.
-
-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.
-
-{% 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 %}
-
-For more complex host configuration, one can define custom config values per machine. In the example
-below, there will be two machines. The first will be a machine reachable on
-`ssh -i ~/.ssh/brooklyn.pem -p 8022 myuser@50.51.52.53`. The second is a windows machine, reachable
-over WinRM. Each machine has also has a private address (e.g. for within a private network).
-
-{% highlight yaml %}
-location:
- byon:
- hosts:
- - ssh: 50.51.52.53:8022
- privateAddresses: [10.0.0.1]
- privateKeyFile: ~/.ssh/brooklyn.pem
- user: myuser
- - winrm: 50.51.52.54:8985
- privateAddresses: [10.0.0.2]
- password: mypassword
- user: myuser
- osFamily: windows
-{% endhighlight %}
-
-The BYON location also supports a machine chooser, using the config key `byon.machineChooser`.
-This allows one to plugin logic to choose from the set of available machines in the pool. For
-example, additional config could be supplied for each machine. This could be used (during the call
-to `location.obtain()`) to find the config that matches the requirements of the entity being
-provisioned. See `FixedListMachineProvisioningLocation.MACHINE_CHOOSER`.
-
-
-### Other Location Topics
-
-* [More Details on Specific Clouds](more-clouds.html)
-* [More Locations](more-locations.html)
-* [Location Customizers](location-customizers.html)
-* [SSH Keys](ssh-keys.html)
+{% child_content %}
[06/10] brooklyn-docs git commit: Added global support for section
position
Posted by al...@apache.org.
Added global support for section position
Project: http://git-wip-us.apache.org/repos/asf/brooklyn-docs/repo
Commit: http://git-wip-us.apache.org/repos/asf/brooklyn-docs/commit/cfa914de
Tree: http://git-wip-us.apache.org/repos/asf/brooklyn-docs/tree/cfa914de
Diff: http://git-wip-us.apache.org/repos/asf/brooklyn-docs/diff/cfa914de
Branch: refs/heads/master
Commit: cfa914ded11bb466e8bf57793d4fb811f767a049
Parents: 95eb8a4
Author: Duncan Godwin <du...@cloudsoftcorp.com>
Authored: Thu Mar 3 13:46:09 2016 +0000
Committer: Duncan Godwin <du...@cloudsoftcorp.com>
Committed: Mon Mar 7 16:54:43 2016 +0000
----------------------------------------------------------------------
_plugins/page_structure.rb | 114 ++++++++-
_plugins/site_structure.rb | 13 +-
guide/ops/locations/1.1_cloud-setup.md | 86 -------
guide/ops/locations/1_clouds.md | 239 ------------------
.../2_inheritance-and-named-locations.md | 78 ------
guide/ops/locations/3.1_ssh-keys.md | 86 -------
guide/ops/locations/3_localhost.md | 31 ---
guide/ops/locations/4_byon.md | 72 ------
guide/ops/locations/6_more-locations.md | 52 ----
guide/ops/locations/byon.md | 74 ++++++
guide/ops/locations/cloud-specific-setup.md | 88 +++++++
guide/ops/locations/clouds.md | 241 +++++++++++++++++++
guide/ops/locations/index.md | 2 +-
.../inheritance-and-named-locations.md | 80 ++++++
guide/ops/locations/localhost.md | 33 +++
guide/ops/locations/more-locations.md | 17 +-
guide/ops/locations/ssh-keys.md | 13 +-
17 files changed, 648 insertions(+), 671 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/cfa914de/_plugins/page_structure.rb
----------------------------------------------------------------------
diff --git a/_plugins/page_structure.rb b/_plugins/page_structure.rb
index 9579397..2833be3 100644
--- a/_plugins/page_structure.rb
+++ b/_plugins/page_structure.rb
@@ -12,19 +12,112 @@ module PageStructureUtils
class ChildPage
def initialize(yaml, content)
- @page_yaml=yaml
- @page_content=content
- end
- def content()
- @page_content
- end
- def yaml()
- @page_yaml
+ @yaml=yaml
+ @content=content
end
+ attr_accessor :yaml
+ attr_accessor :content
def to_s # called with print / puts
- "YAML : #{@page_yaml}, Content : #{@page_content}"
+ "YAML : #{@yaml}" #, Content : #{@content}"
end
+
+ ##
+ # Sort a list of children by their YAML containing section positions. Do this with Gem:Version
+ #
+ #
+ def self.sortBySectionPositions(yaml)
+ $major = "1"
+ $minor = 1
+ # first check all the child pages are numbered, if not, number them in the order they are
+ yaml.each do |i|
+ if i.yaml['section_position'] == nil
+ i.yaml['section_position'] = $major+"."+$minor.to_s
+ $minor += 1
+ else
+ # Store any major, start incrementing minor
+ $major = i.yaml['section_position'].to_s
+ $minor = 1
+ end
+ end
+
+ # return the comparison between the versions
+ yaml.sort{ |x,y| Gem::Version.new(x.yaml['section_position'].to_s) <=> Gem::Version.new(y.yaml['section_position'].to_s) }
+ end
+ ##
+ # Sorts a list of yaml children, if there's no numbering, use the YAML order to create a numbering
+ #
+ def self.sortYAMLSectionPositions(yaml)
+# puts "a > "+yaml.to_s
+ hashArray = []
+ $major = "1"
+ $minor = 1
+ # first check all the child pages are numbered, if not, number them in the order they are
+ yaml.each do |i|
+ hash = {}
+ # if it's a string, convert it to a hash
+ if i.instance_of? String
+ hash = { "path" => i }
+ else
+ hash = i
+ end
+ if i['section_position'] == nil
+ hash['section_position'] = $major+"."+$minor.to_s
+ $minor += 1
+ else
+ # Store any major, start incrementing minor
+ $major = i['section_position'].to_s
+ $minor = 1
+ end
+ hashArray << hash
+ end
+ # return the comparison between the versions (NB: sort! for in-place sorting)
+ hashArray.sort!{ |x,y| Gem::Version.new(x['section_position'].to_s) <=> Gem::Version.new(y['section_position'].to_s) }
+# puts "2 > "+hashArray.to_s
+ end
+
+ ##
+ # This function looks at all the *.md files at the YAML in the headers and produces a list of children ordered by section_position
+ #
+ #
+ def self.parseChildYAMLFromParent(page)
+ # get the base directory of the current file
+ $baseFile = Dir.pwd+page['dir']
+ # list all of the files in that directory
+ $listings = Dir[$baseFile+"/*.md"]
+ $allPages = []
+
+ for $listing in $listings
+
+ # read the file
+ $fileContent = IO.read($listing)
+ # try and split of any YAML
+ $partitionedFileContent = $fileContent.split('---');
+ # if there's potentially partitioned YAML try and parse it
+ if $partitionedFileContent.size > 2
+ # try and parse the YAML
+ yamlContent = YAML.load($partitionedFileContent[1])
+ # if we can, use it (section_type needs to be one of the allowed)
+ if yamlContent != nil && yamlContent != false && yamlContent['section_type'] != nil && yamlContent['section_type'] != "default"
+
+ if yamlContent['section_type'] == nil
+ # if no section position has been specified, put it at the end
+ yamlContent['section_position'] = Integer::MAX
+ end
+ # if there's YAML, check it has the section_position tag and put it into child pages
+ ($allPages ||= []) << ChildPage.new(yamlContent, $partitionedFileContent[2])
+ end
+ end
+ end
+ $allPages = sortBySectionPositions($allPages)
+ # return the combined content
+ $allPages
+ end
+
+ ##
+ # This function looks in a parent folder for all files in the format <Number>_<title>.md
+ #
+ #
def self.parseChildPagesFromParent(page)
# get the base directory of the current file
$baseFile = Dir.pwd+page['dir']
@@ -75,7 +168,8 @@ module PageStructureUtils
@text = text.strip
end
def render(context)
- $childPages = ChildPage.parseChildPagesFromParent(context['page'])
+# $childPages = ChildPage.parseChildPagesFromParent(context['page'])
+ $childPages = ChildPage.parseChildYAMLFromParent(context['page'])
$content = ""
for $childPage in $childPages
#append the content
http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/cfa914de/_plugins/site_structure.rb
----------------------------------------------------------------------
diff --git a/_plugins/site_structure.rb b/_plugins/site_structure.rb
index 88331b8..5f2d42b 100644
--- a/_plugins/site_structure.rb
+++ b/_plugins/site_structure.rb
@@ -227,8 +227,8 @@ module SiteStructure
# see: page_structure.rb
#
# require show_inline_children to be set to true to show in the menu
- if page['show_inline_children'] == true
- $childPages = PageStructureUtils::ChildPage.parseChildPagesFromParent(page)
+ if page['check_directory_for_children'] == true
+ $childPages = PageStructureUtils::ChildPage.parseChildYAMLFromParent(page)
# add the child pages in before the site structure has been created
for $childPage in $childPages
if $childPage.yaml() != nil && $childPage.yaml() != false
@@ -241,6 +241,14 @@ module SiteStructure
end
end
+ ##
+ # This sorts child pages by the YAML property section_position. This uses a versioning format so 1.1.0 > 1.0.4
+ # Any sections missing numbers will use their current position to determine their order
+ #
+ if data['children']
+ data['children'] = PageStructureUtils::ChildPage.sortYAMLSectionPositions(data['children'])
+ end
+
data['path'] = page.path
if item['href_path']
href_page = find_page_with_path_absolute_or_relative_to(site, render_liquid(site, page, item['href_path']), parent, structure_processed_pages)
@@ -329,6 +337,7 @@ module SiteStructure
end
if (data['children'])
+
data['menu'] = []
puts "children of #{data['path']} - #{data['children']}" if @@verbose
data['children'].each do |child|
http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/cfa914de/guide/ops/locations/1.1_cloud-setup.md
----------------------------------------------------------------------
diff --git a/guide/ops/locations/1.1_cloud-setup.md b/guide/ops/locations/1.1_cloud-setup.md
deleted file mode 100644
index 1f60b5b..0000000
--- a/guide/ops/locations/1.1_cloud-setup.md
+++ /dev/null
@@ -1,86 +0,0 @@
----
-section: Cloud Specific Setup
----
-
-### Cloud Specific Setup
-
-To connect to a Cloud, Brooklyn requires appropriate credentials. These comprise the "identity" and
-"credential" in Brooklyn terminology.
-
-For private clouds (and for some clouds being targeted using a standard API), the "endpoint"
-must also be specified, which is the cloud's URL.
-
-The [jclouds guides](https://jclouds.apache.org/guides) includes documentation on configuring
-different clouds.
-
-
-#### AWS
-
-##### Credentials
-
-AWS has an "access key" and a "secret key", which correspond to Brooklyn's identity and credential
-respectively.
-
-These keys are the way for any programmatic mechanism to access the AWS API.
-
-To generate an access key and a secret key, see [jclouds instructions](http://jclouds.apache.org/guides/aws)
-and [AWS IAM instructions](http://docs.aws.amazon.com/IAM/latest/UserGuide/ManagingCredentials.html).
-
-An example of the expected format is shown below:
-
- brooklyn.location.jclouds.aws-ec2.identity=ABCDEFGHIJKLMNOPQRST
- brooklyn.location.jclouds.aws-ec2.credential=abcdefghijklmnopqrstu+vwxyzabcdefghijklm
-
-
-##### Tidying up after jclouds
-
-Security groups are not always deleted by jclouds. This is due to a limitation in AWS (see
-https://issues.apache.org/jira/browse/JCLOUDS-207). In brief, AWS prevents the security group
-being deleted until there are no VMs using it. However, there is eventual consistency for
-recording which VMs still reference those security groups. After deleting the VM, it can sometimes
-take several minutes before the security group can be deleted. jclouds retries for 3 seconds, but
-does not block for longer.
-
-There is utility written by Cloudsoft for deleting these unused resources:
-http://www.cloudsoftcorp.com/blog/2013/03/tidying-up-after-jclouds.
-
-
-#### Google Compute Engine
-
-##### Credentials
-
-Google Compute Engine (GCE) uses a service account e-mail address for the identity, and a private key
-as the credential.
-
-To obtain these from GCE, see the [jclouds instructions](https://jclouds.apache.org/guides/google).
-
-An example of the expected format is shown below (note the credential is one long line,
-with `\n` to represent the new line characters):
-
- brooklyn.location.jclouds.google-compute-engine.identity=123456789012@developer.gserviceaccount.com
- brooklyn.location.jclouds.google-compute-engine.credential=-----BEGIN RSA PRIVATE KEY-----\nabcdefghijklmnopqrstuvwxyznabcdefghijk/lmnopqrstuvwxyzabcdefghij\nabcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrstuvwxyzabcdefghij+lm\nnopqrstuvwxyzabcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrstuvwxyzabcdefghijklm\nnopqrstuvwxyzabcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrstuvwxy\nzabcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrstuvwxyzabcdefghijk\nlmnopqrstuvwxyzabcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrstuvw\nxyzabcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrstuvwxyzabcdefghi\njklmnopqrstuvwxyzabcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrstu\nvwxyzabcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrstuvwxyzabcdefg\nhijklmnopqrstuvwxyzabcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrs\ntuvwxyzabcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrstuvwxyzabcde\nfghijklmnopqrstuvwxyzabcdefghijklmnopqrstuvw\n-----END RSA PRIVATE KEY-----
-
-
-##### Quotas
-
-GCE accounts can have low default [quotas](https://cloud.google.com/compute/docs/resource-quotas).
-
-It is easy to requesta quota increase by submitting a [quota increase form](https://support.google.com/cloud/answer/6075746?hl=en).
-
-
-##### Networks
-
-GCE accounts often have a limit to the number of networks that can be created. One work around
-is to manually create a network with the required open ports, and to refer to that named network
-in Brooklyn's location configuration.
-
-To create a network, see [GCE network instructions](https://cloud.google.com/compute/docs/networking#networks_1).
-
-For example, for dev/demo purposes an "everything" network could be created that opens all ports.
-
-| Name | everything |
-| Description | opens all tcp ports |
-| Source IP Ranges | 0.0.0.0/0 |
-| Allowed protocols and ports | tcp:0-65535 and udp:0-65535 |
-
-
http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/cfa914de/guide/ops/locations/1_clouds.md
----------------------------------------------------------------------
diff --git a/guide/ops/locations/1_clouds.md b/guide/ops/locations/1_clouds.md
deleted file mode 100644
index 13112cd..0000000
--- a/guide/ops/locations/1_clouds.md
+++ /dev/null
@@ -1,239 +0,0 @@
----
-section: Clouds
----
-
-### Clouds
-
-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/)):
-
-* `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)
-
-For any of these, of course, Brooklyn needs to be configured with an `identity` and a `credential`:
-
-{% 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, you can instead store them as a [catalog entry]({{ site.path.guide }}/ops/catalog/index.html#locations-in-catalog) or set them in `brooklyn.properties`
-in the `jclouds.<provider>` namespace:
-
-{% highlight bash %}
-brooklyn.location.jclouds.aws-ec2.identity=ABCDEFGHIJKLMNOPQRST
-brooklyn.location.jclouds.aws-ec2.credential=s3cr3tsq1rr3ls3cr3tsq1rr3ls3cr3tsq1rr3l
-{% endhighlight %}
-
-And in this case you can reference the location in YAML with `location: jclouds:aws-ec2`.
-
-The Getting Started [template brooklyn.properties]({{ site.path.guide }}/start/brooklyn.properties) contains more examples
-of configuring cloud endpoints, including information on credential types used in different clouds.
-
-#### OS Initial Login and Setup
-
-Once a machine is provisioned, Brooklyn will normally attempt to log in via SSH and configure the machine sensibly.
-
-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 custom login is particularly useful when using a custom image templates where the cloud-side account
-management logic is not enabled. For example, a vCloud (vCD) template can have guest customization that will change
-the root password. This setting tells AMP to only use the given password, rather than the initial
-randomly generated password that vCD returns. Without this property, there is a race for such templates:
-does Brooklyn manage to create the admin user before the guest customization changes the login and reboots,
-or is the password reset first (the latter means Brooklyn can never ssh to the VM). With this property,
-Brooklyn will always wait for guest customization to complete before it is able to ssh at all. In such
-cases, it is also recommended to use `useJcloudsSshInit=false`.)
-
-Following a successful logon, Brooklyn performs the following steps to configure the machine:
-
-1. creates a new user with the same name as the user `brooklyn` is running as locally
- (this can be overridden with `user`, below).
-
-1. 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="org/apache/brooklyn/location/jclouds" project_subpath="locations/jclouds" %}.
-
-###### 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)
-
-- A specific existing key pair known at the cloud to use can be specified with `keyPair`
- (selected clouds only)
-
-- A specific VM name (often the hostname) base to be used can be specified by setting `groupId`.
- By default, this name is constructed based on the entity which is creating it,
- including the ID of the app and of the entity.
- (As many cloud portals let you filter views, this can help find a specific entity or all machines for a given application.)
- For more sophisticated control over host naming, you can supply a custom
- {% include java_link.html class_name="CloudMachineNamer" package_path="org/apache/brooklyn/core/location/cloud/names" project_subpath="core" %},
- for example
- `cloudMachineNamer: CustomMachineNamer`.
- {% include java_link.html class_name="CustomMachineNamer" package_path="org/apache/brooklyn/core/location/cloud/names" project_subpath="core" %}
- will use the entity's name or following a template you supply.
- On many clouds, a random suffix will be appended to help guarantee uniqueness;
- this can be removed by setting `vmNameSaltLength: 0` (selected clouds only).
- <!-- TODO jclouds softlayer includes a 3-char hex suffix -->
-
-- A DNS domain name where this host should be placed can be specified with `domainName`
- (in selected clouds only)
-
-- User metadata can be attached using the syntax `userMetadata: { key: value, key2: "value 2" }`
- (or `userMetadata=key=value,key2="value 2"` in a properties file)
-
-- By default, several pieces of user metadata are set to correlate VMs with Brooklyn entities,
- prefixed with `brooklyn-`.
- This user metadata can be omitted by setting `includeBrooklynUserMetadata: false`.
-
-- You can specify the number of attempts Brooklyn should make to create
- machines with `machineCreateAttempts` (jclouds only). This is useful as an efficient low-level fix
- for those occasions when cloud providers give machines that are dead on arrival.
- You can of course also resolve it at a higher level with a policy such as
- {% include java_link.html class_name="ServiceRestarter" package_path="org/apache/brooklyn/policy/ha" project_subpath="policy" %}.
-
-- If you want to investigate failures, set `destroyOnFailure: false`
- to keep failed VM's around. (You'll have to manually clean them up.)
- The default is false: if a VM fails to start, or is never ssh'able, then the VM will be terminated.
-
- ###### 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 when you log in.)
-
-- Provide a list of URLs to public keys in `extraSshPublicKeyUrls`,
- or the data of one key in `extraSshPublicKeyData`,
- to have additional public keys added to the `authorized_keys` file for logging in.
- (This is supported in most but not all locations.)
-
-- 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`)
-
-- Use `openIptables: true` to automatically configure `iptables`, to open the TCP ports required by
- the software process. One can alternatively use `stopIptables: true` to entirely stop the
- iptables service.
-
-- Use `installDevUrandom: true` to fall back to using `/dev/urandom` rather than `/dev/random`. This setting
- is useful for cloud VMs where there is not enough random entropy, which can cause `/dev/random` to be
- extremely slow (causing `ssh` to be extremely slow to respond).
-
-- Use `useJcloudsSshInit: false` to disable the use of the native jclouds support for initial commands executed
- on the VM (e.g. for creating new users, setting root passwords, etc.). Instead, Brooklyn's ssh support will
- be used. Timeouts and retries are more configurable within Brooklyn itself. Therefore this option is particularly
- recommended when the VM startup is unusual (for example, if guest customizations will cause reboots and/or will
- change login credentials).
-
-- Use `brooklyn.ssh.config.noDeleteAfterExec: true` to keep scripts on the server after execution.
- The contents of the scripts and the stdout/stderr of their execution are available in the Brooklyn web console,
- but sometimes it can also be useful to have them on the box.
- This setting prevents scripts executed on the VMs from being deleted on completion.
- Note that some scripts run periodically so this can eventually fill a disk; it should only be used for dev/test.
-
-###### Custom template options
-
-jclouds supports many additional options for configuring how a virtual machine is created and deployed, many of which
-are for cloud-specific features and enhancements. Brooklyn supports some of these, but if what you are looking for is
-not supported directly by Brooklyn, we instead offer a mechanism to set any parameter that is supported by the jclouds
-template options for your cloud.
-
-Part of the process for creating a virtual machine is the creation of a jclouds `TemplateOptions` object. jclouds
-providers extends this with extra options for each cloud - so when using the AWS provider, the object will be of
-type `AWSEC2TemplateOptions`. By [examining the source code](https://github.com/jclouds/jclouds/blob/jclouds-1.9.0/providers/aws-ec2/src/main/java/org/jclouds/aws/ec2/compute/AWSEC2TemplateOptions.java),
-you can see all of the options available to you.
-
-The `templateOptions` config key takes a map. The keys to the map are method names, and Brooklyn will find the method on
-the `TemplateOptions` instance; it then invokes the method with arguments taken from the map value. If a method takes a
-single parameter, then simply give the argument as the value of the key; if the method takes multiple parameters, the
-value of the key should be an array, containing the argument for each parameter.
-
-For example, here is a complete blueprint that sets some AWS EC2 specific options:
-
- location: AWS_eu-west-1
- services:
- - type: org.apache.brooklyn.entity.software.base.EmptySoftwareProcess
- provisioningProperties:
- templateOptions:
- subnetId: subnet-041c8373
- mapNewVolumeToDeviceName: ["/dev/sda1", 100, true]
- securityGroupIds: ['sg-4db68928']
-
-Here you can see that we set three template options:
-
-- `subnetId` is an example of a single parameter method. Brooklyn will effectively try to run the statement
- `templateOptions.subnetId("subnet-041c88373");`
-- `mapNewVolumeToDeviceName` is an example of a multiple parameter method, so the value of the key is an array.
- Brooklyn will effectively true to run the statement `templateOptions.mapNewVolumeToDeviceName("/dev/sda1", 100, true);`
-- `securityGroupIds` demonstrates an ambiguity between the two types; Brooklyn will first try to parse the value as
- a multiple parameter method, but there is no method that matches this parameter. In this case, Brooklyn will next try
- to parse the value as a single parameter method which takes a parameter of type `List`; such a method does exist so
- the operation will succeed.
-
-If the method call cannot be matched to the template options available - for example if you are trying to set an AWS EC2
-specific option but your location is an OpenStack cloud - then a warning is logged and the option is ignored.
-
-
-
-
-See the following resources for more information:
-
-- [AWS VPC issues which may affect users with older AWS accounts](vpc-issues.html)
-- [Amazon EC2 and Amazon Virtual Private Cloud](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-vpc.html#vpc-only-instance-types)
-- [Your Default VPC and Subnets](http://docs.aws.amazon.com/AmazonVPC/latest/UserGuide/default-vpc.html)
-- [Amazon VPC FAQs](http://aws.amazon.com/vpc/faqs/#Default_VPCs)
-
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/cfa914de/guide/ops/locations/2_inheritance-and-named-locations.md
----------------------------------------------------------------------
diff --git a/guide/ops/locations/2_inheritance-and-named-locations.md b/guide/ops/locations/2_inheritance-and-named-locations.md
deleted file mode 100644
index 3e7b50a..0000000
--- a/guide/ops/locations/2_inheritance-and-named-locations.md
+++ /dev/null
@@ -1,78 +0,0 @@
----
-section: Inheritance and Named Locations
-title: Named Locations
----
-
-### 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 %}
-
-Named locations can refer to other named locations using `named:xxx` as their value.
-These will inherit the configuration and can override selected keys.
-Properties set in the namespace of the provider (e.g. `b.l.jclouds.aws-ec2.KEY=VALUE`)
-will be inherited by everything which extends AWS
-Sub-prefix strings are also inherited up to `brooklyn.location.*`,
-except that they are filtered for single-word and other
-known keys
-(so that we exclude provider-scoped properties when looking at sub-prefix keys).
-The precedence for configuration defined at different levels is that the value
-defined in the most specific context will apply.
-
-This is rather straightforward and powerful to use,
-although it sounds rather more complicated than it is!
-The examples below should make it clear.
-You could use the following to install
-a public key on all provisioned machines,
-an additional public key in all AWS machines,
-and no extra public key in `prod1`:
-
-<!-- tested in JcloudsLocationResolverTest -->
-{% highlight bash %}
-brooklyn.location.extraSshPublicKeyUrls=http://me.com/public_key
-brooklyn.location.jclouds.aws-ec2.extraSshPublicKeyUrls="[ \"http://me.com/public_key\", \"http://me.com/aws_public_key\" ]"
-brooklyn.location.named.prod1.extraSshPublicKeyUrls=
-{% endhighlight %}
-
-And in the example below, a config key is repeatedly overridden.
-Deploying `location: named:my-extended-aws` will result in an `aws-ec2` machine in `us-west-1` (by inheritance)
-with `VAL6` for `KEY`:
-
-{% highlight bash %}
-brooklyn.location.KEY=VAL1
-brooklyn.location.jclouds.KEY=VAL2
-brooklyn.location.jclouds.aws-ec2.KEY=VAL3
-brooklyn.location.jclouds.aws-ec2@us-west-1.KEY=VAL4
-brooklyn.location.named.my-aws=jclouds:aws-ec2:us-west-1
-brooklyn.location.named.my-aws.KEY=VAL5
-brooklyn.location.named.my-extended-aws=named:my-aws
-brooklyn.location.named.my-extended-aws.KEY=VAL6
-{% endhighlight %}
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/cfa914de/guide/ops/locations/3.1_ssh-keys.md
----------------------------------------------------------------------
diff --git a/guide/ops/locations/3.1_ssh-keys.md b/guide/ops/locations/3.1_ssh-keys.md
deleted file mode 100644
index 4adda4b..0000000
--- a/guide/ops/locations/3.1_ssh-keys.md
+++ /dev/null
@@ -1,86 +0,0 @@
----
-section: SSH Keys
----
-
-### SSH Keys
-
-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 %}
-
-Now verify that your setup by running the command: `ssh localhost echo hello world`
-
-If your setup is correct, you should see `hello world` printed back at you.
-
-On the first connection, you may see a message similar to this:
-
-<pre>
-The authenticity of host 'localhost (::1)' can't be established.
-RSA key fingerprint is 7b:e3:8e:c6:5b:2a:05:a1:7c:8a:cf:d1:6a:83:c2:ad.
-Are you sure you want to continue connecting (yes/no)?
-</pre>
-
-Simply answer 'yes' and then repeat the command again.
-
-If this isn't the case, see below.
-
-
-
-
-#### Potential Problems
-
-* **MacOS user?** In addition to the above, enable "Remote Login" in "System Preferences > Sharing".
-
-* **Got a passphrase?** Set `brooklyn.location.localhost.privateKeyPassphrase`
- as described [here](index.html#os-setup).
- If you're not sure, or you don't know what a passphrase is, you can test this by executing `ssh-keygen -y`.
- If it does *not* ask for a passphrase, then your key has no passphrase.
- If your key does have a passphrase, you can remove it by running `ssh-keygen -p`.
-
-* Check that you have an `~/.ssh/id_rsa` file (or `id_dsa`) and a corresponding public key with a `.pub` extension;
- if not, create one as described above
-
-* `~/.ssh/` or files in that directory may have permissions they shouldn't:
- they should be visible only to the user (apart from public keys),
- both on the source machine and the target machine.
- You can verify this with `ls -l ~/.ssh/`: lines should start with `-rw-------` or `-r--------` (or `-rwx------` for directories).
- If it does not, execute `chmod go-rwx ~/.ssh ~/.ssh/*`.
-
-* 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/brooklyn-docs/blob/cfa914de/guide/ops/locations/3_localhost.md
----------------------------------------------------------------------
diff --git a/guide/ops/locations/3_localhost.md b/guide/ops/locations/3_localhost.md
deleted file mode 100644
index 13e1435..0000000
--- a/guide/ops/locations/3_localhost.md
+++ /dev/null
@@ -1,31 +0,0 @@
----
-section: Localhost
----
-
-### Localhost
-
-If passwordless ssh login to `localhost` and passwordless `sudo` is enabled on your
-machine, you should be able to deploy blueprints with no special configuration,
-just by specifying `location: localhost` in YAML.
-
-If you use a passpharse or prefer a different key, these can be configured as follows:
-
-{% highlight bash %}
-brooklyn.location.localhost.privateKeyFile=~/.ssh/brooklyn_key
-brooklyn.location.localhost.privateKeyPassphrase=s3cr3tPASSPHRASE
-{% endhighlight %}
-
-If you encounter issues or for more information, see [SSH Keys Localhost Setup](ssh-keys.html#localhost-setup).
-
-If you are normally prompted for a password when executing `sudo` commands, passwordless `sudo` must also be enabled. To enable passwordless `sudo` for your account, a line must be added to the system `/etc/sudoers` file. To edit the file, use the `visudo` command:
-{% highlight bash %}
-sudo visudo
-{% endhighlight %}
-Add this line at the bottom of the file, replacing `username` with your own user:
-{% highlight bash %}
-username ALL=(ALL) NOPASSWD: ALL
-{% endhighlight %}
-If executing the following command does not ask for your password, then `sudo` should be setup correctly:
-{% highlight bash %}
-sudo ls
-{% endhighlight %}
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/cfa914de/guide/ops/locations/4_byon.md
----------------------------------------------------------------------
diff --git a/guide/ops/locations/4_byon.md b/guide/ops/locations/4_byon.md
deleted file mode 100644
index 42a52ca..0000000
--- a/guide/ops/locations/4_byon.md
+++ /dev/null
@@ -1,72 +0,0 @@
----
-section: BYON
----
-
-### BYON
-
-"Bring-your-own-nodes" mode is useful in production, where machines have been provisioned by someone else,
-and during testing, to cut down provisioning time.
-
-Your nodes must meet the following prerequisites:
-
-- A suitable OS must have been installed on all nodes
-- The node must be running sshd (or similar)
-- the brooklyn user must be able to ssh to each node as root or as a user with passwordless sudo permission. (For more information on SSH keys, see [here](ssh-keys.html).)
-
-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.
-
-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.
-
-{% 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 %}
-
-For more complex host configuration, one can define custom config values per machine. In the example
-below, there will be two machines. The first will be a machine reachable on
-`ssh -i ~/.ssh/brooklyn.pem -p 8022 myuser@50.51.52.53`. The second is a windows machine, reachable
-over WinRM. Each machine has also has a private address (e.g. for within a private network).
-
-{% highlight yaml %}
-location:
- byon:
- hosts:
- - ssh: 50.51.52.53:8022
- privateAddresses: [10.0.0.1]
- privateKeyFile: ~/.ssh/brooklyn.pem
- user: myuser
- - winrm: 50.51.52.54:8985
- privateAddresses: [10.0.0.2]
- password: mypassword
- user: myuser
- osFamily: windows
-{% endhighlight %}
-
-The BYON location also supports a machine chooser, using the config key `byon.machineChooser`.
-This allows one to plugin logic to choose from the set of available machines in the pool. For
-example, additional config could be supplied for each machine. This could be used (during the call
-to `location.obtain()`) to find the config that matches the requirements of the entity being
-provisioned. See `FixedListMachineProvisioningLocation.MACHINE_CHOOSER`.
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/cfa914de/guide/ops/locations/6_more-locations.md
----------------------------------------------------------------------
diff --git a/guide/ops/locations/6_more-locations.md b/guide/ops/locations/6_more-locations.md
deleted file mode 100644
index 39099d9..0000000
--- a/guide/ops/locations/6_more-locations.md
+++ /dev/null
@@ -1,52 +0,0 @@
----
-section: Specialized Locations
----
-
-### Specialized Locations
-
-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: org.apache.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 class_name="ServerPool" package_path="org/apache/brooklyn/entity/machine/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/brooklyn-docs/blob/cfa914de/guide/ops/locations/byon.md
----------------------------------------------------------------------
diff --git a/guide/ops/locations/byon.md b/guide/ops/locations/byon.md
new file mode 100644
index 0000000..9088754
--- /dev/null
+++ b/guide/ops/locations/byon.md
@@ -0,0 +1,74 @@
+---
+section: BYON
+section_position: 4
+section_type: inline
+---
+
+### BYON
+
+"Bring-your-own-nodes" mode is useful in production, where machines have been provisioned by someone else,
+and during testing, to cut down provisioning time.
+
+Your nodes must meet the following prerequisites:
+
+- A suitable OS must have been installed on all nodes
+- The node must be running sshd (or similar)
+- the brooklyn user must be able to ssh to each node as root or as a user with passwordless sudo permission. (For more information on SSH keys, see [here](ssh-keys.html).)
+
+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.
+
+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.
+
+{% 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 %}
+
+For more complex host configuration, one can define custom config values per machine. In the example
+below, there will be two machines. The first will be a machine reachable on
+`ssh -i ~/.ssh/brooklyn.pem -p 8022 myuser@50.51.52.53`. The second is a windows machine, reachable
+over WinRM. Each machine has also has a private address (e.g. for within a private network).
+
+{% highlight yaml %}
+location:
+ byon:
+ hosts:
+ - ssh: 50.51.52.53:8022
+ privateAddresses: [10.0.0.1]
+ privateKeyFile: ~/.ssh/brooklyn.pem
+ user: myuser
+ - winrm: 50.51.52.54:8985
+ privateAddresses: [10.0.0.2]
+ password: mypassword
+ user: myuser
+ osFamily: windows
+{% endhighlight %}
+
+The BYON location also supports a machine chooser, using the config key `byon.machineChooser`.
+This allows one to plugin logic to choose from the set of available machines in the pool. For
+example, additional config could be supplied for each machine. This could be used (during the call
+to `location.obtain()`) to find the config that matches the requirements of the entity being
+provisioned. See `FixedListMachineProvisioningLocation.MACHINE_CHOOSER`.
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/cfa914de/guide/ops/locations/cloud-specific-setup.md
----------------------------------------------------------------------
diff --git a/guide/ops/locations/cloud-specific-setup.md b/guide/ops/locations/cloud-specific-setup.md
new file mode 100644
index 0000000..56a701a
--- /dev/null
+++ b/guide/ops/locations/cloud-specific-setup.md
@@ -0,0 +1,88 @@
+---
+section: Cloud Specific Setup
+section_type: inline
+section_position: 1.1
+---
+
+### Cloud Specific Setup
+
+To connect to a Cloud, Brooklyn requires appropriate credentials. These comprise the "identity" and
+"credential" in Brooklyn terminology.
+
+For private clouds (and for some clouds being targeted using a standard API), the "endpoint"
+must also be specified, which is the cloud's URL.
+
+The [jclouds guides](https://jclouds.apache.org/guides) includes documentation on configuring
+different clouds.
+
+
+#### AWS
+
+##### Credentials
+
+AWS has an "access key" and a "secret key", which correspond to Brooklyn's identity and credential
+respectively.
+
+These keys are the way for any programmatic mechanism to access the AWS API.
+
+To generate an access key and a secret key, see [jclouds instructions](http://jclouds.apache.org/guides/aws)
+and [AWS IAM instructions](http://docs.aws.amazon.com/IAM/latest/UserGuide/ManagingCredentials.html).
+
+An example of the expected format is shown below:
+
+ brooklyn.location.jclouds.aws-ec2.identity=ABCDEFGHIJKLMNOPQRST
+ brooklyn.location.jclouds.aws-ec2.credential=abcdefghijklmnopqrstu+vwxyzabcdefghijklm
+
+
+##### Tidying up after jclouds
+
+Security groups are not always deleted by jclouds. This is due to a limitation in AWS (see
+https://issues.apache.org/jira/browse/JCLOUDS-207). In brief, AWS prevents the security group
+being deleted until there are no VMs using it. However, there is eventual consistency for
+recording which VMs still reference those security groups. After deleting the VM, it can sometimes
+take several minutes before the security group can be deleted. jclouds retries for 3 seconds, but
+does not block for longer.
+
+There is utility written by Cloudsoft for deleting these unused resources:
+http://www.cloudsoftcorp.com/blog/2013/03/tidying-up-after-jclouds.
+
+
+#### Google Compute Engine
+
+##### Credentials
+
+Google Compute Engine (GCE) uses a service account e-mail address for the identity, and a private key
+as the credential.
+
+To obtain these from GCE, see the [jclouds instructions](https://jclouds.apache.org/guides/google).
+
+An example of the expected format is shown below (note the credential is one long line,
+with `\n` to represent the new line characters):
+
+ brooklyn.location.jclouds.google-compute-engine.identity=123456789012@developer.gserviceaccount.com
+ brooklyn.location.jclouds.google-compute-engine.credential=-----BEGIN RSA PRIVATE KEY-----\nabcdefghijklmnopqrstuvwxyznabcdefghijk/lmnopqrstuvwxyzabcdefghij\nabcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrstuvwxyzabcdefghij+lm\nnopqrstuvwxyzabcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrstuvwxyzabcdefghijklm\nnopqrstuvwxyzabcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrstuvwxy\nzabcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrstuvwxyzabcdefghijk\nlmnopqrstuvwxyzabcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrstuvw\nxyzabcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrstuvwxyzabcdefghi\njklmnopqrstuvwxyzabcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrstu\nvwxyzabcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrstuvwxyzabcdefg\nhijklmnopqrstuvwxyzabcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrs\ntuvwxyzabcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrstuvwxyzabcde\nfghijklmnopqrstuvwxyzabcdefghijklmnopqrstuvw\n-----END RSA PRIVATE KEY-----
+
+
+##### Quotas
+
+GCE accounts can have low default [quotas](https://cloud.google.com/compute/docs/resource-quotas).
+
+It is easy to requesta quota increase by submitting a [quota increase form](https://support.google.com/cloud/answer/6075746?hl=en).
+
+
+##### Networks
+
+GCE accounts often have a limit to the number of networks that can be created. One work around
+is to manually create a network with the required open ports, and to refer to that named network
+in Brooklyn's location configuration.
+
+To create a network, see [GCE network instructions](https://cloud.google.com/compute/docs/networking#networks_1).
+
+For example, for dev/demo purposes an "everything" network could be created that opens all ports.
+
+| Name | everything |
+| Description | opens all tcp ports |
+| Source IP Ranges | 0.0.0.0/0 |
+| Allowed protocols and ports | tcp:0-65535 and udp:0-65535 |
+
+
http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/cfa914de/guide/ops/locations/clouds.md
----------------------------------------------------------------------
diff --git a/guide/ops/locations/clouds.md b/guide/ops/locations/clouds.md
new file mode 100644
index 0000000..90f9eb4
--- /dev/null
+++ b/guide/ops/locations/clouds.md
@@ -0,0 +1,241 @@
+---
+section: Clouds
+section_type: inline
+section_position: 1.0
+---
+
+### Clouds
+
+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/)):
+
+* `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)
+
+For any of these, of course, Brooklyn needs to be configured with an `identity` and a `credential`:
+
+{% 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, you can instead store them as a [catalog entry]({{ site.path.guide }}/ops/catalog/index.html#locations-in-catalog) or set them in `brooklyn.properties`
+in the `jclouds.<provider>` namespace:
+
+{% highlight bash %}
+brooklyn.location.jclouds.aws-ec2.identity=ABCDEFGHIJKLMNOPQRST
+brooklyn.location.jclouds.aws-ec2.credential=s3cr3tsq1rr3ls3cr3tsq1rr3ls3cr3tsq1rr3l
+{% endhighlight %}
+
+And in this case you can reference the location in YAML with `location: jclouds:aws-ec2`.
+
+The Getting Started [template brooklyn.properties]({{ site.path.guide }}/start/brooklyn.properties) contains more examples
+of configuring cloud endpoints, including information on credential types used in different clouds.
+
+#### OS Initial Login and Setup
+
+Once a machine is provisioned, Brooklyn will normally attempt to log in via SSH and configure the machine sensibly.
+
+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 custom login is particularly useful when using a custom image templates where the cloud-side account
+management logic is not enabled. For example, a vCloud (vCD) template can have guest customization that will change
+the root password. This setting tells AMP to only use the given password, rather than the initial
+randomly generated password that vCD returns. Without this property, there is a race for such templates:
+does Brooklyn manage to create the admin user before the guest customization changes the login and reboots,
+or is the password reset first (the latter means Brooklyn can never ssh to the VM). With this property,
+Brooklyn will always wait for guest customization to complete before it is able to ssh at all. In such
+cases, it is also recommended to use `useJcloudsSshInit=false`.)
+
+Following a successful logon, Brooklyn performs the following steps to configure the machine:
+
+1. creates a new user with the same name as the user `brooklyn` is running as locally
+ (this can be overridden with `user`, below).
+
+1. 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="org/apache/brooklyn/location/jclouds" project_subpath="locations/jclouds" %}.
+
+###### 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)
+
+- A specific existing key pair known at the cloud to use can be specified with `keyPair`
+ (selected clouds only)
+
+- A specific VM name (often the hostname) base to be used can be specified by setting `groupId`.
+ By default, this name is constructed based on the entity which is creating it,
+ including the ID of the app and of the entity.
+ (As many cloud portals let you filter views, this can help find a specific entity or all machines for a given application.)
+ For more sophisticated control over host naming, you can supply a custom
+ {% include java_link.html class_name="CloudMachineNamer" package_path="org/apache/brooklyn/core/location/cloud/names" project_subpath="core" %},
+ for example
+ `cloudMachineNamer: CustomMachineNamer`.
+ {% include java_link.html class_name="CustomMachineNamer" package_path="org/apache/brooklyn/core/location/cloud/names" project_subpath="core" %}
+ will use the entity's name or following a template you supply.
+ On many clouds, a random suffix will be appended to help guarantee uniqueness;
+ this can be removed by setting `vmNameSaltLength: 0` (selected clouds only).
+ <!-- TODO jclouds softlayer includes a 3-char hex suffix -->
+
+- A DNS domain name where this host should be placed can be specified with `domainName`
+ (in selected clouds only)
+
+- User metadata can be attached using the syntax `userMetadata: { key: value, key2: "value 2" }`
+ (or `userMetadata=key=value,key2="value 2"` in a properties file)
+
+- By default, several pieces of user metadata are set to correlate VMs with Brooklyn entities,
+ prefixed with `brooklyn-`.
+ This user metadata can be omitted by setting `includeBrooklynUserMetadata: false`.
+
+- You can specify the number of attempts Brooklyn should make to create
+ machines with `machineCreateAttempts` (jclouds only). This is useful as an efficient low-level fix
+ for those occasions when cloud providers give machines that are dead on arrival.
+ You can of course also resolve it at a higher level with a policy such as
+ {% include java_link.html class_name="ServiceRestarter" package_path="org/apache/brooklyn/policy/ha" project_subpath="policy" %}.
+
+- If you want to investigate failures, set `destroyOnFailure: false`
+ to keep failed VM's around. (You'll have to manually clean them up.)
+ The default is false: if a VM fails to start, or is never ssh'able, then the VM will be terminated.
+
+ ###### 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 when you log in.)
+
+- Provide a list of URLs to public keys in `extraSshPublicKeyUrls`,
+ or the data of one key in `extraSshPublicKeyData`,
+ to have additional public keys added to the `authorized_keys` file for logging in.
+ (This is supported in most but not all locations.)
+
+- 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`)
+
+- Use `openIptables: true` to automatically configure `iptables`, to open the TCP ports required by
+ the software process. One can alternatively use `stopIptables: true` to entirely stop the
+ iptables service.
+
+- Use `installDevUrandom: true` to fall back to using `/dev/urandom` rather than `/dev/random`. This setting
+ is useful for cloud VMs where there is not enough random entropy, which can cause `/dev/random` to be
+ extremely slow (causing `ssh` to be extremely slow to respond).
+
+- Use `useJcloudsSshInit: false` to disable the use of the native jclouds support for initial commands executed
+ on the VM (e.g. for creating new users, setting root passwords, etc.). Instead, Brooklyn's ssh support will
+ be used. Timeouts and retries are more configurable within Brooklyn itself. Therefore this option is particularly
+ recommended when the VM startup is unusual (for example, if guest customizations will cause reboots and/or will
+ change login credentials).
+
+- Use `brooklyn.ssh.config.noDeleteAfterExec: true` to keep scripts on the server after execution.
+ The contents of the scripts and the stdout/stderr of their execution are available in the Brooklyn web console,
+ but sometimes it can also be useful to have them on the box.
+ This setting prevents scripts executed on the VMs from being deleted on completion.
+ Note that some scripts run periodically so this can eventually fill a disk; it should only be used for dev/test.
+
+###### Custom template options
+
+jclouds supports many additional options for configuring how a virtual machine is created and deployed, many of which
+are for cloud-specific features and enhancements. Brooklyn supports some of these, but if what you are looking for is
+not supported directly by Brooklyn, we instead offer a mechanism to set any parameter that is supported by the jclouds
+template options for your cloud.
+
+Part of the process for creating a virtual machine is the creation of a jclouds `TemplateOptions` object. jclouds
+providers extends this with extra options for each cloud - so when using the AWS provider, the object will be of
+type `AWSEC2TemplateOptions`. By [examining the source code](https://github.com/jclouds/jclouds/blob/jclouds-1.9.0/providers/aws-ec2/src/main/java/org/jclouds/aws/ec2/compute/AWSEC2TemplateOptions.java),
+you can see all of the options available to you.
+
+The `templateOptions` config key takes a map. The keys to the map are method names, and Brooklyn will find the method on
+the `TemplateOptions` instance; it then invokes the method with arguments taken from the map value. If a method takes a
+single parameter, then simply give the argument as the value of the key; if the method takes multiple parameters, the
+value of the key should be an array, containing the argument for each parameter.
+
+For example, here is a complete blueprint that sets some AWS EC2 specific options:
+
+ location: AWS_eu-west-1
+ services:
+ - type: org.apache.brooklyn.entity.software.base.EmptySoftwareProcess
+ provisioningProperties:
+ templateOptions:
+ subnetId: subnet-041c8373
+ mapNewVolumeToDeviceName: ["/dev/sda1", 100, true]
+ securityGroupIds: ['sg-4db68928']
+
+Here you can see that we set three template options:
+
+- `subnetId` is an example of a single parameter method. Brooklyn will effectively try to run the statement
+ `templateOptions.subnetId("subnet-041c88373");`
+- `mapNewVolumeToDeviceName` is an example of a multiple parameter method, so the value of the key is an array.
+ Brooklyn will effectively true to run the statement `templateOptions.mapNewVolumeToDeviceName("/dev/sda1", 100, true);`
+- `securityGroupIds` demonstrates an ambiguity between the two types; Brooklyn will first try to parse the value as
+ a multiple parameter method, but there is no method that matches this parameter. In this case, Brooklyn will next try
+ to parse the value as a single parameter method which takes a parameter of type `List`; such a method does exist so
+ the operation will succeed.
+
+If the method call cannot be matched to the template options available - for example if you are trying to set an AWS EC2
+specific option but your location is an OpenStack cloud - then a warning is logged and the option is ignored.
+
+
+
+
+See the following resources for more information:
+
+- [AWS VPC issues which may affect users with older AWS accounts](vpc-issues.html)
+- [Amazon EC2 and Amazon Virtual Private Cloud](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-vpc.html#vpc-only-instance-types)
+- [Your Default VPC and Subnets](http://docs.aws.amazon.com/AmazonVPC/latest/UserGuide/default-vpc.html)
+- [Amazon VPC FAQs](http://aws.amazon.com/vpc/faqs/#Default_VPCs)
+
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/cfa914de/guide/ops/locations/index.md
----------------------------------------------------------------------
diff --git a/guide/ops/locations/index.md b/guide/ops/locations/index.md
index 0698996..dc0c1dc 100644
--- a/guide/ops/locations/index.md
+++ b/guide/ops/locations/index.md
@@ -1,7 +1,7 @@
---
title: Locations
layout: website-normal
-show_inline_children: true
+check_directory_for_children: true
---
Locations are the environments to which Brooklyn deploys applications, including:
http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/cfa914de/guide/ops/locations/inheritance-and-named-locations.md
----------------------------------------------------------------------
diff --git a/guide/ops/locations/inheritance-and-named-locations.md b/guide/ops/locations/inheritance-and-named-locations.md
new file mode 100644
index 0000000..9854fea
--- /dev/null
+++ b/guide/ops/locations/inheritance-and-named-locations.md
@@ -0,0 +1,80 @@
+---
+section: Inheritance and Named Locations
+title: Named Locations
+section_type: inline
+section_position: 2
+---
+
+### 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 %}
+
+Named locations can refer to other named locations using `named:xxx` as their value.
+These will inherit the configuration and can override selected keys.
+Properties set in the namespace of the provider (e.g. `b.l.jclouds.aws-ec2.KEY=VALUE`)
+will be inherited by everything which extends AWS
+Sub-prefix strings are also inherited up to `brooklyn.location.*`,
+except that they are filtered for single-word and other
+known keys
+(so that we exclude provider-scoped properties when looking at sub-prefix keys).
+The precedence for configuration defined at different levels is that the value
+defined in the most specific context will apply.
+
+This is rather straightforward and powerful to use,
+although it sounds rather more complicated than it is!
+The examples below should make it clear.
+You could use the following to install
+a public key on all provisioned machines,
+an additional public key in all AWS machines,
+and no extra public key in `prod1`:
+
+<!-- tested in JcloudsLocationResolverTest -->
+{% highlight bash %}
+brooklyn.location.extraSshPublicKeyUrls=http://me.com/public_key
+brooklyn.location.jclouds.aws-ec2.extraSshPublicKeyUrls="[ \"http://me.com/public_key\", \"http://me.com/aws_public_key\" ]"
+brooklyn.location.named.prod1.extraSshPublicKeyUrls=
+{% endhighlight %}
+
+And in the example below, a config key is repeatedly overridden.
+Deploying `location: named:my-extended-aws` will result in an `aws-ec2` machine in `us-west-1` (by inheritance)
+with `VAL6` for `KEY`:
+
+{% highlight bash %}
+brooklyn.location.KEY=VAL1
+brooklyn.location.jclouds.KEY=VAL2
+brooklyn.location.jclouds.aws-ec2.KEY=VAL3
+brooklyn.location.jclouds.aws-ec2@us-west-1.KEY=VAL4
+brooklyn.location.named.my-aws=jclouds:aws-ec2:us-west-1
+brooklyn.location.named.my-aws.KEY=VAL5
+brooklyn.location.named.my-extended-aws=named:my-aws
+brooklyn.location.named.my-extended-aws.KEY=VAL6
+{% endhighlight %}
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/cfa914de/guide/ops/locations/localhost.md
----------------------------------------------------------------------
diff --git a/guide/ops/locations/localhost.md b/guide/ops/locations/localhost.md
new file mode 100644
index 0000000..86ef5b5
--- /dev/null
+++ b/guide/ops/locations/localhost.md
@@ -0,0 +1,33 @@
+---
+section: Localhost
+section_position: 3
+section_type: inline
+---
+
+### Localhost
+
+If passwordless ssh login to `localhost` and passwordless `sudo` is enabled on your
+machine, you should be able to deploy blueprints with no special configuration,
+just by specifying `location: localhost` in YAML.
+
+If you use a passpharse or prefer a different key, these can be configured as follows:
+
+{% highlight bash %}
+brooklyn.location.localhost.privateKeyFile=~/.ssh/brooklyn_key
+brooklyn.location.localhost.privateKeyPassphrase=s3cr3tPASSPHRASE
+{% endhighlight %}
+
+If you encounter issues or for more information, see [SSH Keys Localhost Setup](ssh-keys.html#localhost-setup).
+
+If you are normally prompted for a password when executing `sudo` commands, passwordless `sudo` must also be enabled. To enable passwordless `sudo` for your account, a line must be added to the system `/etc/sudoers` file. To edit the file, use the `visudo` command:
+{% highlight bash %}
+sudo visudo
+{% endhighlight %}
+Add this line at the bottom of the file, replacing `username` with your own user:
+{% highlight bash %}
+username ALL=(ALL) NOPASSWD: ALL
+{% endhighlight %}
+If executing the following command does not ask for your password, then `sudo` should be setup correctly:
+{% highlight bash %}
+sudo ls
+{% endhighlight %}
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/cfa914de/guide/ops/locations/more-locations.md
----------------------------------------------------------------------
diff --git a/guide/ops/locations/more-locations.md b/guide/ops/locations/more-locations.md
index 0a00bf5..2ed2c83 100644
--- a/guide/ops/locations/more-locations.md
+++ b/guide/ops/locations/more-locations.md
@@ -1,15 +1,14 @@
---
-title: More Locations
-layout: website-normal
-children:
-- { section: Single Host }
-- { section: The Multi Location }
-- { section: The Server Pool }
+section: Specialized Locations
+section_position: 5
+section_type: inline
---
+### Specialized Locations
+
Some additional location types are supported for specialized situations:
-### Single Host
+#### 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.
@@ -25,7 +24,7 @@ services:
Or, in `brooklyn.properties`, set `brooklyn.location.named.host1=host:(192.168.0.1)`.
-### The Multi Location
+#### The Multi Location
The spec `multi` allows multiple locations, specified as `targets`,
to be combined and treated as one location.
@@ -48,7 +47,7 @@ and then to `acct2`.
-### The Server Pool
+#### The Server Pool
The {% include java_link.html class_name="ServerPool" package_path="org/apache/brooklyn/entity/machine/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/brooklyn-docs/blob/cfa914de/guide/ops/locations/ssh-keys.md
----------------------------------------------------------------------
diff --git a/guide/ops/locations/ssh-keys.md b/guide/ops/locations/ssh-keys.md
index f805253..e49d031 100644
--- a/guide/ops/locations/ssh-keys.md
+++ b/guide/ops/locations/ssh-keys.md
@@ -1,8 +1,11 @@
---
-title: SSH Keys
-layout: website-normal
+section: SSH Keys
+section_position: 3.1
+section_type: inline
---
+### SSH Keys
+
SSH keys are one of the simplest and most secure ways to access remote servers.
They consist of two parts:
@@ -21,7 +24,7 @@ the remote machine can confirm it is you accessing it (if no one else has the pr
and no one snooping on the network can decrypt of any of the traffic.
-### Creating an SSH Key
+#### Creating an SSH Key
If you don't have an SSH key, create one with:
@@ -30,7 +33,7 @@ $ ssh-keygen -t rsa -N "" -f ~/.ssh/id_rsa
{% endhighlight %}
-### Localhost Setup
+#### 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:
@@ -59,7 +62,7 @@ If this isn't the case, see below.
-### Potential Problems
+#### Potential Problems
* **MacOS user?** In addition to the above, enable "Remote Login" in "System Preferences > Sharing".