This closes #94
* github/pr/94:
Add notEqual assertion to test entities
diff --git a/_config.yml b/_config.yml
index 810c978..09ef041 100644
--- a/_config.yml
+++ b/_config.yml
@@ -45,13 +45,14 @@
sass:
sass_dir: style/css
-brooklyn-stable-version: 0.8.0-incubating
-brooklyn-base-url: https://brooklyn.apache.org
+# TODO the 0.9.0 paths must be changed!
+brooklyn-stable-version: 0.9.0
+pdf-default-base-url: http://brooklyn.apache.org
+pdf-default-versioned-url-subpath: /v/0.9.0
pdf-rewrite-prefixes:
- '/guide' : '/v/0.9.0-SNAPSHOT'
+ '/guide' : '/v/0.9.0'
'/website' : ''
- '/community' : '/community'
brooklyn-version: 0.10.0-SNAPSHOT # BROOKLYN_VERSION
brooklyn-snapshot-git-branch: master # if line above is SNAPSHOT this should point to corresponding git branch (e.g. master, 0.4)
diff --git a/_includes/fields.md b/_includes/fields.md
index d9e74b7..9d05d8d 100644
--- a/_includes/fields.md
+++ b/_includes/fields.md
@@ -17,15 +17,6 @@
{% capture this_repo_base_url_content %}{% if SNAPSHOT %}{{ apache_snapshots_repo_groupid_url }}{% else %}{{ apache_releases_repo_groupid_url }}{% endif %}{% endcapture %}
{% capture this_dist_url_list %}{{ this_repo_base_url_content }}/brooklyn-dist/{{ site.brooklyn-version }}/{% endcapture %}
-{% if SNAPSHOT %}
- <!-- put e field last, so we can append .sha1 -->
- {% capture this_dist_url_zip %}{{ this_repo_base_url_artifact }}?r=snapshots&g={{ brooklyn_group_id }}&a=brooklyn-dist&v={{ site.brooklyn-version }}&c=dist&e=zip{% endcapture %}
- {% capture this_dist_url_tgz %}{{ this_repo_base_url_artifact }}?r=snapshots&g={{ brooklyn_group_id }}&a=brooklyn-dist&v={{ site.brooklyn-version }}&c=dist&e=tar.gz{% endcapture %}
-{% else %}<!--- RELEASE -->
- {% capture this_dist_url_zip %}{{ this_dist_url_list }}/brooklyn-dist-{{ site.brooklyn-version }}-dist.zip{% endcapture %}
- {% capture this_dist_url_tgz %}{{ this_dist_url_list }}/brooklyn-dist-{{ site.brooklyn-version }}-dist.tar.gz{% endcapture %}
-{% endif %}
-
{% capture this_anything_url_search %}{{ this_repo_base_url_search }};gav~{{ brooklyn_group_id }}~~{{ site.brooklyn-version }}~~{% endcapture %}
{% capture this_dist_url_search %}{{ this_repo_base_url_search }};gav~{{ brooklyn_group_id }}~brooklyn-dist~{{ site.brooklyn-version }}~~{% endcapture %}
diff --git a/_includes/java_link.html b/_includes/java_link.html
index 9411877..4461f37 100644
--- a/_includes/java_link.html
+++ b/_includes/java_link.html
@@ -8,8 +8,8 @@
{% endcomment %}{% if include.project_subpath %}<code>{{ include.class_name }}</code>
- (<a href="{{ site.path.guide }}/misc/javadoc/{{ include.package_path }}/{{ include.class_name }}.html">javadoc</a>,
- <a href="{{ site.brooklyn.url.git }}/{{ include.project_subpath }}/src/main/java/{{ include.package_path }}/{{ include.class_name }}.java">src</a>){% comment %}
+ ({% comment %}<a href="{{ site.path.guide }}/misc/javadoc/{{ include.package_path }}/{{ include.class_name }}.html">javadoc</a>,
+ {% endcomment %}<a href="{{ site.brooklyn.url.git }}/{{ include.project_subpath }}/src/main/java/{{ include.package_path }}/{{ include.class_name }}.java">src</a>){% comment %}
{% endcomment %}{% else %}<a href="{{ site.path.guide }}/misc/javadoc/{{ include.package_path }}/{{ include.class_name }}.html">
<code>{{ include.class_name }}</code></a>
{% endif %}{% comment %}
diff --git a/_plugins/brooklyn_metadata.rb b/_plugins/brooklyn_metadata.rb
index 5c08104..c210c3d 100644
--- a/_plugins/brooklyn_metadata.rb
+++ b/_plugins/brooklyn_metadata.rb
@@ -44,14 +44,16 @@
}
end
- url_set["git"] = "https://github.com/apache/brooklyn/tree/#{ git_branch }"
+ url_set["git"] = "https://github.com/apache/brooklyn-server/tree/#{ git_branch }"
site.config['brooklyn'] = {
"version" => BrooklynMetadata::BROOKLYN_VERSION,
"is_snapshot" => is_snapshot,
"is_release" => !is_snapshot,
"url" => url_set,
- "git_branch" => git_branch
+ "git_branch" => git_branch,
+ "download_prefix" => "https://www.apache.org/dyn/closer.lua?action=download&filename=brooklyn/apache-brooklyn-#{ site.config['brooklyn-stable-version'] }/apache-brooklyn-#{ site.config['brooklyn-stable-version'] }",
+ "hash_download_prefix" => "https://dist.apache.org/repos/dist/release/brooklyn/apache-brooklyn-#{ site.config['brooklyn-stable-version'] }/apache-brooklyn-#{ site.config['brooklyn-stable-version'] }"
}
# config is preferred of data, because you can write just {{ site.brooklyn.xxx }},
diff --git a/_plugins/page_structure.rb b/_plugins/page_structure.rb
index b1697bd..cb81c93 100644
--- a/_plugins/page_structure.rb
+++ b/_plugins/page_structure.rb
@@ -7,6 +7,7 @@
require 'rubygems'
require 'yaml'
require "kramdown"
+require 'pathname'
module PageStructureUtils
@@ -105,7 +106,7 @@
#
def self.parseChildYAMLFromParent(page)
# get the base directory of the current file
- $baseFile = Dir.pwd+page['dir']
+ $baseFile = Dir.pwd+"/"+(Pathname(page['path']).dirname.to_s)
# list all of the files in that directory
$listings = Dir[$baseFile+"/*.md"]
$allPages = []
@@ -143,7 +144,7 @@
#
def self.parseChildPagesFromParent(page)
# get the base directory of the current file
- $baseFile = Dir.pwd+page['dir']
+ $baseFile = Dir.pwd+"/"+(Pathname(page['path']).dirname.to_s)
# list all of the files in that directory
$listings = Dir[$baseFile+"/*"]
# filter by the key pattern
diff --git a/_plugins/regex_filter.rb b/_plugins/regex_filter.rb
index b82169d..5a96223 100644
--- a/_plugins/regex_filter.rb
+++ b/_plugins/regex_filter.rb
@@ -26,7 +26,7 @@
if input == nil
return nil
end
-
+
# generate document id, this will be used for the anchors
$pid = "id-undefined"
if currentPage['title'] != nil
@@ -100,12 +100,12 @@
# make an absolute external URL for the link
if $match.start_with?(prefix[0])
$notFoundPrefix = false
- $newLink = site['brooklyn-base-url']+prefix[1]+$match[prefix[0].length, $match.length]
+ $newLink = site['pdf-default-base-url']+prefix[1]+$match[prefix[0].length, $match.length]
end
end
if $notFoundPrefix
- puts $match+" not found prefix"
- $newLink = site['brooklyn-base-url']+"/v/"+site['brooklyn-version']+$match
+ $newLink = site['pdf-default-base-url']+site['pdf-default-versioned-url-subpath']+$match
+ puts "PDF link to "+$match+" in "+currentPage['path']+" has unknown prefix, routing to "+$newLink
end
end
end
diff --git a/guide/dev/env/maven-build.md b/guide/dev/env/maven-build.md
index cda77e3..e311b8f 100644
--- a/guide/dev/env/maven-build.md
+++ b/guide/dev/env/maven-build.md
@@ -6,35 +6,42 @@
## The Basics
-To build the code, you need Maven (v3.1+) and Java (v1.7+, 1.8 recommended) and Go (v1.6+).
-With that in place, you should be able to build everything with a:
+The full build requires the following software to be installed:
+
+* Maven (v3.1+)
+* Java (v1.7+, 1.8 recommended)
+* Go (v1.6+) [if building the CLI client]
+* rpm tools [if building the dist packages for those platforms]
+
+With these in place, you should be able to build everything with a:
{% highlight bash %}
% mvn clean install
{% endhighlight %}
-Key things to note if you're new to Maven:
+Alternatively you can build most things with just Java and Maven installed using:
+
+{% highlight bash %}
+mvn clean install -Dno-go-client -Dno-rpm`
+{% endhighlight %}
+
+Other tips:
+
+* Add ``-DskipTests`` to skip tests (builds much faster, but not as safe)
* You may need more JVM memory, e.g. at the command-line (or in `.profile`):
``export MAVEN_OPTS="-Xmx1024m -Xms512m -XX:MaxPermSize=256m"``
-* You can do this in specific projects as well.
-
-* Add ``-DskipTests`` to skip tests.
-
-* Add ``-Dno-go-client`` to skip building the ``brooklyn-client`` project (useful if you don't have Go installed).
-
-* You may need to install ``rpm`` package to build RPM packages: ``brew install rpm`` for Mac OS, ``apt-get install rpm`` for Ubuntu, ``yum install rpm`` for Centos/RHEL.
-
* Run ``-PIntegration`` to run integration tests, or ``-PLive`` to run live tests
([tests described here](../code/tests.html))
-* Note that many of the gory details are in ``brooklyn-server/parent/pom.xml``, which is referenced by most other poms.
+* You may need to install ``rpm`` package to build RPM packages: ``brew install rpm`` for Mac OS, ``apt-get install rpm`` for Ubuntu, ``yum install rpm`` for Centos/RHEL.
+ On Mac OS you may also need to set `%_tmppath /tmp` in `~/.rpmmacros`.
-* You can also open and use the code in your favourite IDE,
- although you may hit a few **[snags](ide/)**
- (that link has some tips for resolving them too)
+* If you're looking at the maven internals, note that many of the settings are inherited from parent projects (see for instance `brooklyn-server/parent/pom.xml`)
+
+* For tips on building within various IDEs, look [here](ide/).
## When the RAT Bites
diff --git a/guide/java/entities.md b/guide/java/entities.md
index b83bfc9..1e2623d 100644
--- a/guide/java/entities.md
+++ b/guide/java/entities.md
@@ -113,7 +113,7 @@
to capture the behaviour of the effectors in a simple methods.
For example deploying a WAR to a cluster can be done as follows:
-*This section is not complete. Feel free to [fork]({{site.path.guide}}/dev/code) the docs and lend a hand.*
+*This section is not complete. Feel free to [fork](https://github.com/apache/brooklyn-docs) the docs and lend a hand.*
<!---
TODO show an effector which recurses across children
diff --git a/guide/java/gist_generator/gist_generator.bom b/guide/java/gist_generator/gist_generator.bom
index 5be6b50..89effaf 100644
--- a/guide/java/gist_generator/gist_generator.bom
+++ b/guide/java/gist_generator/gist_generator.bom
@@ -1,10 +1,10 @@
brooklyn.catalog:
id: example.GistGenerator
- version: 1.0
+ version: "1.0"
+ itemType: template
description: For programmatically generating GitHub Gists
displayName: Gist Generator
iconUrl: classpath:///sample-icon.png
- itemType: template
libraries:
- http://search.maven.org/remotecontent?filepath=com/google/code/gson/gson/2.2.2/gson-2.2.2.jar
- http:/.developers.cloudsoftcorp.com/brooklyn/guide/java/gist_generator/org.eclipse.egit.github.core-2.1.5.jar
diff --git a/guide/java/policies.md b/guide/java/policies.md
index 9781d6e..fe3dd6d 100644
--- a/guide/java/policies.md
+++ b/guide/java/policies.md
@@ -31,42 +31,209 @@
### Management Policies
-- AutoScaler Policy
-
- Increases or decreases the size of a Resizable entity based on an aggregate sensor value, the current size of the entity, and customized high/low watermarks.
+#### AutoScaler Policy
- An AutoScaler policy can take any sensor as a metric, have its watermarks tuned live, and target any resizable entity - be it an application server managing how many instances it handles, or a tier managing global capacity.
+- org.apache.brooklyn.policy.autoscaling.AutoScalerPolicy
- e.g. if the average request per second across a cluster of Tomcat servers goes over the high watermark, it will resize the cluster to bring the average back to within the watermarks.
-
-<!---
-TODO - list some
-TODO - describe how they can be customised (briefly mention sensors)
--->
+Increases or decreases the size of a Resizable entity based on an aggregate sensor value, the current size of the entity, and customized high/low watermarks.
+An AutoScaler policy can take any sensor as a metric, have its watermarks tuned live, and target any resizable entity - be it an application server managing how many instances it handles, or a tier managing global capacity.
+
+e.g. if the average request per second across a cluster of Tomcat servers goes over the high watermark, it will resize the cluster to bring the average back to within the watermarks.
+
+{% highlight yaml %}
+brooklyn.policies:
+- type: org.apache.brooklyn.policy.autoscaling.AutoScalerPolicy
+ brooklyn.config:
+ metric: webapp.reqs.perSec.perNode
+ metricUpperBound: 3
+ metricLowerBound: 1
+ resizeUpStabilizationDelay: 2s
+ resizeDownStabilizationDelay: 1m
+ maxPoolSize: 3
+
+{% endhighlight %}
+
+#### ServiceRestarter
+
+- org.apache.brooklyn.policy.ha.ServiceRestarter
+
+Attaches to a SoftwareProcess (or anything Startable, emitting ENTITY_FAILED or other configurable sensor), and invokes restart on failure; if there is a subsequent failure within a configurable time interval, or if the restart fails, this gives up and emits {@link #ENTITY_RESTART_FAILED}
+
+{% highlight yaml %}
+brooklyn.policies:
+- type: org.apache.brooklyn.policy.ha.ServiceRestarter
+ brooklyn.config:
+ failOnRecurringFailuresInThisDuration: 5m
+{% endhighlight %}
+
+#### StopAfterDuration Policy
+
+- org.apache.brooklyn.policy.action.StopAfterDurationPolicy
+
+The StopAfterDurationPolicy can be used to limit the lifetime of an entity. After a configure time period expires the entity will be stopped.
+
+#### CreateUser Policy
+
+- org.apache.brooklyn.policy.jclouds.os.CreateUserPolicy
+
+The CreateUserPolicy Attaches to an Entity and monitors for the addition of a location to that entity, the policy then adds a new user to the VM with a randomly generated password, with the SSH connection details set on the entity as the createuser.vm.user.credentials sensor.
+
+#### AdvertiseWinRMLogin Policy
+
+- org.apache.brooklyn.location.winrm.WinRmMachineLocation
+
+This is similar to the CreateUserPolicy. It will monitor the addition of WinRmMachineLocation to an entity and then create a sensor advertising the administrative user's credentials.
+
+#### SshMachineFailureDetector
+
+- org.apache.brooklyn.policy.ha.SshMachineFailureDetector
+
+The SshMachineFailureDetector is an HA policy for monitoring an SshMachine, emitting an event if the connection is lost/restored.
+
+#### ConnectionFailureDetector
+
+- org.apache.brooklyn.policy.ha.ConnectionFailureDetector
+
+The ConnectionFailureDetector is an HA policy for monitoring an http connection, emitting an event if the connection is lost/restored.
+
+#### ServiceReplacer
+
+- org.apache.brooklyn.policy.ha.ServiceReplacer
+
+The ServiceReplacer attaches to a DynamicCluster and replaces a failed member in response to HASensors.ENTITY_FAILED or other sensor. The [introduction to policies](../) shows a worked example of the ServiceReplacer policy in user.
+
+#### FollowTheSun Policy
+
+- org.apache.brooklyn.policy.followthesun.FollowTheSunPolicy
+
+The FollowTheSunPolicy is for moving work around to follow the demand. The work can be any Movable entity. This currently available in yaml blueprints.
+
+#### ConditionalSuspend Policy
+
+- org.apache.brooklyn.policy.ha.ConditionalSuspendPolicy
+
+The ConditionalSuspendPolicy will suspend and resume a target policy based on configured suspend and resume sensors.
+
+#### LoadBalancing Policy
+
+- org.apache.brooklyn.policy.loadbalancing.LoadBalancingPolicy
+
+The LoadBalancingPolicy is attached to a pool of "containers", each of which can host one or more migratable "items". The policy monitors the workrates of the items and effects migrations in an attempt to ensure that the containers are all sufficiently utilized without any of them being overloaded.
### Enrichers
-* Delta
+#### Transformer
- Converts absolute sensor values into a delta.
+- org.apache.brooklyn.enricher.stock.Transformer
+
+Transforms attributes of an entity.
+
+{% highlight yaml %}
+brooklyn.enrichers:
+- type: org.apache.brooklyn.enricher.stock.Transformer
+ brooklyn.config:
+ enricher.sourceSensor: $brooklyn:sensor("urls.tcp.string")
+ enricher.targetSensor: $brooklyn:sensor("urls.tcp.withBrackets")
+ enricher.targetValue: $brooklyn:formatString("[%s]", $brooklyn:attributeWhenReady("urls.tcp.string"))
+{% endhighlight %}
+
+#### Propagator
+
+- org.apache.brooklyn.enricher.stock.Propagator
+
+Use propagator to duplicate one sensor as another, giving the supplied sensor mapping.
+The other use of Propagator is where you specify a producer (using $brooklyn:entity(...) as below)
+from which to take sensors; in that mode you can specify `propagate` as a list of sensors whose names are unchanged,
+instead of (or in addition to) this map
+
+{% highlight yaml %}
+brooklyn.enrichers:
+- type: org.apache.brooklyn.enricher.stock.Propagator
+ brooklyn.config:
+ producer: $brooklyn:entity("cluster")
+- type: org.apache.brooklyn.enricher.stock.Propagator
+ brooklyn.config:
+ sensorMapping:
+ $brooklyn:sensor("url"): $brooklyn:sensor("org.apache.brooklyn.core.entity.Attributes", "main.uri")
+{% endhighlight %}
+
+#### Custom Aggregating
+
+- org.apache.brooklyn.enricher.stock.Aggregator
+
+Aggregates multiple sensor values (usually across a tier, esp. a cluster) and performs a supplied aggregation method to them to return an aggregate figure, e.g. sum, mean, median, etc.
+
+{% highlight yaml %}
+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
+{% endhighlight %}
+
+#### Joiner
+
+- org.apache.brooklyn.enricher.stock.Joiner
+
+Joins a sensor whose output is a list into a single item joined by a separator.
+
+{% highlight yaml %}
+brooklyn.enrichers:
+- type: org.apache.brooklyn.enricher.stock.Joiner
+ brooklyn.config:
+ enricher.sourceSensor: $brooklyn:sensor("urls.tcp.list")
+ enricher.targetSensor: $brooklyn:sensor("urls.tcp.string")
+ uniqueTag: urls.quoted.string
+{% endhighlight %}
+
+#### Delta Enricher
+
+- org.apache.brooklyn.policy.enricher.Delta Enricher
+
+Converts absolute sensor values into a delta.
+
+#### Time-weighted Delta
+
+- org.apache.brooklyn.enricher.stock.YamlTimeWeightedDeltaEnricher
+
+Converts absolute sensor values into a delta/second.
+{% highlight yaml %}
+brooklyn.enrichers:
+- type: org.apache.brooklyn.enricher.stock.YamlTimeWeightedDeltaEnricher
+ brooklyn.config:
+ enricher.sourceSensor: reqs.count
+ enricher.targetSensor: reqs.per_sec
+ enricher.delta.period: 1s
+{% endhighlight %}
-* Time-weighted Delta
+#### Rolling Mean
- Converts absolute sensor values into a delta/second.
+- org.apache.brooklyn.policy.enricher.RollingMeanEnricher
+
+Converts the last *N* sensor values into a mean.
-* Rolling Mean
+#### Rolling Time-window Mean
- Converts the last *N* sensor values into a mean.
-
-* Rolling Time-window Mean
+- org.apache.brooklyn.policy.enricher.RollingTimeWindowMeanEnricher
- Converts the last *N* seconds of sensor values into a weighted mean.
+Converts the last *N* seconds of sensor values into a weighted mean.
-* Custom Aggregating
+#### Http Latency Detector
- Aggregates multiple sensor values (usually across a tier, esp. a cluster) and performs a supplied aggregation method to them to return an aggregate figure, e.g. sum, mean, median, etc.
+- org.apache.brooklyn.policy.enricher.RollingTimeWindowMeanEnricher.HttpLatencyDetector
+
+An Enricher which computes latency in accessing a URL.
+
+#### Combiner
+
+- org.apache.brooklyn.enricher.stock.Combiner
+
+Can be used to combine the values of sensors. This enricher should be instantiated using Enrichers.buider.combining(..).
+This enricher is only available in Java blueprints and cannot be used in YAML.
Next: Writing a Policy
diff --git a/guide/misc/download.md b/guide/misc/download.md
index d154802..8417aa6 100644
--- a/guide/misc/download.md
+++ b/guide/misc/download.md
@@ -19,56 +19,78 @@
<th>checksums <small><a href="{{ site.path.website }}/download/verify.html" title='Instructions on verifying the integrity of your downloads.{% if site.brooklyn.is_snapshot %} May not be available for SNAPSHOT artifacts.{% endif %}'>(?)</a></small></th>
</tr>
<tr>
- <td style='text-align:left;vertical-align:top' rowspan='2'>Distro</td>
- <td style='text-align:left'><a href='{{ this_dist_url_zip }}' title='Download ZIP archive'>brooklyn-dist-{{ site.brooklyn-version }}-dist.zip</a></td>
- <td><small>
- {% if site.brooklyn.is_release %}<a href='{{ this_dist_url_zip }}.asc'>PGP</a>, {% endif %}
- <a href='{{ this_dist_url_zip }}.sha1'>SHA1</a></small></td>
- </tr>
- <tr>
- <td style='text-align:left'><a href='{{ this_dist_url_tgz }}' title='Download TGZ archive'>brooklyn-dist-{{ site.brooklyn-version }}-dist.tar.gz</a></td>
+ <td style='text-align:left;vertical-align:top' rowspan='2'>Binary distribution<br />Server & client</td>
+ <td style='text-align:left'><a href='{{ site.brooklyn.download_prefix }}-bin.tar.gz' title='Download TGZ archive'>apache-brooklyn-{{ site.brooklyn-version }}-bin.tar.gz</a></td>
<td ><small>
- {% if site.brooklyn.is_release %}<a href='{{ this_dist_url_tgz }}.asc'>PGP</a>, {% endif %}
- <a href='{{ this_dist_url_tgz }}.sha1'>SHA1</a></small></td>
+ {% if site.brooklyn.is_release %}<a href='{{ site.brooklyn.hash_download_prefix }}-bin.tar.gz.asc'>PGP</a>, {% endif %}
+ <a href='{{ site.hash_brooklyn.download_prefix }}-bin.tar.gz.sha1'>SHA1</a></small></td>
</tr>
<tr>
- <td style='text-align:left'>Apache Repo</td>
- <td style='text-align:left'>
- <a href='{{ this_anything_url_search }}' title='Search'><i>GUI</i></a>
- —
- <a href='{{ this_dist_url_list }}' title='List'><i>dir</i></a>
- </td>
- <td> — </td>
+ <td style='text-align:left'><a href='{{ site.brooklyn.download_prefix }}-bin.zip' title='Download ZIP archive'>apache-brooklyn-{{ site.brooklyn-version }}-bin.zip</a></td>
+ <td><small>
+ {% if site.brooklyn.is_release %}<a href='{{ site.brooklyn.hash_download_prefix }}-bin.zip.asc'>PGP</a>, {% endif %}
+ <a href='{{ site.brooklyn.hash_download_prefix }}-bin.zip.sha1'>SHA1</a></small></td>
</tr>
<tr>
- <td style='text-align:left'>Release Notes</td>
- <td style='text-align:left'><a href='{{ site.path.guide }}/misc/release-notes.html'>{{ site.brooklyn-version }}</a></td>
- <td> — </td>
+ <td style='text-align:left;vertical-align:top'>RPM package<br />CentOS7, RHEL7, etc.</td>
+ <td style='text-align:left'><a href='{{ site.brooklyn.download_prefix }}-1.noarch.rpm' title='Download ZIP archive'>apache-brooklyn-{{ site.brooklyn-version }}-1.noarch.rpm</a></td>
+ <td><small>
+ {% if site.brooklyn.is_release %}<a href='{{ site.brooklyn.hash_download_prefix }}-1.noarch.rpm.asc'>PGP</a>, {% endif %}
+ <a href='{{ site.brooklyn.hash_download_prefix }}-1.noarch.rpm.sha1'>SHA1</a></small></td>
+ </tr>
+ <tr>
+ <td style='text-align:left;vertical-align:top' rowspan='6'>Client CLI only</td>
+ <td style='text-align:left'><a href='{{ site.brooklyn.download_prefix }}-client-cli-linux.tar.gz' title='Download TGZ archive'>apache-brooklyn-{{ site.brooklyn-version }}-client-cli-linux.tar.gz</a></td>
+ <td ><small>
+ {% if site.brooklyn.is_release %}<a href='{{ site.brooklyn.hash_download_prefix }}-client-cli-linux.tar.gz.asc'>PGP</a>, {% endif %}
+ <a href='{{ site.hash_brooklyn.download_prefix }}-client-cli-linux.tar.gz.sha1'>SHA1</a></small></td>
+ </tr>
+ <tr>
+ <td style='text-align:left'><a href='{{ site.brooklyn.download_prefix }}-client-cli-linux.zip' title='Download ZIP archive'>apache-brooklyn-{{ site.brooklyn-version }}-client-cli-linux.zip</a></td>
+ <td><small>
+ {% if site.brooklyn.is_release %}<a href='{{ site.brooklyn.hash_download_prefix }}-client-cli-linux.zip.asc'>PGP</a>, {% endif %}
+ <a href='{{ site.brooklyn.hash_download_prefix }}-client-cli-linux.zip.sha1'>SHA1</a></small></td>
+ </tr>
+ <tr>
+ <td style='text-align:left'><a href='{{ site.brooklyn.download_prefix }}-client-cli-macosx.tar.gz' title='Download TGZ archive'>apache-brooklyn-{{ site.brooklyn-version }}-client-cli-macosx.tar.gz</a></td>
+ <td ><small>
+ {% if site.brooklyn.is_release %}<a href='{{ site.brooklyn.hash_download_prefix }}-client-cli-macosx.tar.gz.asc'>PGP</a>, {% endif %}
+ <a href='{{ site.hash_brooklyn.download_prefix }}-client-cli-macosx.tar.gz.sha1'>SHA1</a></small></td>
+ </tr>
+ <tr>
+ <td style='text-align:left'><a href='{{ site.brooklyn.download_prefix }}-client-cli-macosx.zip' title='Download ZIP archive'>apache-brooklyn-{{ site.brooklyn-version }}-client-cli-macosx.zip</a></td>
+ <td><small>
+ {% if site.brooklyn.is_release %}<a href='{{ site.brooklyn.hash_download_prefix }}-client-cli-macosx.zip.asc'>PGP</a>, {% endif %}
+ <a href='{{ site.brooklyn.hash_download_prefix }}-client-cli-macosx.zip.sha1'>SHA1</a></small></td>
+ </tr>
+ <tr>
+ <td style='text-align:left'><a href='{{ site.brooklyn.download_prefix }}-client-cli-windows.tar.gz' title='Download TGZ archive'>apache-brooklyn-{{ site.brooklyn-version }}-client-cli-windows.tar.gz</a></td>
+ <td ><small>
+ {% if site.brooklyn.is_release %}<a href='{{ site.brooklyn.hash_download_prefix }}-client-cli-windows.tar.gz.asc'>PGP</a>, {% endif %}
+ <a href='{{ site.hash_brooklyn.download_prefix }}-client-cli-windows.tar.gz.sha1'>SHA1</a></small></td>
+ </tr>
+ <tr>
+ <td style='text-align:left'><a href='{{ site.brooklyn.download_prefix }}-client-cli-windows.zip' title='Download ZIP archive'>apache-brooklyn-{{ site.brooklyn-version }}-client-cli-windows.zip</a></td>
+ <td><small>
+ {% if site.brooklyn.is_release %}<a href='{{ site.brooklyn.hash_download_prefix }}-client-cli-windows.zip.asc'>PGP</a>, {% endif %}
+ <a href='{{ site.brooklyn.hash_download_prefix }}-client-cli-windows.zip.sha1'>SHA1</a></small></td>
+ </tr>
+ <tr>
+ <td style='text-align:left;vertical-align:top' rowspan='2'>Source code</td>
+ <td style='text-align:left'><a href='{{ site.brooklyn.download_prefix }}-src.tar.gz' title='Download TGZ archive'>apache-brooklyn-{{ site.brooklyn-version }}-src.tar.gz</a></td>
+ <td ><small>
+ {% if site.brooklyn.is_release %}<a href='{{ site.brooklyn.hash_download_prefix }}-src.tar.gz.asc'>PGP</a>, {% endif %}
+ <a href='{{ site.hash_brooklyn.download_prefix }}-src.tar.gz.sha1'>SHA1</a></small></td>
+ </tr>
+ <tr>
+ <td style='text-align:left'><a href='{{ site.brooklyn.download_prefix }}-src.zip' title='Download ZIP archive'>apache-brooklyn-{{ site.brooklyn-version }}-src.zip</a></td>
+ <td><small>
+ {% if site.brooklyn.is_release %}<a href='{{ site.brooklyn.hash_download_prefix }}-src.zip.asc'>PGP</a>, {% endif %}
+ <a href='{{ site.brooklyn.hash_download_prefix }}-src.zip.sha1'>SHA1</a></small></td>
</tr>
</table>
-<a name="distro"></a>
-
-## The Dist
-
-The binary distribution archive contains Brooklyn as a standalone executable package.
-
-* [This version ZIP]({{ this_dist_url_zip }})
-* [This version TGZ]({{ this_dist_url_tgz }})
-* [Apache stable versions]({{ apache_releases_repo_groupid_url }}/brooklyn-dist/)
-* [Apache snapshot versions]({{ apache_snapshots_repo_groupid_url }}/brooklyn-dist/)
-
-Released versions are also available at
-[Maven Central](https://search.maven.org/#search%7Cga%7C1%7Corg.apache.brooklyn).
-
-{% if site.brooklyn-version contains 'SNAPSHOT' %}
-**Please note**: You are reading the documentation for a snapshot version of Brooklyn.
-You should always confirm that the source repository and datestamp for downloaded snapshot artifacts
-match the intended dependencies, as snapshot artifacts change as code is written.
-{% endif %}
-
-
## Release Notes
Release notes can be found [here]({{ site.path.guide }}/misc/release-notes.html).
@@ -110,8 +132,7 @@
and some of ``brooklyn-software-webapp``, ``brooklyn-software-database``, ``brooklyn-software-messaging``, or others
(browse the full list [here]({{ this_anything_url_search }})).
-If you wish to use the Apache snapshot repo and/or Cloudsoft repositories,
-you can add some of the following sections:
+If you wish to use the Apache snapshot repo, you can add this to you `pom.xml`:
{% highlight xml %}
<!-- include repos for snapshot items and other dependencies -->
@@ -123,19 +144,6 @@
<releases> <enabled>false</enabled> </releases>
<snapshots> <enabled>true</enabled> </snapshots>
</repository>
- <repository>
- <id>cloudsoft-cloudfront-releases-repo</id>
- <url>http://developers.cloudsoftcorp.com/maven/releases/</url>
- </repository>
- <repository>
- <id>cloudsoft-cloudfront-snapshots-repo</id>
- <url>http://developers.cloudsoftcorp.com/maven/snapshots/</url>
- <snapshots>
- <enabled>true</enabled>
- <updatePolicy>never</updatePolicy>
- <checksumPolicy>fail</checksumPolicy>
- </snapshots>
- </repository>
</repositories>
{% endhighlight %}
diff --git a/guide/misc/javadoc/index.md b/guide/misc/javadoc/index.md
index 5cf9ebc..6841283 100644
--- a/guide/misc/javadoc/index.md
+++ b/guide/misc/javadoc/index.md
@@ -6,6 +6,6 @@
*Javadoc is not available as part of this build.*
-Please see the [source code]({{site.path.guide}}/dev/code) to view javadoc.
+Please see the [source code](https://github.com/apache/brooklyn) to view javadoc.
<!-- This page is normally overwritten by generated javadoc. -->
diff --git a/guide/misc/osgi.md b/guide/misc/osgi.md
index 2af842e..dd9ba77 100644
--- a/guide/misc/osgi.md
+++ b/guide/misc/osgi.md
@@ -88,6 +88,7 @@
version: ...
items:
- id: org.apache.brooklyn.entity.webapp.nodejs.NodeJsWebAppService
+ itemType: entity
item:
type: org.apache.brooklyn.entity.webapp.nodejs.NodeJsWebAppService
name: Node.JS Application
diff --git a/guide/misc/release-notes.md b/guide/misc/release-notes.md
index 7cd9413..2fb7d36 100644
--- a/guide/misc/release-notes.md
+++ b/guide/misc/release-notes.md
@@ -9,85 +9,17 @@
**You are viewing a SNAPSHOT release (master branch), so this list is in progress!**
{% endif %}
-* Introduction
-* New Features
-* Backwards Compatibility
-
-
-### Introduction
-
-Version 0.9.0 is [TODO add description]
-
Thanks go to our community for their improvements, feedback and guidance, and
to Brooklyn's commercial users for funding much of this development.
-
### New Features
-1. Parameters (config keys) can now be defined in YAML, using `brooklyn.parameters`.
-This allows YAML entities to advertise how they should be parameterized,
-for use in the UI and in documentation tools, and do coercion on these values.
-For a good demonstration, see the "Custom Entities" section of the YAML chapter of the user guide.
-
-[ TODO -
-restructuring and graduation;
-the `br` client CLI tool;
-better YAML editor in the UI;
-a location wizard for defining new clouds;
-test framework;
-`$brooklyn:external(...)` extension for taking values from other sources is supported in more places;
-OSGi-native mode using Karaf, to simplify packaging of blueprints;
-a new pure-java WinRM client (winrm4j), hugely reducing the number of dependencies and distro size;
-several version bumps (jclouds) and performance and reliability improvements
-]
-
### Backwards Compatibility
-Changes since 0.8.0-incubating:
+Changes since 0.9.0:
-1. **Major:** The classes HttpTool and HttpToolResponse in brooklyn-core (package org.apache.brooklyn.util.core.http)
-have been moved to brooklyn-utils-common, in package org.apache.brooklyn.util.
-Classes such as HttpFeed that previously returned org.apache.brooklyn.util.core.http.HttpToolResponse in some methods now
-return org.apache.brooklyn.util.HttpToolResponse.
-
-2. **Major:** Locations set in YAML or on a spec are no longer passed to `child.start(...)` by `AbstractApplication`;
-this has no effect in most cases as `SoftwareProcess.start` looks at local and inherited locations, but in ambiguous cases
-it means that locally defined locations are now preferred. Other classes of entities may need to do similar behaviour,
-and it means that calls to `Entity.getLocations()` in some cases will not show parent locations,
-unless discovered and set locally e.g. `start()`. The new method `Entities.getAllInheritedLocations(Entity)`
-can be used to traverse the hierarchy. It also means that when a type in the registry (catalog) includes a location,
-and a caller references it, that location will now take priority over a location defined in a parent.
-Additionally, any locations specified in YAML extending the registered type will now *replace* locations on the referenced type;
-this means in many cases an explicit `locations: []` when extending a type will cause locations to be taken from the
-parent or application root in YAML. Related to this, tags from referencing specs now preceed tags in the referenced types,
-and the referencing catalog item ID also takes priority; this has no effect in most cases, but if you have a chain of
-referenced types blueprint plan source code and the catalog item ID are now set correctly.
-
-3. Task cancellation is now propagated to dependent submitted tasks, including backgrounded tasks if they are transient.
-Previously when a task was cancelled the API did not guarantee semantics but the behaviour was to cancel sub-tasks only
-in very limited cases. Now the semantics are more precise and controllable, and more sub-tasks are cancelled.
-This can prevent some leaked waits on `attributeWhenReady`.
-
-4. The name of the sensor `VanillaWindowsProcess.WINRM_PORT` has been changed from `winrmPort` to `winrm.port`.
-<br>
-During the development some wrong named sensors appeared for WINRM_PORT. They are still there for backwards compatibility but they are deprecated.
-<br>
-If you are referencing this sensor in blueprint DSL or somewhere else please use the key `winrm.port`.
-
-5. The name of the sensor `VanillaWindowsProcess.RDP_PORT` has been changed from `rdpPort` to `rdp.port`.
-<br>
-If you are referencing this sensor in blueprint DSL or somewhere else please use the key `rdp.port`.
-
-6. Location resolvers now generate `LocationSpec` instances instead of `Location` instances.
-This makes it clearer when locations become managed and prevents a memory leak which can
-happen when some locations are never unmanaged. All implementations of `LocationResolver`
-need to be updated to conform to the new interface.
-
-7. The named location `localhost` is no longer automatically added by default on a fresh Brooklyn install.
-Instead UI users are directed to a location wizard where they can configure their targets, including localhost.
-If you require `localhost` to be available on boot, define it as a named location in `brooklyn.properties`
-or the default catalog. (The property `brooklyn.location.name.localhost=localhost` is usually sufficient.)
+1. [minor] `ClassCoercionException` has moved package. The old one was deleted to prevent errors inadvertently trying to catch it.
For changes in prior versions, please refer to the release notes for
-[0.8.0](/v/0.8.0-incubating/misc/release-notes.html).
+[0.9.0]({{ site.path.v }}/0.9.0/misc/release-notes.html).
diff --git a/guide/ops/brooklyn_properties.md b/guide/ops/brooklyn_properties.md
index 2805297..8d51323 100644
--- a/guide/ops/brooklyn_properties.md
+++ b/guide/ops/brooklyn_properties.md
@@ -15,7 +15,7 @@
The file `~/.brooklyn/brooklyn.properties` is read when Brooklyn starts
to load server configuration values.
A different properties file can be specified either additionally or instead
-through [CLI options](launch.html#configuration-files).
+through [CLI options](server-cli-reference.html).
A template [brooklyn.properties]({{brooklyn_properties_url_path}}) file is available,
with abundant comments.
diff --git a/guide/ops/catalog/index.md b/guide/ops/catalog/index.md
index 230eedc..80e1b2c 100644
--- a/guide/ops/catalog/index.md
+++ b/guide/ops/catalog/index.md
@@ -12,10 +12,11 @@
---
-Apache Brooklyn provides a **catalog**, which is a persisted collection of versioned blueprints and other resources.
-A set of blueprints is loaded from the `default.catalog.bom` in the Brooklyn folder by default and additional ones can be added through the web console or CLI.
-Blueprints in the catalog can be deployed directly, via the Brooklyn CLI or the web console,
-or referenced in other blueprints using their `id`.
+Apache Brooklyn provides a **catalog**, which is a persisted collection of versioned blueprints
+and other resources. A set of blueprints is loaded from the `default.catalog.bom` in the Brooklyn
+folder by default and additional ones can be added through the web console or CLI. Blueprints in
+the catalog can be deployed directly, via the Brooklyn CLI or the web console, or referenced in
+other blueprints using their `id`.
### Catalog Items YAML Syntax
@@ -25,20 +26,8 @@
#### General YAML Schema
-
-A single catalog item can be defined following this general structure:
-~~~ yaml
-brooklyn.catalog:
- <catalog-metadata>
- item:
- <blueprint-or-resource-definition>
-~~~
-
-
-To define multiple catalog items in a single YAML,
-where they may share some metadata,
-use the following structure:
+Catalog items can be defined using the general structure below:
~~~ yaml
brooklyn.catalog:
@@ -51,14 +40,42 @@
item:
<blueprint-or-resource-definition>
~~~
+
+Alternatively, a single catalog item can be defined using the following general structure:
+
+~~~ yaml
+brooklyn.catalog:
+ <catalog-metadata>
+ item:
+ <blueprint-or-resource-definition>
+~~~
+
+For example, the YAML below adds to the catalog a Tomcat entity with some additional default
+configuration:
+
+~~~ yaml
+brooklyn.catalog:
+ items:
+ - id: tomcat-server
+ version: "1.0.0"
+ itemType: entity
+ item:
+ type: org.apache.brooklyn.entity.webapp.tomcat.Tomcat8Server
+ brooklyn.config:
+ webapp.enabledProtocols: https
+ httpsSsl:
+ url: classpath://org/apache/brooklyn/entity/webapp/sample-java-keystore.jks
+ alias: myname
+ password: mypass
+~~~
#### Catalog Metadata
-Catalog metadata fields supply the additional information required In order to register an item in the catalog.
+Catalog metadata fields supply the additional information required in order to register an item in the catalog.
These fields can be supplied as `key: value` entries
where either the `<catalog-metadata>` or `<additional-catalog-metadata>` placeholders are,
-with the latter overriding the former unless otherwise specfied below.
+with the latter overriding the former unless otherwise specified below.
The following metadata is *required* for all items:
@@ -67,7 +84,13 @@
this field disambiguates between blueprints of the same `id`.
Note that this is typically *not* the version of the software being installed,
but rather the version of the blueprint. For more information on versioning, see below.
- (Also note YAML treats numbers differently to Strings. Explicit quotes may sometimes be required.)
+ (Also note YAML treats numbers differently to Strings. Explicit quotes are recommended, to avoid
+ `1.10` being interpretted as the number `1.1`.)
+- `itemType`: the type of the item being defined. The supported item types are:
+ - `entity`
+ - `template`
+ - `policy`
+ - `location`
To reference a catalog item in another blueprint, simply reference its ID and optionally its version number.
For instance, if we've added an item with metadata `{ id: datastore, version: "1.0" }` (such as the example below),
@@ -80,36 +103,48 @@
In addition to the above fields, exactly **one** of the following is also required:
-- `item`: the YAML for a service or policy or location specification
- (a map containing `type` and optional `brooklyn.config`)
- or a full application blueprint (in the usual YAML format) for a template; **or*
+- `item`: the YAML for an entity, or policy, or location specification
+ (a map containing `type` and optional `brooklyn.config`). For a "template" item, it
+ should be a map containing `services` (i.e. the usual YAML format for a full application
+ blueprint). **Or**
- `items`: a list of catalog items, where each entry in the map follows the same schema as
the `brooklyn.catalog` value, and the keys in these map override any metadata specified as
a sibling of this `items` key (or, in the case of `brooklyn.libraries` they add to the list);
- if there are references between items, then order is important,
- `items` are processed in order, depth-first, and forward references are not supported.
+ if there are references between items, then order is important:
+ `items` are processed in order, depth-first, and forward references are not supported. Entries
+ can be URL to another catalog file to include, inheriting the metadata from the current hierarchy.
+ Libraries defined so far in the metadata will be used to load classpath entries. For example:
+
+~~~ yaml
+brooklyn.catalog:
+ brooklyn.libraries:
+ - http://some.server.or.other/path/my.jar
+ items:
+ - classpath://my-catalog-entries-inside-jar.bom
+ - some-property: value
+ include: classpath://more-catalog-entries-inside-jar.bom
+ - id: use-from-my-catalog
+ version: "1.0.0"
+ itemType: entity
+ item:
+ type: some-type-defined-in-my-catalog-entries
+ brooklyn.config:
+ some.config: "some value"
+~~~
The following optional catalog metadata is supported:
-- `itemType`: the type of the item being defined.
- When adding a template (see below) this must be set.
- In most other cases this can be omitted and type type will be inferred.
- The supported item types are:
- - `entity`
- - `template`
- - `policy`
- - `location`
-- `name`: a nicely formatted display name for the item, used when presenting it in a GUI
-- `description`: supplies an extended textual description for the item
+- `name`: a nicely formatted display name for the item, used when presenting it in a GUI.
+- `description`: supplies an extended textual description for the item.
- `iconUrl`: points to an icon for the item, used when presenting it in a GUI.
- The URL prefix `classpath` is supported but these URLs may *not* refer items in any OSGi bundle in the `brooklyn.libraries` section
- (to prevent requiring all OSGi bundles to be loaded at launch).
- Icons are instead typically installed either at the server from which the OSGi bundles or catalog items are supplied
- or in the `conf` folder of the Brooklyn distro.
-- `scanJavaAnnotations` [experimental]: if provided (as `true`), this will scan any locally provided
- library URLs for types annotated `@Catalog` and extract metadata to include them as catalog items.
- If no libraries are specified this will scan the default classpath.
- This feature is experimental and may change or be removed.
+ The URL prefix `classpath` is supported but these URLs may *not* refer to resources in any OSGi
+ bundle in the `brooklyn.libraries` section (to prevent requiring all OSGi bundles to be loaded
+ at launch). Icons are instead typically installed either at the web server from which the OSGi
+ bundles or catalog items are supplied or in the `conf` folder of the Brooklyn distro.
+- `scanJavaAnnotations` [experimental; deprecated]: if provided (as `true`), this will scan any
+ locally provided library URLs for types annotated `@Catalog` and extract metadata to include
+ them as catalog items. If no libraries are specified this will scan the default classpath.
+ This feature will likely be removed.
Also note that external OSGi dependencies are not supported
and other metadata (such as versions, etc) may not be applied.
- `brooklyn.libraries`: a list of pointers to OSGi bundles required for the catalog item.
@@ -119,13 +154,17 @@
Libraries should be supplied in the form
`brooklyn.libraries: [ "http://...", "http://..." ]`,
or as
- `brooklyn.libraries: [ { name: symbolic-name, version: 1.0, url: http://... }, ... ]` if `symbolic-name:1.0`
+ `brooklyn.libraries: [ { name: symbolic-name, version: "1.0", url: http://... }, ... ]` if `symbolic-name:1.0`
might already be installed from a different URL and you want to skip the download.
Note that these URLs should point at immutable OSGi bundles;
if the contents at any of these URLs changes, the behaviour of the blueprint may change
whenever a bundle is reloaded in a Brooklyn server,
and if entities have been deployed against that version, their behavior may change in subtle or potentially incompatible ways.
To avoid this situation, it is highly recommended to use OSGi version stamps as part of the URL.
+- `include`: A URL to another catalog file to include, inheriting the meta from the current hierarchy.
+ Libraries defined so far in the meta will be used to load classpath entries. `include` must be used
+ when you have sibling properties. If it's the only property it may be skipped by having the URL as the
+ value - see `items` example above.
#### Catalog YAML Examples
@@ -140,14 +179,15 @@
~~~ yaml
brooklyn.catalog:
id: datastore
- version: 1.0
+ version: "1.0"
itemType: template
iconUrl: classpath://org/apache/brooklyn/entity/nosql/riak/riak.png
name: Datastore (Riak)
description: Riak is an open-source NoSQL key-value data store.
item:
- type: org.apache.brooklyn.entity.nosql.riak.RiakNode
- name: Riak Node
+ services:
+ - type: org.apache.brooklyn.entity.nosql.riak.RiakNode
+ name: Riak Node
~~~
@@ -157,15 +197,17 @@
~~~ yaml
brooklyn.catalog:
- version: 1.1
+ version: "1.1"
iconUrl: classpath://org/apache/brooklyn/entity/nosql/riak/riak.png
description: Riak is an open-source NoSQL key-value data store.
items:
- id: riak-node
+ itemType: entity
item:
type: org.apache.brooklyn.entity.nosql.riak.RiakNode
name: Riak Node
- id: riak-cluster
+ itemType: entity
item:
type: org.apache.brooklyn.entity.nosql.riak.RiakCluster
name: Riak Cluster
@@ -175,12 +217,6 @@
item:
services:
- type: riak-cluster
- location:
- jclouds:softlayer:
- region: sjc01
- # identity and credential must be set unless they are specified in your brooklyn.properties
- # identity: XXX
- # credential: XXX
brooklyn.config:
# the default size is 3 but this can be changed to suit your requirements
initial.size: 3
@@ -189,7 +225,7 @@
minRam: 8gb
~~~
-The items this will install are:
+The items this will add to the catalog are:
- `riak-node`, as before, but with a different name
- `riak-cluster` as a convenience short name for the `org.apache.brooklyn.entity.nosql.riak.RiakCluster` class
@@ -208,7 +244,7 @@
~~~ yaml
brooklyn.catalog:
id: vagrant
- version: 1.0
+ version: "1.0"
itemType: location
name: Vagrant getting started location
item:
@@ -232,7 +268,7 @@
#### Legacy Syntax
-The following legacy and experimental syntax is also supported:
+The following legacy and experimental syntax is also supported, but deprecated:
~~~ yaml
<blueprint-definition>
@@ -255,6 +291,8 @@
### Templates and the Add-Application Wizard
+A `template` is a full application. It consists of one or more entities inside an application
+(though this is also composable: it can be used as part of another application).
When a `template` is added to the catalog, the blueprint will appear in the 'Create Application' dialog
as shown here:
@@ -278,7 +316,13 @@
To do this using `curl`:
~~~ bash
-curl http://127.0.0.1:8081/v1/catalog --data-binary @/path/to/riak.catalog.bom
+curl -u admin:password http://127.0.0.1:8081/v1/catalog --data-binary @/path/to/riak.catalog.bom
+~~~
+
+Or using the CLI:
+
+~~~ bash
+br add-catalog /path/to/riak.catalog.bom
~~~
@@ -291,9 +335,10 @@
For example, to delete the item with id `datastore` and version `1.0` with `curl`:
~~~ bash
-curl -X DELETE http://127.0.0.1:8081/v1/catalog/applications/datastore/1.0
+curl -u admin:password -X DELETE http://127.0.0.1:8081/v1/catalog/applications/datastore/1.0
~~~
+
**Note:** Catalog items should not be deleted if there are running apps which were created using the same item.
During rebinding the catalog item is used to reconstruct the entity.
@@ -306,7 +351,7 @@
id including the version number is passed to the REST API as follows:
~~~ bash
-curl -X POST http://127.0.0.1:8081/v1/catalog/entities/MySQL:1.0/deprecated/true
+curl -u admin:password -X POST http://127.0.0.1:8081/v1/catalog/entities/MySQL:1.0/deprecated/true
~~~
@@ -327,9 +372,9 @@
the latest non-snapshot version will be loaded when an entity is instantiated.
-### CLI Options
+### Brooklyn Server Command Line Arguments
-The `brooklyn` CLI includes several commands for working with the catalog.
+The command line arguments when launching `brooklyn` include several commands for working with the catalog.
* `--catalogAdd <file.bom>` will add the catalog items in the `bom` file
* `--catalogReset` will reset the catalog to the initial state
diff --git a/guide/ops/cli/index.md b/guide/ops/cli/index.md
index 15ea905..1c79ce9 100644
--- a/guide/ops/cli/index.md
+++ b/guide/ops/cli/index.md
@@ -12,8 +12,17 @@
## Obtaining the CLI tool
-The CLI tool, `br`, is included in the Apache Brooklyn distribution, under `bin/brooklyn-client-cli/`.
-The tool is an executable binary available for many platforms, with each build in its own subdirectory:
+A selection of distributions of the CLI tool, `br`, are available to download from the download site {% if site.brooklyn-version contains 'SNAPSHOT' %}
+[here](https://repository.apache.org/service/local/artifact/maven/redirect?r=snapshots&g=org.apache.brooklyn&a=brooklyn-client-cli&v={{site.brooklyn-version}}&c=bin&e=zip).
+{% else %} here:
+
+* [Windows](https://www.apache.org/dyn/closer.lua/brooklyn/apache-brooklyn-{{site.brooklyn-version}}-client-cli-windows.zip)
+* [Linux](https://www.apache.org/dyn/closer.lua/brooklyn/apache-brooklyn-{{site.brooklyn-version}}-client-cli-linux.tar.gz)
+* [OSX](https://www.apache.org/dyn/closer.lua/brooklyn/apache-brooklyn-{{site.brooklyn-version}}-client-cli-macosx.tar.gz)
+{% endif %}
+
+Alternatively the CLI tool is available as an executable binary for many more platforms in the Apache Brooklyn
+ distribution, under `bin/brooklyn-client-cli/`, with each build in its own subdirectory:
* Mac: `darwin.amd64/`
* Windows 32-bit: `windows.386/`
diff --git a/guide/ops/externalized-configuration.md b/guide/ops/externalized-configuration.md
index b0c85cd..f891b82 100644
--- a/guide/ops/externalized-configuration.md
+++ b/guide/ops/externalized-configuration.md
@@ -128,7 +128,8 @@
brooklyn.catalog:
id: com.example.myblueprint
- version: 1.2.3
+ version: "1.2.3"
+ itemType: entity
brooklyn.libraries:
- >
$brooklyn:formatString("https://%s:%s@repo.example.com/libs/myblueprint-1.2.3.jar",
diff --git a/guide/ops/gui/running.md b/guide/ops/gui/running.md
index ef8edca..f73ffb2 100644
--- a/guide/ops/gui/running.md
+++ b/guide/ops/gui/running.md
@@ -38,6 +38,9 @@
INFO Started Brooklyn console at http://127.0.0.1:8081/, running classpath://brooklyn.war
</pre>
+_Notice! Before launching Apache Brooklyn, please check the `date` on the local machine.
+Even several minutes before or after the actual time could cause problems._
+
## Connect with Browser
Next, open the web console on [http://127.0.0.1:8081](http://127.0.0.1:8081).
diff --git a/guide/ops/high-availability/high-availability-supplemental.md b/guide/ops/high-availability/high-availability-supplemental.md
new file mode 100644
index 0000000..7b663fb
--- /dev/null
+++ b/guide/ops/high-availability/high-availability-supplemental.md
@@ -0,0 +1,155 @@
+---
+title: High Availability (Supplemental)
+layout: website-normal
+---
+
+This document supplements the [High Availability]({{ site.path.guide }}/ops/high-availability/) documentation
+and provides an example of how to configure a pair of Apache Brooklyn servers to run in master-standby mode with a shared NFS datastore
+
+### Prerequisites
+- Two VMs (or physical machines) have been provisioned
+- NFS or another suitable file system has been configured and is available to both VMs*
+- An NFS folder has been mounted on both VMs at `/mnt/brooklyn-persistence` and both machines can write to the folder
+
+\* Brooklyn can be configured to use either an object store such as S3, or a shared NFS mount. The recommended option is to use an object
+store as described in the [Object Store Persistence]({{ site.path.guide }}/ops/persistence/#object-store-persistence) documentation. For simplicity, a shared NFS folder
+is assumed in this example
+
+### Launching
+To start, download and install the latest Apache Brooklyn release on both VMs following the instructions in
+[Running Apache Brooklyn]({{ site.path.guide }}/start/running.html#install-apache-brooklyn)
+
+On the first VM, which will be the master node, run the following to start Brooklyn in high availability mode:
+
+{% highlight bash %}
+$ bin/brooklyn launch --highAvailability master --https --persist auto --persistenceDir /mnt/brooklyn-persistence
+{% endhighlight %}
+
+If you are using RPMs/deb to install, please see the [Running Apache Brooklyn]({{ site.path.guide }}/start/running.html#install-apache-brooklyn)
+documentation for the appropriate launch commands
+
+Once Brooklyn has launched, on the second VM, run the following command to launch Brooklyn in standby mode:
+
+{% highlight bash %}
+$ bin/brooklyn launch --highAvailability auto --https --persist auto --persistenceDir /mnt/brooklyn-persistence
+{% endhighlight %}
+
+### Failover
+When running as a HA standby node, each standby Brooklyn server (in this case there is only one standby) will check the shared persisted state
+every one second to determine the state of the HA master. If no heartbeat has been recorded for 30 seconds, then an election will be performed
+and one of the standby nodes will be promoted to master. At this point all requests should be directed to the new master node.
+If the master is terminated gracefully, the secondary will be immediately promoted to mater. Otherwise, the secondary will be promoted after
+heartbeats are missed for a given length of time. This defaults to 30 seconds, and is configured in brooklyn.properties using
+`brooklyn.ha.heartbeatTimeout`
+
+In the event that tasks - such as the provisioning of a new entity - are running when a failover occurs, the new master will display the current
+state of the entity, but will not resume its provisioning or re-run any partially completed tasks. In this case it may be necessary
+to remove the entity and reprovision it. In the case of a failover whilst executing a task called by an effector, it may be possible to simple
+call the effector again
+
+### Client Configuration
+It is the responsibility of the client to connect to the master Brooklyn server. This can be accomplished in a variety of ways:
+
+* ###Reverse Proxy
+
+ To allow the client application to automatically fail over in the event of a master server becoming unavailable, or the promotion of a new master,
+ a reverse proxy can be configured to route traffic depending on the response returned by `https://<ip-address>:8443/v1/server/ha/state` (see above).
+ If a server returns `"MASTER"`, then traffic should be routed to that server, otherwise it should not be. The client software should be configured
+ to connect to the reverse proxy server and no action is required by the client in the event of a failover. It can take up to 30 seconds for the
+ standby to be promoted, so the reverse proxy should retry for at least this period, or the failover time should be reconfigured to be shorter
+
+* ###Re-allocating an Elastic IP on Failover
+
+ If the cloud provider you are using supports Elastic or Floating IPs, then the IP address should be allocated to the HA master, and the client
+ application configured to connect to the floating IP address. In the event of a failure of the master node, the standby node will automatically
+ be promoted to master, and the floating IP will need to be manually re-allocated to the new master node. No action is required by the client
+ in the event of a failover. It is possible to automate the re-allocation of the floating IP if the Brooklyn servers are deployed and managed
+ by Brooklyn using the entity `org.apache.brooklyn.entity.brooklynnode.BrooklynCluster`
+
+* ###Client-based failover
+
+ In this scenario, the responsibilty for determining the Brooklyn master server falls on the client application. When configuring the client
+ application, a list of all servers in the cluster is passed in at application startup. On first connection, the client application connects to
+ any of the members of the cluster to retrieve the HA states (see above). The JSON object returned is used to determine the addresses of all
+ members of the cluster, and also to determine which node is the HA master
+
+ In the event of a failure of the master node, the client application should then retrieve the HA states of the cluster from any of the other cluster
+ members. This is the same process as when the application first connects to the cluster. The client should refresh its list of cluster memebers
+ and determine which node is the HA master
+
+ It is also recommended that the client application periodically checks the status of the cluster and updates its list of addresses. This will
+ ensure that failover is still possible if the standby server(s) has been replaced. It also allows additional standby servers to be added at any
+ time
+
+### Testing
+You can confirm that Brooklyn is running in high availibility mode on the master by logging into the web console at `https://<ip-address>:8443`.
+Similarly you can log into the web console on the standby VM where you will see a warning that the server is not the high availability master.
+
+To test a failover, you can simply terminate the process on the first VM and log into the web console on the second VM. Upon launch, Brooklyn will
+output its PID to the file `pid.txt`; you can force an immediate (non-graceful) termination of the process by running the following command
+from the same directory from which you launched Brooklyn:
+
+{% highlight bash %}
+$ kill -9 $(cat pid.txt)
+{% endhighlight %}
+
+It is also possiblity to check the high availability state of a running Brooklyn server using the following curl command:
+
+{% highlight bash %}
+$ curl -k -u myusername:mypassword https://<ip-address>:8443/v1/server/ha/state
+{% endhighlight %}
+
+This will return one of the following states:
+
+{% highlight bash %}
+
+"INITIALIZING"
+"STANDBY"
+"HOT_STANDBY"
+"HOT_BACKUP"
+"MASTER"
+"FAILED"
+"TERMINATED"
+
+{% endhighlight %}
+
+Note: The quotation characters will be included in the reply
+
+To obtain information about all of the nodes in the cluster, run the following command against any of the nodes in the cluster:
+
+{% highlight bash %}
+$ curl -k -u myusername:mypassword https://<ip-address>:8443/v1/server/ha/states
+{% endhighlight %}
+
+This will return a JSON document describing the Brooklyn nodes in the cluster. An example of two HA Brooklyn nodes is as follows (whitespace formatting has been
+added for clarity):
+
+{% highlight yaml %}
+
+{
+ ownId: "XkJeXUXE",
+ masterId: "yAVz0fzo",
+ nodes: {
+ yAVz0fzo: {
+ nodeId: "yAVz0fzo",
+ nodeUri: "https://<server1-ip-address>:8443/",
+ status: "MASTER",
+ localTimestamp: 1466414301065,
+ remoteTimestamp: 1466414301000
+ },
+ XkJeXUXE: {
+ nodeId: "XkJeXUXE",
+ nodeUri: "https://<server2-ip-address>:8443/",
+ status: "STANDBY",
+ localTimestamp: 1466414301066,
+ remoteTimestamp: 1466414301000
+ }
+ },
+ links: { }
+}
+
+{% endhighlight %}
+
+The examples above show how to use `curl` to manually check the status of Brooklyn via its REST API. The same REST API calls can also be used by
+automated third party monitoring tools such as Nagios
+
diff --git a/guide/ops/high-availability.md b/guide/ops/high-availability/index.md
similarity index 97%
rename from guide/ops/high-availability.md
rename to guide/ops/high-availability/index.md
index 5f05cca..5fc244e 100644
--- a/guide/ops/high-availability.md
+++ b/guide/ops/high-availability/index.md
@@ -1,6 +1,8 @@
---
title: High Availability
layout: website-normal
+children:
+- high-availability-supplemental.md
---
Brooklyn will automatically run in HA mode if multiple Brooklyn instances are started
diff --git a/guide/ops/index.md b/guide/ops/index.md
index 192bc77..a2f154a 100644
--- a/guide/ops/index.md
+++ b/guide/ops/index.md
@@ -3,13 +3,14 @@
started-pdf-exclude: true
layout: website-normal
children:
+- starting-stopping-monitoring.md
- server-cli-reference.md
- cli/
- gui/
- brooklyn_properties.md
- locations/
- persistence/
-- high-availability.md
+- high-availability/
- catalog/
- rest.md
- logging.md
diff --git a/guide/ops/locations/_AWS.md b/guide/ops/locations/_AWS.md
new file mode 100644
index 0000000..5d43a20
--- /dev/null
+++ b/guide/ops/locations/_AWS.md
@@ -0,0 +1,113 @@
+---
+section: Amazon Web Services (AWS)
+title: Amazon Web Services
+section_type: inline
+section_position: 3
+---
+
+## Amazon Web Services (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.
+
+
+### Using Subnets and Security Groups
+
+Apache Brooklyn can run with AWS VPC and both public and private subnets.
+Simply provide the `subnet-a1b2c3d4` as the `networkName` when deploying:
+
+ location:
+ jclouds:aws-ec2:
+ region: us-west-1
+ networkName: subnet-a1b2c3d4 # use your subnet ID
+
+Subnets are typically used in conjunction with security groups.
+Brooklyn does *not* attempt to open additional ports
+when private subnets or security groups are supplied,
+so the subnet and ports must be configured appropriately for the blueprints being deployed.
+You can configure a default security group with appropriate (or all) ports opened for
+access from the appropriate (or all) CIDRs and security groups,
+or you can define specific `securityGroups` on the location
+or as `provisioning.properties` on the entities.
+
+Make sure that Brooklyn has access to the machines under management.
+This includes SSH, which might be done with a public IP created with inbound access
+on port 22 permitted for a CIDR range including the IP from which Brooklyn contacts it.
+Alternatively you can run Brooklyn on a machine in that same subnet, or
+set up a VPN or jumphost which Brooklyn will use.
+
+
+### EC2 "Classic" Problems with VPC-only Hardware Instance Types
+
+If you have a pre-2014 Amazon account, it is likely configured in some regions to run in "EC2 Classic" mode
+by default, instead of the more modern "VPC" default mode. This can cause failures when requesting certain hardware
+configurations because many of the more recent hardware "instance types" only run in "VPC" mode.
+For instance when requesting an instance with `minRam: 8gb`, Brooklyn may opt for an `m4.large`,
+which is a VPC-only instance type. If you are in a region configured to use "EC2 Classic" mode,
+you may see a message such as this:
+
+ 400 VPCResourceNotSpecified: The specified instance type can only be used in a VPC.
+ A subnet ID or network interface ID is required to carry out the request.
+
+This is a limitation of "legacy" accounts. The easiest fixes are either:
+
+* specify an instance type which is supported in classic, such as `m3.xlarge` (see below)
+* move to a different region where VPC is the default
+ (`eu-central-1` should work as it *only* offers VPC mode,
+ irrespective of the age of your AWS account)
+* get a new AWS account -- "VPC" will be the default mode
+ (Amazon recommend this and if you want to migrate existing deployments
+ they provide [detailed instructions](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/vpc-migrate.html))
+
+To understand the situation, the following resources may be useful:
+
+* Background on VPC vs Classic: [http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-vpc.html](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-vpc.html)
+* Good succinct answers to FAQs: [http://aws.amazon.com/vpc/faqs/#Default_VPCs]()
+* Check if a region in your account is "VPC" or "Classic": [http://docs.aws.amazon.com/AmazonVPC/latest/UserGuide/default-vpc.html#default-vpc-availability]()
+* Regarding instance types:
+ * All instance types: [https://aws.amazon.com/ec2/instance-types]()
+ * Those which require VPC: [http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-vpc.html#vpc-only-instance-types]()
+
+If you want to solve this problem with your existing account,
+you can create a VPC and instruct Brooklyn to use it:
+
+1. Use the "Start VPC Wizard" option in [the VPC dashboard](https://console.aws.amazon.com/vpc),
+ making sure it is for the right region, and selecting a "Single Public Subnet".
+ (More information is in [these AWS instructions](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/get-set-up-for-amazon-ec2.html#create-a-vpc).)
+2. Once the VPC is created, open the "Subnets" view and modify the "Public subnet"
+ so that it will "Auto-assign Public IP".
+3. Next click on the "Security Groups" and find the `default` security group for that VPC.
+ Modify its "Inbound Rules" to allow "All traffic" from "Anywhere".
+ (Or for more secure options, see the instructions in the previous section,
+ "Using Subnets".)
+4. Finally make a note of the subnet ID (e.g. `subnet-a1b2c3d4`) for use in Brooklyn.
+
+You can then deploy blueprints to the subnet, allowing VPC hardware instance types,
+by specifying the subnet ID as the `networkName` in your YAML blueprint.
+This is covered in the previous section, "Using Subnets".
+
diff --git a/guide/ops/locations/_GCE.md b/guide/ops/locations/_GCE.md
new file mode 100644
index 0000000..10a739d
--- /dev/null
+++ b/guide/ops/locations/_GCE.md
@@ -0,0 +1,46 @@
+---
+section: Google Compute Engine (GCE)
+title: Google Compute Engine
+section_type: inline
+section_position: 4
+---
+
+## Google Compute Engine (GCE)
+
+### Credentials
+
+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 that when supplying the credential in a properties file, it should be one long line
+with `\n` representing 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 |
+
+
diff --git a/guide/ops/locations/byon.md b/guide/ops/locations/_byon.md
similarity index 97%
rename from guide/ops/locations/byon.md
rename to guide/ops/locations/_byon.md
index 38f6595..525916d 100644
--- a/guide/ops/locations/byon.md
+++ b/guide/ops/locations/_byon.md
@@ -1,6 +1,6 @@
---
section: BYON
-section_position: 4
+section_position: 8
section_type: inline
---
@@ -13,7 +13,7 @@
- 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).)
+- 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).)
To deploy to machines with known IP's in a blueprint, use the following syntax:
diff --git a/guide/ops/locations/clouds.md b/guide/ops/locations/_clouds.md
similarity index 80%
rename from guide/ops/locations/clouds.md
rename to guide/ops/locations/_clouds.md
index 89195fa..9aee611 100644
--- a/guide/ops/locations/clouds.md
+++ b/guide/ops/locations/_clouds.md
@@ -46,7 +46,7 @@
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)**.
+These are outlined in **[More Details for Specific Clouds](#more-details-on-specific-clouds)**.
#### OS Initial Login and Setup
@@ -154,7 +154,7 @@
- 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).)
+ (For more information on SSH keys, see [here](#ssh-keys).)
- 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
@@ -174,9 +174,36 @@
- 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`)
+- A post-provisioning `setup.script` can be specified to run an additional script, before making the `Location`
+ available to entities. This may take the form of a URL of a script or a [data URI](https://en.wikipedia.org/wiki/Data_URI_scheme).
+ Note that if using a data URI it is usually a good idea to [base64](https://en.wikipedia.org/wiki/Base64) this string to escape problem characters
+ in more complex scripts. The base64 encoded script should then be prefixed with `data:text/plain;base64,` to denote this.
+ For example if you wanted to disable a yum repository called `reponame` prior to using the machine, you could use the following command:
+
+ `sudo yum-config-manager --disable reponame`
+
+ Base64 encoding can be done with a with a tool such as [this](https://www.base64encode.org/) or a linux command such as:
+
+ `echo "sudo yum-config-manager --disable reponame" | base64`
+
+ With the base64 prefix this would then look like this:
+
+ `setup.script: data:text/plain;base64,c3VkbyB5dW0tY29uZmlnLW1hbmFnZXIgLS1kaXNhYmxlIHJlcG9uYW1l`
+
+ The `setup.script` can also take [FreeMarker](http://freemarker.org/) variables in a `setup.script.vars`
+ property. Variables are set in the format `key1:value1,key2:value2` and used in the form `${key1}`. So for the above example:
+
+ `setup.script.vars: repository:reponame`
+
+ then
+
+ `setup.script: data:sudo yum-config-manager --disable ${repository}`
+
+ or encoded in base64:
+
+ `setup.script: data:text/plain;base64,c3VkbyB5dW0tY29uZmlnLW1hbmFnZXIgLS1kaXNhYmxlICR7cmVwb3NpdG9yeX0=`
+
+ This enables the name of the repository to be passed in to the script.
- 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
@@ -240,13 +267,34 @@
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.
+###### Cloud Machine Naming
+The name that Apache Brooklyn generates for your virtual machine will, by default, be based on your Apache Brooklyn server name and the IDs of the entities involved. This is the name you see in places such as the AWS console and will look something like:
-
-See the following resources for more information:
+ brooklyn-o8jql4-machinename-rkix-tomcat-wi-nca6-14b
-- [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
+If you have created a lot of virtual machines, this kind of naming may not be helpful. This can be changed using the following YAML in your location's `brooklyn.config`:
+
+ cloudMachineNamer: org.apache.brooklyn.core.location.cloud.names.CustomMachineNamer
+ custom.machine.namer.machine: My-Custom-Name-${entity.displayName}
+
+A [FreeMarker](http://freemarker.org/) format is used in `custom.machine.namer.machine` which can take values from places such as the launching entity or location.
+
+The above example will create a name such as:
+
+ My-Custom-Name-Tomcat
+
+Allowing you to more easily identify your virtual machines.
+
+### More Details on Specific Clouds
+
+Clouds vary in the format of the identity, credential, endpoint, and region.
+Some also have their own idiosyncracies. More details for configuring some common clouds
+is included below. You may also find these sources helpful:
+
+* The **[template brooklyn.properties]({{ site.path.guide }}/start/brooklyn.properties)** file
+ in the Getting Started guide
+ contains numerous examples of configuring specific clouds,
+ including the format of credentials and options for sometimes-fiddly private clouds.
+* The **[jclouds guides](https://jclouds.apache.org/guides)** describes low-level configuration
+ sometimes required for various clouds.
diff --git a/guide/ops/locations/_ibm-softlayer.md b/guide/ops/locations/_ibm-softlayer.md
new file mode 100644
index 0000000..63cdf86
--- /dev/null
+++ b/guide/ops/locations/_ibm-softlayer.md
@@ -0,0 +1,103 @@
+---
+section: IBM Softlayer
+title: IBM Softlayer
+section_type: inline
+section_position: 5
+---
+
+## IBM SoftLayer
+
+### VLAN Selection
+
+SoftLayer may provision VMs in different VLANs, even within the same region.
+Some applications require VMs to be on the *same* internal subnet; blueprints
+for these can specify this behaviour in SoftLayer in one of two ways.
+
+The VLAN ID can be set explicitly using the fields
+`primaryNetworkComponentNetworkVlanId` and
+`primaryBackendNetworkComponentNetworkVlanId` of `SoftLayerTemplateOptions`
+when specifying the location being used in the blueprint, as follows:
+
+ location:
+ jclouds:softlayer:
+ region: ams01
+ templateOptions:
+ # Enter your preferred network IDs
+ primaryNetworkComponentNetworkVlanId: 1153481
+ primaryBackendNetworkComponentNetworkVlanId: 1153483
+
+This method requires that a VM already exist and you look up the IDs of its
+VLANs, for example in the SoftLayer console UI, and that subsequently at least
+one VM in that VLAN is kept around. If all VMs on a VLAN are destroyed
+SoftLayer may destroy the VLAN. Creating VLANs directly and then specifying
+them as IDs here may not work. Add a line note
+
+The second method tells Brooklyn to discover VLAN information automatically: it
+will provision one VM first, and use the VLAN information from it when
+provisioning subsequent machines. This ensures that all VMs are on the same
+subnet without requiring any manual VLAN referencing, making it very easy for
+end-users.
+
+To use this method, we tell brooklyn to use `SoftLayerSameVlanLocationCustomizer`
+as a location customizer. This can be done on a location as follows:
+
+ location:
+ jclouds:softlayer:
+ region: lon02
+ customizers:
+ - $brooklyn:object:
+ type: org.apache.brooklyn.location.jclouds.softlayer.SoftLayerSameVlanLocationCustomizer
+ softlayer.vlan.scopeUid: "my-custom-scope"
+ softlayer.vlan.timeout: 10m
+
+Usually you will want the scope to be unique to a single application, but if you
+need multiple applications to share the same VLAN, simply configure them with
+the same scope identifier.
+
+It is also possible with many blueprints to specify this as one of the
+`provisioning.properties` on an *application*:
+
+ services:
+ - type: org.apache.brooklyn.entity.stock.BasicApplication
+ id: same-vlan-application
+ brooklyn.config:
+ provisioning.properties:
+ customizers:
+ - $brooklyn:object:
+ type: org.apache.brooklyn.location.jclouds.softlayer.SoftLayerSameVlanLocationCustomizer
+ softlayer.vlan.scopeUid: "my-custom-scope"
+ softlayer.vlan.timeout: 10m
+
+If you are writing an entity in Java, you can also use the helper
+method `forScope(String)` to create the customizer. Configure the
+provisioning flags as follows:
+
+ JcloudsLocationCustomizer vlans = SoftLayerSameVlanLocationCustomizer.forScope("my-custom-scope");
+ flags.put(JcloudsLocationConfig.JCLOUDS_LOCATION_CUSTOMIZERS.getName(), ImmutableList.of(vlans));
+
+
+### Configuration Options
+
+The allowed configuration keys for the `SoftLayerSameVlanLocationCustomizer`
+are:
+
+- **softlayer.vlan.scopeUid** The scope identifier for locations whose
+ VMs will have the same VLAN.
+
+- **softlayer.vlan.timeout** The amount of time to wait for a VM to
+ be configured before timing out without setting the VLAN ids.
+
+- **softlayer.vlan.publicId** A specific public VLAN ID to use for
+ the specified scope.
+
+- **softlayer.vlan.privateId** A specific private VLAN ID to use for
+ the specified scope.
+
+An entity being deployed to a customized location will have the VLAN ids set as
+sensors, with the same names as the last two configuration keys.
+
+***NOTE*** If the SoftLayer location is already configured with specific VLANs
+then this customizer will have no effect.
+
+
+
diff --git a/guide/ops/locations/inheritance-and-named-locations.md b/guide/ops/locations/_inheritance-and-named-locations.md
similarity index 99%
rename from guide/ops/locations/inheritance-and-named-locations.md
rename to guide/ops/locations/_inheritance-and-named-locations.md
index 53fe904..bf237f3 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: 3
+section_position: 7
---
### Inheritance and Named Locations
diff --git a/guide/ops/locations/localhost.md b/guide/ops/locations/_localhost.md
similarity index 95%
rename from guide/ops/locations/localhost.md
rename to guide/ops/locations/_localhost.md
index 7ac906a..6558d9f 100644
--- a/guide/ops/locations/localhost.md
+++ b/guide/ops/locations/_localhost.md
@@ -1,6 +1,6 @@
---
section: Localhost
-section_position: 6
+section_position: 10
section_type: inline
---
@@ -20,7 +20,7 @@
Alternatively, you can create a specific localhost location through the location wizard tool available within the web console.
This location will be saved as a [catalog entry]({{ site.path.guide }}/ops/catalog/index.html#locations-in-catalog) for easy reusability.
-If you encounter issues or for more information, see [SSH Keys Localhost Setup](ssh-keys.html#localhost-setup).
+If you encounter issues or for more information, see [SSH Keys Localhost Setup](#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 %}
diff --git a/guide/ops/locations/_openstack.md b/guide/ops/locations/_openstack.md
new file mode 100644
index 0000000..cc45e0a
--- /dev/null
+++ b/guide/ops/locations/_openstack.md
@@ -0,0 +1,163 @@
+---
+section: Openstack
+title: Openstack
+section_type: inline
+section_position: 6
+---
+
+## Openstack
+
+### Apache jclouds
+
+Support for OpenStack is provided by Apache jclouds. For more information, see their guide
+[here](https://jclouds.apache.org/guides/openstack/).
+
+
+### Networks
+
+When multiple networks are available you should indicate which ones machines should join.
+Do this by setting the desired values id as an option in the
+**[templateOptions](#custom-template-options)** configuration:
+
+ location:
+ jclouds:openstack-nova:
+ ...
+ templateOptions:
+ # Assign the node to all networks in the list.
+ networks:
+ - network-one-id
+ - network-two-id
+ - ...
+
+
+### Floating IPs
+
+Configuration of floating IPs is as networks; specify the pools to use as another
+[template option](#custom-template-options):
+
+ location:
+ jclouds:openstack-nova:
+ ...
+ templateOptions:
+ # Pool names to use when allocating a floating IP
+ floatingIpPoolNames:
+ - "pool name"
+
+
+### Basic Location Structure
+
+This is a basic inline YAML template for an OpenStack location:
+
+ location:
+ jclouds:clouds:openstack-nova:
+ endpoint: http://x.x.x.x:5000/v2.0/
+ identity: "your-tenant:your-username"
+ credential: your-password
+
+ # imageId, hardwareId, and loginUser* are optional
+ imageId: your-region-name/your-image-id
+ hardwareId: your-region-name/your-flavor-id
+ loginUser: 'ubuntu'
+ loginUser.privateKeyFile: /path/to/your/privatekey
+
+ jclouds.openstack-nova.auto-generate-keypairs: false
+ jclouds.openstack-nova.auto-create-floating-ips: true
+
+ templateOptions:
+ networks: [ "your-network-id" ]
+ floatingIpPoolNames: [ "your-floatingIp-pool" ]
+ securityGroups: ['your-security-group']
+
+ # Optional if 'jclouds.openstack-nova.auto-generate-keypairs' is assigned to 'true'
+ keyPairName: "your-keypair"
+
+This is the same OpenStack location in a format that can be added to your
+`brooklyn.properties` file:
+
+ brooklyn.location.named.My\ Openstack=jclouds:openstack-nova:http://x.x.x.x:5000/v2.0/
+ brooklyn.location.named.My\ OpenStack.identity=your-tenant:your-username
+ brooklyn.location.named.My\ OpenStack.credential=your-password
+ brooklyn.location.named.My\ OpenStack.endpoint=http://x.x.x.x:5000/v2.0/
+
+ brooklyn.location.named.My\ OpenStack.imageId=your-region-name/your-image-id
+ brooklyn.location.named.My\ OpenStack.hardwareId=your-region-name/your-flavor-id
+ brooklyn.location.named.My\ OpenStack.loginUser=ubuntu
+ brooklyn.location.named.My\ OpenStack.loginUser.privateKeyFile=/path/to/your/privatekey
+ brooklyn.location.named.My\ OpenStack.openstack-nova.auto-generate-keypairs=false
+ brooklyn.location.named.My\ OpenStack.openstack-nova.auto-create-floating-ips=true
+
+ brooklyn.location.named.My\ OpenStack.networks=your-network-id
+ brooklyn.location.named.My\ OpenStack.floatingIpPoolNames=your-floatingIp-pool
+ brooklyn.location.named.My\ OpenStack.securityGroups=your-security-group
+ brooklyn.location.named.My\ OpenStack.keyPair=your-keypair
+
+Chose a value of `your-flavor-id` from one of the defaults, or create your own flavor if
+you have administrator privileges.
+For for more information, see the
+[OpenStack flavors guide](http://docs.openstack.org/admin-guide/cli_manage_flavors.html).
+
+The default flavors are:
+
+ +-----+-----------+-----------+------+
+ | ID | Name | Memory_MB | Disk |
+ +-----+-----------+-----------+------+
+ | 1 | m1.tiny | 512 | 1 |
+ | 2 | m1.small | 2048 | 20 |
+ | 3 | m1.medium | 4096 | 40 |
+ | 4 | m1.large | 8192 | 80 |
+ | 5 | m1.xlarge | 16384 | 160 |
+ +-----+-----------+-----------+------+
+
+For an even more detailed example location configuration, consult the
+[template properties file](https://brooklyn.apache.org/v/latest/start/brooklyn.properties).
+
+
+### Other features
+
+Consult jclouds' [Nova template options](https://jclouds.apache.org/reference/javadoc/1.9.x/org/jclouds/openstack/nova/v2_0/compute/options/NovaTemplateOptions.html)
+for futher options when configuring Openstack locations.
+
+### Troubleshooting
+
+#### jclouds Namespace Issue
+
+A change to Nova's API resulted in all extensions having the same "fake" namespace which
+the current version of jclouds does not yet support.
+
+If you are having problems deploying to OpenStack, consult your Brooklyn debug log and
+look for the following:
+
+
+ "namespace": "http://docs.openstack.org/compute/ext/fake_xml"
+
+
+If this appears, perform the following steps as a workaround:
+
+* Generate a patch JAR `openstack-devtest-compute-1.9.2.jar`
+by building: https://github.com/cloudsoft/jclouds-openstack-devtest
+* Copy the patch JAR into $BROOKLYN_HOME/lib/patch
+* Change `jclouds:openstack-nova` to `jclouds:openstack-devtest-compute` in your location
+configuration
+
+Here is a simple example template to be used with this workaround:
+
+
+ location:
+ jclouds:openstack-devtest-compute:
+ endpoint: http://x.x.x.x:5000/v2.0/
+ identity: "your-tenant:your-username"
+ credential: your-password
+ templateOptions:
+ networks: [ "your-network-id" ]
+ floatingIpPoolNames: [ "your-floatingIp-pool" ]
+
+
+Note that the following values will be set by default when omitted above:
+
+
+ jclouds.keystone.credential-type=passwordCredentials
+ jclouds.openstack-nova.auto-generate-keypairs: true
+ jclouds.openstack-nova.auto-create-floating-ips: true
+
+
+
diff --git a/guide/ops/locations/_special-locations.md b/guide/ops/locations/_special-locations.md
new file mode 100644
index 0000000..a3a69c6
--- /dev/null
+++ b/guide/ops/locations/_special-locations.md
@@ -0,0 +1,87 @@
+---
+section: Specialized Locations
+section_position: 11
+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 %}
+location: host:(192.168.0.1)
+services:
+- type: org.apache.brooklyn.entity.webapp.jboss.JBoss7Server
+{% 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.
+
+In its simplest form, this will use the first target location where possible,
+and will then switch to the second and subsequent locations when there are no
+machine available.
+
+In the example below, it provisions the first node to `192.168.0.1`, then it provisions into AWS
+us-east-1 region (because the bring-your-own-nodes region will have run out of nodes).
+
+{% highlight yaml %}
+location:
+ multi:
+ targets:
+ - byon:(hosts=192.168.0.1)
+ - jclouds:aws-ec2:us-east-1
+services:
+- type: org.apache.brooklyn.entity.group.DynamicCluster
+ brooklyn.config:
+ initialSize: 3
+ memberSpec:
+ $brooklyn:entitySpec:
+ type: org.apache.brooklyn.entity.machine.MachineEntity
+{% endhighlight %}
+
+The `multi` location also supports the "availability zone" location extension: it presents each
+target location as an "availability zone". This means that a cluster can be configured to
+round-robin across the targets.
+
+For example, in the blueprint below the cluster will request VMs round-robin across the three zones
+(where `zone1` etc are locations already added to the catalog, or defined in brooklyn.properties).
+The configuration option `dynamiccluster.zone.enable` on `DynamicCluster` tells it to query the
+given location for the `AvailabilityZoneExtension`. If available, it will query for the list of
+zones (in this case the list of targets), and then use them round-robin. Custom alternatives to
+round-robin are also possible using the configuration option `dynamiccluster.zone.placementStrategy`
+on `DynamicCluster`.
+
+{% highlight yaml %}
+location:
+ multi:
+ targets:
+ - zone1
+ - zone2
+ - zone3
+services:
+- type: org.apache.brooklyn.entity.group.DynamicCluster
+ brooklyn.config:
+ dynamiccluster.zone.enable: true
+ initialSize: 4
+ memberSpec:
+ $brooklyn:entitySpec:
+ type: org.apache.brooklyn.entity.machine.MachineEntity
+{% endhighlight %}
+
+
+#### 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.
+
diff --git a/guide/ops/locations/ssh-keys.md b/guide/ops/locations/_ssh-keys.md
similarity index 99%
rename from guide/ops/locations/ssh-keys.md
rename to guide/ops/locations/_ssh-keys.md
index 03ee84e..a929acf 100644
--- a/guide/ops/locations/ssh-keys.md
+++ b/guide/ops/locations/_ssh-keys.md
@@ -1,6 +1,6 @@
---
section: SSH Keys
-section_position: 5
+section_position: 9
section_type: inline
---
diff --git a/guide/ops/locations/cloud-credentials.md b/guide/ops/locations/cloud-credentials.md
index 1594012..36041e0 100644
--- a/guide/ops/locations/cloud-credentials.md
+++ b/guide/ops/locations/cloud-credentials.md
@@ -3,4 +3,4 @@
layout: website-normal
---
-This page has moved. See [More Clouds](more-clouds.html) instead.
+This page has moved. See [More Clouds](index.html#more-details-on-specific-clouds) instead.
diff --git a/guide/ops/locations/more-clouds.md b/guide/ops/locations/more-clouds.md
deleted file mode 100644
index acfd274..0000000
--- a/guide/ops/locations/more-clouds.md
+++ /dev/null
@@ -1,274 +0,0 @@
----
-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.
-
-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. For public clouds, Brooklyn comes preconfigured
-with the endpoints, but many offer different choices of the `region` where you might want to deploy.
-
-Clouds vary in the format of the identity, credential, endpoint, and region.
-Some also have their own idiosyncracies. More details for configuring some common clouds
-is included below. You may also find these sources helpful:
-
-* The **[template brooklyn.properties]({{ site.path.guide }}/start/brooklyn.properties)** file
- in the Getting Started guide
- contains numerous examples of configuring specific clouds,
- including the format of credentials and options for sometimes-fiddly private clouds.
-* The **[jclouds guides](https://jclouds.apache.org/guides)** describes low-level configuration
- sometimes required for various clouds.
-
-
-
-## Amazon Web Services (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.
-
-
-### Using Subnets and Security Groups
-
-Apache Brooklyn can run with AWS VPC and both public and private subnets.
-Simply provide the `subnet-a1b2c3d4` as the `networkName` when deploying:
-
- location:
- jclouds:aws-ec2:
- region: us-west-1
- networkName: subnet-a1b2c3d4 # use your subnet ID
-
-Subnets are typically used in conjunction with security groups.
-Brooklyn does *not* attempt to open additional ports
-when private subnets or security groups are supplied,
-so the subnet and ports must be configured appropriately for the blueprints being deployed.
-You can configure a default security group with appropriate (or all) ports opened for
-access from the appropriate (or all) CIDRs and security groups,
-or you can define specific `securityGroups` on the location
-or as `provisioning.properties` on the entities.
-
-Make sure that Brooklyn has access to the machines under management.
-This includes SSH, which might be done with a public IP created with inbound access
-on port 22 permitted for a CIDR range including the IP from which Brooklyn contacts it.
-Alternatively you can run Brooklyn on a machine in that same subnet, or
-set up a VPN or jumphost which Brooklyn will use.
-
-
-### EC2 "Classic" Problems with VPC-only Hardware Instance Types
-
-If you have a pre-2014 Amazon account, it is likely configured in some regions to run in "EC2 Classic" mode
-by default, instead of the more modern "VPC" default mode. This can cause failures when requesting certain hardware
-configurations because many of the more recent hardware "instance types" only run in "VPC" mode.
-For instance when requesting an instance with `minRam: 8gb`, Brooklyn may opt for an `m4.large`,
-which is a VPC-only instance type. If you are in a region configured to use "EC2 Classic" mode,
-you may see a message such as this:
-
- 400 VPCResourceNotSpecified: The specified instance type can only be used in a VPC.
- A subnet ID or network interface ID is required to carry out the request.
-
-This is a limitation of "legacy" accounts. The easiest fixes are either:
-
-* specify an instance type which is supported in classic, such as `m3.xlarge` (see below)
-* move to a different region where VPC is the default
- (`eu-central-1` should work as it *only* offers VPC mode,
- irrespective of the age of your AWS account)
-* get a new AWS account -- "VPC" will be the default mode
- (Amazon recommend this and if you want to migrate existing deployments
- they provide [detailed instructions](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/vpc-migrate.html))
-
-To understand the situation, the following resources may be useful:
-
-* Background on VPC vs Classic: [http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-vpc.html](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-vpc.html)
-* Good succinct answers to FAQs: [http://aws.amazon.com/vpc/faqs/#Default_VPCs]()
-* Check if a region in your account is "VPC" or "Classic": [http://docs.aws.amazon.com/AmazonVPC/latest/UserGuide/default-vpc.html#default-vpc-availability]()
-* Regarding instance types:
- * All instance types: [https://aws.amazon.com/ec2/instance-types]()
- * Those which require VPC: [http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-vpc.html#vpc-only-instance-types]()
-
-If you want to solve this problem with your existing account,
-you can create a VPC and instruct Brooklyn to use it:
-
-1. Use the "Start VPC Wizard" option in [the VPC dashboard](https://console.aws.amazon.com/vpc),
- making sure it is for the right region, and selecting a "Single Public Subnet".
- (More information is in [these AWS instructions](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/get-set-up-for-amazon-ec2.html#create-a-vpc).)
-2. Once the VPC is created, open the "Subnets" view and modify the "Public subnet"
- so that it will "Auto-assign Public IP".
-3. Next click on the "Security Groups" and find the `default` security group for that VPC.
- Modify its "Inbound Rules" to allow "All traffic" from "Anywhere".
- (Or for more secure options, see the instructions in the previous section,
- "Using Subnets".)
-4. Finally make a note of the subnet ID (e.g. `subnet-a1b2c3d4`) for use in Brooklyn.
-
-You can then deploy blueprints to the subnet, allowing VPC hardware instance types,
-by specifying the subnet ID as the `networkName` in your YAML blueprint.
-This is covered in the previous section, "Using Subnets".
-
-
-## Google Compute Engine (GCE)
-
-### Credentials
-
-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 that when supplying the credential in a properties file, it should be one long line
-with `\n` representing 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 |
-
-## IBM SoftLayer
-
-### VLAN Selection
-
-SoftLayer may provision VMs in different VLANs, even within the same region.
-Some applications require VMs to be on the *same* internal subnet; blueprints
-for these can specify this behaviour in SoftLayer in one of two ways.
-
-The VLAN ID can be set explicitly using the fields
-`primaryNetworkComponentNetworkVlanId` and
-`primaryBackendNetworkComponentNetworkVlanId` of `SoftLayerTemplateOptions`
-when specifying the location being used in the blueprint, as follows:
-
-```YAML
-location:
- jclouds:softlayer:
- region: ams01
- templateOptions:
- # Enter your preferred network IDs
- primaryNetworkComponentNetworkVlanId: 1153481
- primaryBackendNetworkComponentNetworkVlanId: 1153483
-```
-
-This method requires that a VM already exist and you look up the IDs of its
-VLANs, for example in the SoftLayer console UI, and that subsequently at least
-one VM in that VLAN is kept around. If all VMs on a VLAN are destroyed
-SoftLayer may destroy the VLAN. Creating VLANs directly and then specifying
-them as IDs here may not work. Add a line note
-
-The second method tells Brooklyn to discover VLAN information automatically: it
-will provision one VM first, and use the VLAN information from it when
-provisioning subsequent machines. This ensures that all VMs are on the same
-subnet without requiring any manual VLAN referencing, making it very easy for
-end-users.
-
-To use this method, we tell brooklyn to use `SoftLayerSameVlanLocationCustomizer`
-as a location customizer. This can be done on a location as follows:
-
-```YAML
-location:
- jclouds:softlayer:
- region: lon02
- customizers:
- - $brooklyn:object:
- type: org.apache.brooklyn.location.jclouds.softlayer.SoftLayerSameVlanLocationCustomizer
- softlayer.vlan.scopeUid: "my-custom-scope"
- softlayer.vlan.timeout: 10m
-```
-
-Usually you will want the scope to be unique to a single application, but if you
-need multiple applications to share the same VLAN, simply configure them with
-the same scope identifier.
-
-It is also possible with many blueprints to specify this as one of the
-`provisioning.properties` on an *application*:
-
-```YAML
-services:
-- type: org.apache.brooklyn.entity.stock.BasicApplication
- id: same-vlan-application
- brooklyn.config:
- provisioning.properties:
- customizers:
- - $brooklyn:object:
- type: org.apache.brooklyn.location.jclouds.softlayer.SoftLayerSameVlanLocationCustomizer
- softlayer.vlan.scopeUid: "my-custom-scope"
- softlayer.vlan.timeout: 10m
-```
-
-If you are writing an entity in Java, you can also use the helper
-method `forScope(String)` to create the customizer. Configure the
-provisioning flags as follows:
-
-```Java
-JcloudsLocationCustomizer vlans = SoftLayerSameVlanLocationCustomizer.forScope("my-custom-scope");
-flags.put(JcloudsLocationConfig.JCLOUDS_LOCATION_CUSTOMIZERS.getName(), ImmutableList.of(vlans));
-```
-
-### Configuration Options
-
-The allowed configuration keys for the `SoftLayerSameVlanLocationCustomizer`
-are:
-
-- **softlayer.vlan.scopeUid** The scope identifier for locations whose
- VMs will have the same VLAN.
-
-- **softlayer.vlan.timeout** The amount of time to wait for a VM to
- be configured before timing out without setting the VLAN ids.
-
-- **softlayer.vlan.publicId** A specific public VLAN ID to use for
- the specified scope.
-
-- **softlayer.vlan.privateId** A specific private VLAN ID to use for
- the specified scope.
-
-An entity being deployed to a customized location will have the VLAN ids set as
-sensors, with the same names as the last two configuration keys.
-
-***NOTE*** If the SoftLayer location is already configured with specific VLANs
-then this customizer will have no effect.
diff --git a/guide/ops/locations/special-locations.md b/guide/ops/locations/special-locations.md
deleted file mode 100644
index 8f19fa4..0000000
--- a/guide/ops/locations/special-locations.md
+++ /dev/null
@@ -1,54 +0,0 @@
----
-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.
-
diff --git a/guide/ops/persistence/index.md b/guide/ops/persistence/index.md
index 30c3d5f..57996cb 100644
--- a/guide/ops/persistence/index.md
+++ b/guide/ops/persistence/index.md
@@ -170,6 +170,20 @@
* `--transformations` <transformations>
The local transformations file to be applied to the copy of the data before uploading it.
+## CLI Commands for Cleaning Orphaned State
+
+Brooklyn includes a command to clean orphaned state which uses the copy state command
+and removes orphaned locations, enrichers, policies and feeds from the copied state.
+The `clean-orphaned-state` CLI command takes the following arguments:
+
+* `--persistenceDir` <source persistence dir>
+ The directory to read persisted state (or container name if using an object store).
+* `--persistenceLocation` <source persistence location>
+ The location spec for an object store to read persisted state.
+* `--destinationDir` <target persistence dir>
+ The directory to copy persistence data to, with orphaned state removed.
+* `--destinationLocation` <target persistence location>
+ The location spec for an object store to copy data to.
## Handling Rebind Failures
diff --git a/guide/ops/production-installation.md b/guide/ops/production-installation.md
index b0110d5..3748712 100644
--- a/guide/ops/production-installation.md
+++ b/guide/ops/production-installation.md
@@ -15,22 +15,23 @@
This guide covers the basics. You may also wish to configure:
-* [Logging](logging.md)
+* [Logging](logging.html)
* [Persistence](persistence/)
-* [High availability](high-availability.md)
+* [High availability](high-availability/)
### <a id="prerequisites"></a>Set up the Prerequisites
-Check that the server meets the [requirements](requirements.md).
+Check that the server meets the [requirements](requirements.html).
Then configure the server as follows:
* install Java JRE or JDK (version 7 or later)
-* install an [SSH key]({{ site.path.guide }}/ops/locations/ssh-keys.html), if not available
-* enable [passwordless ssh login]({{ site.path.guide }}/ops/locations/ssh-keys.html)
+* install an [SSH key]({{ site.path.guide }}/ops/locations/index.html#ssh-keys), if not available
+* enable [passwordless ssh login]({{ site.path.guide }}/ops/locations/index.html#ssh-keys)
* create a `~/.brooklyn` directory on the host with `$ mkdir ~/.brooklyn`
* check your `iptables` or other firewall service, making sure that incoming connections on port 8443 is not blocked
* check that the [linux kernel entropy]({{ site.path.website }}/documentation/increase-entropy.html) is sufficient
+* ensure external libraries are up-to-date, including `nss` for SSL.
### <a id="download"></a>Download Apache Brooklyn
@@ -66,7 +67,7 @@
### <a id="configuring-properties"></a>Configuring brooklyn.properties
-Set up `brooklyn.properties` as described [here](brooklyn_properties.md):
+Set up `brooklyn.properties` as described [here](brooklyn_properties.html):
* Configure the users who should have access
* Turn on HTTPS
diff --git a/guide/ops/requirements.md b/guide/ops/requirements.md
index 634e4e6..86a186a 100644
--- a/guide/ops/requirements.md
+++ b/guide/ops/requirements.md
@@ -19,11 +19,54 @@
any binaries for custom blueprints/integrations.
+### Disk Space
+
+There are three main consumers of disk space:
+
+* **Static files**: these are the Apache Brooklyn distribution with its own
+ dependencies, plus binaries for custom blueprints and integrations added to
+ the `lib` directory. Note that Brooklyn requires that Java is installed which
+ you may have to consider when calculating disk space requirements.
+* **Persisted state**: when using [Persistence](persistence/index.html) -- which
+ is a prerequisite for [High Availability](high-availability.html) -- Brooklyn
+ will save data to a store location. Items in the persisted state include
+ metadata about the Brooklyn servers, catalog items, and metadata about all
+ running applications and entities.
+* **Log files**: Brooklyn writes info and debug log files. By default, these are
+ written to the local filesystem. This can be reconfigured to set the
+ destination and to increase or decrease the detail in the logs. See the
+ [Logging](logging.html) section for more details.
+
+The Apache Brooklyn distribution itself, when unpacked, consumes approximately
+75MB of disk space. This includes everything needed to run Brooklyn except for a
+Java VM. The space consumed by additional binaries for custom blueprints and
+integrations is application-specific.
+
+Persisted state, excluding catalog data, is relatively small, starting at
+approximately 300KB for a clean, idle Brooklyn server. Deploying blueprints will
+add to this - how much depends exactly on the entities involved and is therefore
+application specific, but as a guideline, a 3-node Riak cluster adds
+approximately 500KB to the persistence store.
+
+Log data can be a large consumer of disk space. By default Brooklyn generates
+two logfiles, one which logs notable information only, and another which logs at
+a debug level. Each logfile rotates when it hits a size of 100MB; a maximum of
+10 log files are retained for each type. The two logging streams combined,
+therefore, can consume up to 2GB of disk space.
+
+In the default configuration of Brooklyn's `.tar.gz` and `.zip` distributions,
+logs are saved to the Brooklyn installation directory. You will most likely want
+to [reconfigure Brooklyn's logging](logging.html) to save logs to a location
+elsewhere. In the `.rpm` and `.deb` packaging, logging files will be located
+under `/var/log`. You can further reconfiguring the logging detail level and log
+rotation according to your organisation's policy.
+
+
## Supported Operating Systems
The recommended operating system is CentOS 6.x or RedHat 6.x.
-Brooklyn has also been tested on Ubuntu 12.04 and OS X.
+Brooklyn has also been tested on Ubuntu 14.04 and OS X.
## Software Requirements
diff --git a/guide/ops/server-cli-reference.md b/guide/ops/server-cli-reference.md
index 107920d..407de29 100644
--- a/guide/ops/server-cli-reference.md
+++ b/guide/ops/server-cli-reference.md
@@ -11,7 +11,7 @@
To launch Brooklyn, from the directory where Brooklyn is unpacked, run:
{% highlight bash %}
-% nohup bin/brooklyn launch > /dev/null 2&>1 &
+% nohup bin/brooklyn launch > /dev/null 2>&1 &
{% endhighlight %}
With no configuration, this will launch the Brooklyn web console and REST API on [`http://localhost:8081/`](http://localhost:8081/).
@@ -74,6 +74,12 @@
memory. It will only expunge tasks from memory when this space is required for other objects within the
Brooklyn process.
+### Web Console Bind Address
+
+The web console will by default bind to 0.0.0.0. It's restricted to 127.0.0.1 if the `--noConsoleSecurity` flag is used.
+To specify a local interface, or use the local loopback (127.0.0.1), for the web console to bind to you should use:
+
+ --bindAddress <IP>
## Configuration
diff --git a/guide/ops/starting-stopping-monitoring.md b/guide/ops/starting-stopping-monitoring.md
new file mode 100644
index 0000000..ffd9084
--- /dev/null
+++ b/guide/ops/starting-stopping-monitoring.md
@@ -0,0 +1,83 @@
+---
+title: Starting, Stopping and Monitoring
+layout: website-normal
+---
+
+**NOTE:** This document is for information on starting an Apache Brooklyn
+Server. For information on using the Brooklyn Client CLI to access an already
+running Brooklyn Server, refer to [Client CLI Reference](cli/index.html).
+
+## Packages for RHEL/CentOS and Ubuntu
+
+If you are using the `.rpm` or `.deb` package of Apache Brooklyn, then Brooklyn
+will integrate with your OS service management. Commands such as
+`service brooklyn start` will work as expected, and Brooklyn's PID file will be
+stored in the normal location for your OS, such as `/var/run/brooklyn.pid`.
+
+
+## Platform-independent distributions
+
+The platform-independent distributions are packaged in `.tar.gz` and `.zip`
+files.
+
+
+### Starting
+
+To launch Brooklyn, from the directory where Brooklyn is unpacked, run:
+
+{% highlight bash %}
+% bin/brooklyn launch > /dev/null 2>&1 & disown
+{% endhighlight %}
+
+With no configuration, this will launch the Brooklyn web console and REST API on [`http://localhost:8081/`](http://localhost:8081/).
+No password is set, but the server is listening only on the loopback network interface for security.
+Once [security is configured](brooklyn_properties.html), Brooklyn will listen on all network interfaces by default.
+
+See the [Server CLI Reference](server-cli-reference.html) for more information
+about the Brooklyn server process.
+
+The Brooklyn startup script will create a file name `pid_java` at the root of
+the Brooklyn directory, which contains the PID of the last Brooklyn process to
+be started.
+
+
+### Stopping
+
+To stop Brooklyn, simply send a `TERM` signal to the Brooklyn process. The PID
+of the most recently run Brooklyn process can be found in the `pid_java` file at
+the root of the Brooklyn directory.
+
+For example:
+
+{% highlight bash %}
+% kill $( cat pid_java )
+{% endhighlight bash %}
+
+
+## Monitoring
+
+For `.tar.gz` and `.zip` distributions of Brooklyn, the Brooklyn startup script
+will create a file name `pid_java` at the root of the Brooklyn directory, which
+contains the PID of the last Brooklyn process to be started. You can examine
+this file to discover the PID, and then test that the process is still running.
+`.rpm` and `.deb` distributions of Brooklyn will use the normal mechanism that
+your OS uses, such as writing to `/var/run/brooklyn.pid`.
+
+This should lead to a fairly straightforward integration with many monitoring
+tools - the monitoring tool can discover the expected PID, and can execute the
+start or stop commands shown above as necessary.
+
+For example, here is a fragment of a `monitrc` file as used by
+[Monit](http://https://mmonit.com/monit/), for a Brooklyn `.tar.gz` distribution
+unpacked and installed at `/opt/apache-brooklyn`:
+
+{% highlight text %}
+check process apachebrooklyn with pidfile /opt/apache-brooklyn/pid_java
+ start program = "/bin/bash -c '/opt/apache-brooklyn/bin/brooklyn launch --persist auto & disown'" with timeout 10 seconds
+ stop program = "/bin/bash -c 'kill $( cat /opt/apache-brooklyn/pid_java )'"
+{% endhighlight %}
+
+In addition to monitoring the Brooklyn process itself, you will almost certainly
+want to monitor resource usage of Brooklyn. In particular, please see the
+[Requirements](requirements.html#disk-space) section for a discussion on Brooklyn's disk
+space requirements.
diff --git a/guide/ops/troubleshooting/_connectivity.md b/guide/ops/troubleshooting/_connectivity.md
new file mode 100644
index 0000000..a7117ac
--- /dev/null
+++ b/guide/ops/troubleshooting/_connectivity.md
@@ -0,0 +1,149 @@
+
+A common problem when setting up an application in the cloud is getting the basic connectivity right - how
+do I get my service (e.g. a TCP host:port) publicly accessible over the internet?
+
+This varies a lot - e.g. Is the VM public or in a private network? Is the service only accessible through
+a load balancer? Should the service be globally reachable or only to a particular CIDR?
+
+This guide gives some general tips for debugging connectivity issues, which are applicable to a
+range of different service types. Choose those that are appropriate for your use-case.
+
+## VM reachable
+If the VM is supposed to be accessible directly (e.g. from the public internet, or if in a private network
+then from a jump host)...
+
+### ping
+Can you `ping` the VM from the machine you are trying to reach it from?
+
+However, ping is over ICMP. If the VM is unreachable, it could be that the firewall forbids ICMP but still
+lets TCP traffic through.
+
+### telnet to TCP port
+You can check if a given TCP port is reachable and listening using `telnet <host> <port>`, such as
+`telnet www.google.com 80`, which gives output like:
+
+```
+ Trying 31.55.163.219...
+ Connected to www.google.com.
+ Escape character is '^]'.
+```
+
+If this is very slow to respond, it can be caused by a firewall blocking access. If it is fast, it could
+be that the server is just not listening on that port.
+
+### DNS and routing
+If using a hostname rather than IP, then is it resolving to a sensible IP?
+
+Is the route to the server sensible? (e.g. one can hit problems with proxy servers in a corporate
+network, or ISPs returning a default result for unknown hosts).
+
+The following commands can be useful:
+
+* `host` is a DNS lookup utility. e.g. `host www.google.com`.
+* `dig` stands for "domain information groper". e.g. `dig www.google.com`.
+* `traceroute` prints the route that packets take to a network host. e.g. `traceroute www.google.com`.
+
+## Proxy settings
+Depending on the type of location, brooklyn might use HTTP to provision machines (clocker, jclouds). If the host environment defines proxy settings, these might interfere with the reachability of the respective HTTP service.
+
+One such case is using VirtualBox with host-only or private internal network settings, while using an external proxy for accessing the internet. It is clear that the external proxy won't be able to route HTTP calls properly, but that might not be clear when reading the logs (although brooklyn will present the failing URL).
+
+Try accessing the web-service URLs from a browser via the proxy, or perhaps try running brooklyn with proxy disabled:
+```
+ export http_proxy=
+ bin/brooklyn launch
+```
+
+## Service is listening
+
+### Service responds
+Try connecting to the service from the VM itself. For example, `curl http://localhost:8080` for a
+web-service.
+
+On dev/test VMs, don't be afraid to install the utilities you need such as `curl`, `telnet`, `nc`,
+etc. Cloud VMs often have a very cut-down set of packages installed. For example, execute
+`sudo apt-get update; sudo apt-get install -y curl` or `sudo yum install -y curl`.
+
+### Listening on port
+Check that the service is listening on the port, and on the correct NIC(s).
+
+Execute `netstat -antp` (or on OS X `netstat -antp TCP`) to list the TCP ports in use (or use
+`-anup` for UDP). You should expect to see the something like the output below for a service.
+
+```
+Proto Recv-Q Send-Q Local Address Foreign Address State PID/Program name
+tcp 0 0 :::8080 :::* LISTEN 8276/java
+```
+
+In this case a Java process with pid 8276 is listening on port 8080. The local address `:::8080`
+format means all NICs (in IPv6 address format). You may also see `0.0.0.0:8080` for IPv4 format.
+If it says 127.0.0.1:8080 then your service will most likely not be reachable externally.
+
+Use `ip addr show` (or the obsolete `ifconfig -a`) to see the network interfaces on your server.
+
+For `netstat`, run with `sudo` to see the pid for all listed ports.
+
+## Firewalls
+On Linux, check if `iptables` is preventing the remote connection. On Windows, check the Windows Firewall.
+
+If it is acceptable (e.g. it is not a server in production), try turning off the firewall temporarily,
+and testing connectivity again. Remember to re-enable it afterwards! On CentOS, this is `sudo service
+iptables stop`. On Ubuntu, use `sudo ufw disable`. On Windows, press the Windows key and type 'Windows
+Firewall with Advanced Security' to open the firewall tools, then click 'Windows Firewall Properties'
+and set the firewall state to 'Off' in the Domain, Public and Private profiles.
+
+If you cannot temporarily turn off the firewall, then look carefully at the firewall settings. For
+example, execute `sudo iptables -n --list` and `iptables -t nat -n --list`.
+
+## Cloud firewalls
+Some clouds offer a firewall service, where ports need to be explicitly listed to be reachable.
+
+For example, [security groups for EC2-classic]
+(http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-network-security.html#ec2-classic-security-groups)
+have rules for the protocols and ports to be reachable from specific CIDRs.
+
+Check these settings via the cloud provider's web-console (or API).
+
+## Quick test of a listener port
+It can be useful to start listening on a given port, and to then check if that port is reachable.
+This is useful for testing basic connectivity when your service is not yet running, or to a
+different port to compare behaviour, or to compare with another VM in the network.
+
+The `nc` netcat tool is useful for this. For example, `nc -l 0.0.0.0 8080` will listen on port
+TCP 8080 on all network interfaces. On another server, you can then run `echo hello from client
+| nc <hostname> 8080`. If all works well, this will send "hello from client" over the TCP port 8080,
+which will be written out by the `nc -l` process before exiting.
+
+Similarly for UDP, you use `-lU`.
+
+You may first have to install `nc`, e.g. with `sudo yum install -y nc` or `sudo apt-get install netcat`.
+
+### Cloud load balancers
+For some use-cases, it is good practice to use the load balancer service offered by the cloud provider
+(e.g. [ELB in AWS](http://aws.amazon.com/elasticloadbalancing/) or the [Cloudstack Load Balancer]
+(http://docs.cloudstack.apache.org/projects/cloudstack-installation/en/latest/network_setup.html#management-server-load-balancing))
+
+The VMs can all be isolated within a private network, with access only through the load balancer service.
+
+Debugging techniques here include ensuring connectivity from another jump server within the private
+network, and careful checking of the load-balancer configuration from the Cloud Provider's web-console.
+
+### DNAT
+Use of DNAT is appropriate for some use-cases, where a particular port on a particular VM is to be
+made available.
+
+Debugging connectivity issues here is similar to the steps for a cloud load balancer. Ensure
+connectivity from another jump server within the private network. Carefully check the NAT rules from
+the Cloud Provider's web-console.
+
+### Guest wifi
+It is common for guest wifi to restrict access to only specific ports (e.g. 80 and 443, restricting
+ssh over port 22 etc).
+
+Normally your best bet is then to abandon the guest wifi (e.g. to tether to a mobile phone instead).
+
+There are some unconventional workarounds such as [configuring sshd to listen on port 80 so you can
+use an ssh tunnel](http://askubuntu.com/questions/107173/is-it-possible-to-ssh-through-port-80).
+However, the firewall may well inspect traffic so sending non-http traffic over port 80 may still fail.
+
+
diff --git a/guide/ops/troubleshooting/connectivity.md b/guide/ops/troubleshooting/connectivity.md
index b6b0ba5..0ec7139 100644
--- a/guide/ops/troubleshooting/connectivity.md
+++ b/guide/ops/troubleshooting/connectivity.md
@@ -4,151 +4,4 @@
toc: /guide/toc.json
---
-A common problem when setting up an application in the cloud is getting the basic connectivity right - how
-do I get my service (e.g. a TCP host:port) publicly accessible over the internet?
-
-This varies a lot - e.g. Is the VM public or in a private network? Is the service only accessible through
-a load balancer? Should the service be globally reachable or only to a particular CIDR?
-
-This guide gives some general tips for debugging connectivity issues, which are applicable to a
-range of different service types. Choose those that are appropriate for your use-case.
-
-## VM reachable
-If the VM is supposed to be accessible directly (e.g. from the public internet, or if in a private network
-then from a jump host)...
-
-### ping
-Can you `ping` the VM from the machine you are trying to reach it from?
-
-However, ping is over ICMP. If the VM is unreachable, it could be that the firewall forbids ICMP but still
-lets TCP traffic through.
-
-### telnet to TCP port
-You can check if a given TCP port is reachable and listening using `telnet <host> <port>`, such as
-`telnet www.google.com 80`, which gives output like:
-
-```
- Trying 31.55.163.219...
- Connected to www.google.com.
- Escape character is '^]'.
-```
-
-If this is very slow to respond, it can be caused by a firewall blocking access. If it is fast, it could
-be that the server is just not listening on that port.
-
-### DNS and routing
-If using a hostname rather than IP, then is it resolving to a sensible IP?
-
-Is the route to the server sensible? (e.g. one can hit problems with proxy servers in a corporate
-network, or ISPs returning a default result for unknown hosts).
-
-The following commands can be useful:
-
-* `host` is a DNS lookup utility. e.g. `host www.google.com`.
-* `dig` stands for "domain information groper". e.g. `dig www.google.com`.
-* `traceroute` prints the route that packets take to a network host. e.g. `traceroute www.google.com`.
-
-## Proxy settings
-Depending on the type of location, brooklyn might use HTTP to provision machines (clocker, jclouds). If the host environment defines proxy settings, these might interfere with the reachability of the respective HTTP service.
-
-One such case is using VirtualBox with host-only or private internal network settings, while using an external proxy for accessing the internet. It is clear that the external proxy won't be able to route HTTP calls properly, but that might not be clear when reading the logs (although brooklyn will present the failing URL).
-
-Try accessing the web-service URLs from a browser via the proxy, or perhaps try running brooklyn with proxy disabled:
-```
- export http_proxy=
- bin/brooklyn launch
-```
-
-## Service is listening
-
-### Service responds
-Try connecting to the service from the VM itself. For example, `curl http://localhost:8080` for a
-web-service.
-
-On dev/test VMs, don't be afraid to install the utilities you need such as `curl`, `telnet`, `nc`,
-etc. Cloud VMs often have a very cut-down set of packages installed. For example, execute
-`sudo apt-get update; sudo apt-get install -y curl` or `sudo yum install -y curl`.
-
-### Listening on port
-Check that the service is listening on the port, and on the correct NIC(s).
-
-Execute `netstat -antp` (or on OS X `netstat -antp TCP`) to list the TCP ports in use (or use
-`-anup` for UDP). You should expect to see the something like the output below for a service.
-
-```
-Proto Recv-Q Send-Q Local Address Foreign Address State PID/Program name
-tcp 0 0 :::8080 :::* LISTEN 8276/java
-```
-
-In this case a Java process with pid 8276 is listening on port 8080. The local address `:::8080`
-format means all NICs (in IPv6 address format). You may also see `0.0.0.0:8080` for IPv4 format.
-If it says 127.0.0.1:8080 then your service will most likely not be reachable externally.
-
-Use `ip addr show` (or the obsolete `ifconfig -a`) to see the network interfaces on your server.
-
-For `netstat`, run with `sudo` to see the pid for all listed ports.
-
-## Firewalls
-On Linux, check if `iptables` is preventing the remote connection. On Windows, check the Windows Firewall.
-
-If it is acceptable (e.g. it is not a server in production), try turning off the firewall temporarily,
-and testing connectivity again. Remember to re-enable it afterwards! On CentOS, this is `sudo service
-iptables stop`. On Ubuntu, use `sudo ufw disable`. On Windows, press the Windows key and type 'Windows
-Firewall with Advanced Security' to open the firewall tools, then click 'Windows Firewall Properties'
-and set the firewall state to 'Off' in the Domain, Public and Private profiles.
-
-If you cannot temporarily turn off the firewall, then look carefully at the firewall settings. For
-example, execute `sudo iptables -n --list` and `iptables -t nat -n --list`.
-
-## Cloud firewalls
-Some clouds offer a firewall service, where ports need to be explicitly listed to be reachable.
-
-For example, [security groups for EC2-classic]
-(http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-network-security.html#ec2-classic-security-groups)
-have rules for the protocols and ports to be reachable from specific CIDRs.
-
-Check these settings via the cloud provider's web-console (or API).
-
-## Quick test of a listener port
-It can be useful to start listening on a given port, and to then check if that port is reachable.
-This is useful for testing basic connectivity when your service is not yet running, or to a
-different port to compare behaviour, or to compare with another VM in the network.
-
-The `nc` netcat tool is useful for this. For example, `nc -l 0.0.0.0 8080` will listen on port
-TCP 8080 on all network interfaces. On another server, you can then run `echo hello from client
-| nc <hostname> 8080`. If all works well, this will send "hello from client" over the TCP port 8080,
-which will be written out by the `nc -l` process before exiting.
-
-Similarly for UDP, you use `-lU`.
-
-You may first have to install `nc`, e.g. with `sudo yum install -y nc` or `sudo apt-get install netcat`.
-
-### Cloud load balancers
-For some use-cases, it is good practice to use the load balancer service offered by the cloud provider
-(e.g. [ELB in AWS](http://aws.amazon.com/elasticloadbalancing/) or the [Cloudstack Load Balancer]
-(http://docs.cloudstack.apache.org/projects/cloudstack-installation/en/latest/network_setup.html#management-server-load-balancing))
-
-The VMs can all be isolated within a private network, with access only through the load balancer service.
-
-Debugging techniques here include ensuring connectivity from another jump server within the private
-network, and careful checking of the load-balancer configuration from the Cloud Provider's web-console.
-
-### DNAT
-Use of DNAT is appropriate for some use-cases, where a particular port on a particular VM is to be
-made available.
-
-Debugging connectivity issues here is similar to the steps for a cloud load balancer. Ensure
-connectivity from another jump server within the private network. Carefully check the NAT rules from
-the Cloud Provider's web-console.
-
-### Guest wifi
-It is common for guest wifi to restrict access to only specific ports (e.g. 80 and 443, restricting
-ssh over port 22 etc).
-
-Normally your best bet is then to abandon the guest wifi (e.g. to tether to a mobile phone instead).
-
-There are some unconventional workarounds such as [configuring sshd to listen on port 80 so you can
-use an ssh tunnel](http://askubuntu.com/questions/107173/is-it-possible-to-ssh-through-port-80).
-However, the firewall may well inspect traffic so sending non-http traffic over port 80 may still fail.
-
-
+{% readj _connectivity.md %}
diff --git a/guide/ops/troubleshooting/deployment.md b/guide/ops/troubleshooting/deployment.md
index 38b6c5e..9e85dec 100644
--- a/guide/ops/troubleshooting/deployment.md
+++ b/guide/ops/troubleshooting/deployment.md
@@ -30,6 +30,11 @@
An error like `... Not authorized to access cloud ...` usually means the wrong identity/credential was used.
+AWS requires a X-Amz-Date header which contains the date of the Apache Brooklyn AWS client.
+If the date on the server is wrong, for example several minutes behind you will get Authorization Exception.
+Please be sure that the machine which is running Apache Brooklyn set its clock correctly.
+To set the time on Linux we advice to use the ntp client: `sudo ntpdate pool.ntp.org`.
+
An error like `Unable to match required VM template constraints` means that a matching image (e.g. AMI in AWS terminology) could not be found. This
could be because an incorrect explicit image id was supplied, or because the match-criteria could not
be satisfied using the given images available in the given cloud. The first time this error is
@@ -75,6 +80,58 @@
A very useful debug configuration is to set `destroyOnFailure` to false. This will allow ssh failures to
be more easily investigated.
+#### java.security.KeyException when Provisioning VM
+
+The exception `java.security.KeyException` can be thrown when jclouds is attempting the SSL handshake,
+to make cloud API calls. This can happen if the version of nss is older than 3.16 - the nss package
+includes the ssl library.
+
+To fix this on CentOS, run:
+
+{% highlight bash %}
+sudo yum upgrade nss
+{% endhighlight %}
+
+For a discussion of investigating this kind of issue, see this [Backslasher blog](http://blog.backslasher.net/java-ssl-crash.html).
+
+The full stacktrace is shown below:
+
+{% highlight java %}
+Caused by: javax.net.ssl.SSLException: java.security.ProviderException: java.security.KeyException
+ at sun.security.ssl.Alerts.getSSLException(Alerts.java:208)
+ at sun.security.ssl.SSLSocketImpl.fatal(SSLSocketImpl.java:1949)
+ at sun.security.ssl.SSLSocketImpl.fatal(SSLSocketImpl.java:1906)
+ at sun.security.ssl.SSLSocketImpl.handleException(SSLSocketImpl.java:1889)
+ at sun.security.ssl.SSLSocketImpl.startHandshake(SSLSocketImpl.java:1410)
+ at sun.security.ssl.SSLSocketImpl.startHandshake(SSLSocketImpl.java:1387)
+ at sun.net.www.protocol.https.HttpsClient.afterConnect(HttpsClient.java:559)
+ at sun.net.www.protocol.https.AbstractDelegateHttpsURLConnection.connect(AbstractDelegateHttpsURLConnection.java:185)
+ at sun.net.www.protocol.http.HttpURLConnection.getOutputStream0(HttpURLConnection.java:1283)
+ at sun.net.www.protocol.http.HttpURLConnection.getOutputStream(HttpURLConnection.java:1258)
+ at sun.net.www.protocol.https.HttpsURLConnectionImpl.getOutputStream(HttpsURLConnectionImpl.java:250)
+ at org.jclouds.http.internal.JavaUrlHttpCommandExecutorService.writePayloadToConnection(JavaUrlHttpCommandExecutorService.java:294)
+ at org.jclouds.http.internal.JavaUrlHttpCommandExecutorService.convert(JavaUrlHttpCommandExecutorService.java:170)
+ at org.jclouds.http.internal.JavaUrlHttpCommandExecutorService.convert(JavaUrlHttpCommandExecutorService.java:64)
+ at org.jclouds.http.internal.BaseHttpCommandExecutorService.invoke(BaseHttpCommandExecutorService.java:95)
+ ... 64 more
+Caused by: java.security.ProviderException: java.security.KeyException
+ at sun.security.ec.ECKeyPairGenerator.generateKeyPair(ECKeyPairGenerator.java:147)
+ at java.security.KeyPairGenerator$Delegate.generateKeyPair(KeyPairGenerator.java:703)
+ at sun.security.ssl.ECDHCrypt.<init>(ECDHCrypt.java:77)
+ at sun.security.ssl.ClientHandshaker.serverKeyExchange(ClientHandshaker.java:721)
+ at sun.security.ssl.ClientHandshaker.processMessage(ClientHandshaker.java:281)
+ at sun.security.ssl.Handshaker.processLoop(Handshaker.java:979)
+ at sun.security.ssl.Handshaker.process_record(Handshaker.java:914)
+ at sun.security.ssl.SSLSocketImpl.readRecord(SSLSocketImpl.java:1062)
+ at sun.security.ssl.SSLSocketImpl.performInitialHandshake(SSLSocketImpl.java:1375)
+ at sun.security.ssl.SSLSocketImpl.startHandshake(SSLSocketImpl.java:1403)
+ ... 74 more
+Caused by: java.security.KeyException
+ at sun.security.ec.ECKeyPairGenerator.generateECKeyPair(Native Method)
+ at sun.security.ec.ECKeyPairGenerator.generateKeyPair(ECKeyPairGenerator.java:128)
+ ... 83 more
+{% endhighlight %}
+
## Timeout Waiting For Service-Up
diff --git a/guide/ops/troubleshooting/detailed-support-report.md b/guide/ops/troubleshooting/detailed-support-report.md
new file mode 100644
index 0000000..c41ebcb
--- /dev/null
+++ b/guide/ops/troubleshooting/detailed-support-report.md
@@ -0,0 +1,43 @@
+---
+layout: website-normal
+title: Detailed Support Report
+toc: /guide/toc.json
+---
+
+If you wish to send a detailed report, then depending on the nature of the problem, consider
+collecting the following information.
+
+See [Brooklyn Slow or Unresponse](slow-unresponsive.html) docs for details of these commands.
+
+{% highlight bash %}
+BROOKLYN_HOME=/home/users/brooklyn/apache-brooklyn-0.9.0-bin
+BROOKLYN_PID=$(cat $BROOKLYN_HOME/pid_java)
+REPORT_DIR=/tmp/brooklyn-report/
+DEBUG_LOG=${BROOKLYN_HOME}/brooklyn.debug.log
+
+uname -a > ${REPORT_DIR}/uname.txt
+df -h > ${REPORT_DIR}/df.txt
+cat /proc/cpuinfo > ${REPORT_DIR}/cpuinfo.txt
+cat /proc/meminfo > ${REPORT_DIR}/meminfo.txt
+ulimit -a > ${REPORT_DIR}/ulimit.txt
+cat /proc/${BROOKLYN_PID}/limits >> ${REPORT_DIR}/ulimit.txt
+top -n 1 -b > ${REPORT_DIR}/top.txt
+lsof -p ${BROOKLYN_PID} > ${REPORT_DIR}/lsof.txt
+netstat -an > ${REPORT_DIR}/netstat.txt
+
+jmap -histo:live ${BROOKLYN_PID} > ${REPORT_DIR}/jmap-histo.txt
+jmap -heap ${BROOKLYN_PID} > ${REPORT_DIR}/jmap-heap.txt
+for i in {1..10}; do
+ jstack ${BROOKLYN_PID} > ${REPORT_DIR}/jstack.${i}.txt
+ sleep 1
+done
+grep "brooklyn gc" ${DEBUG_LOG} > ${REPORT_DIR}/brooklyn-gc.txt
+grep "events for subscriber" ${DEBUG_LOG} > ${REPORT_DIR}/events-for-subscriber.txt
+tar czf brooklyn-report.tgz ${REPORT_DIR}
+{% endhighlight %}
+
+Also consider providing your log files and persisted state, though extreme care should be taken if
+these might contain cloud or machine credentials (especially if
+[Externalised Configuration]({{ site.path.guide }}/ops/externalized-configuration.html)
+is not being used for credential storage).
+
diff --git a/guide/ops/troubleshooting/index.md b/guide/ops/troubleshooting/index.md
index ee8dfd7..bb3715c 100644
--- a/guide/ops/troubleshooting/index.md
+++ b/guide/ops/troubleshooting/index.md
@@ -5,6 +5,8 @@
- { path: overview.md, title: Overview }
- { path: deployment.md, title: Deployment }
- { path: connectivity.md, title: Server Connectivity }
+- { path: slow-unresponsive.md, title: Brooklyn Slow or Unresponsive }
+- { path: detailed-support-report.md, title: Detailed Support Report }
- { path: softwareprocess.md, title: SoftwareProcess Entities }
- { path: going-deep-in-java-and-logs.md, title: Going Deep in Java and Logs }
---
diff --git a/guide/ops/troubleshooting/slow-unresponsive.md b/guide/ops/troubleshooting/slow-unresponsive.md
new file mode 100644
index 0000000..6a8e6f9
--- /dev/null
+++ b/guide/ops/troubleshooting/slow-unresponsive.md
@@ -0,0 +1,237 @@
+---
+layout: website-normal
+title: Brooklyn Slow or Unresponsive
+toc: /guide/toc.json
+---
+
+There are many possible causes for a Brooklyn server becoming slow or unresponsive. This guide
+describes some possible reasons, and some commands and tools that can help diagnose the problem.
+
+Possible reasons include:
+
+* CPU is max'ed out
+* Memory usage is extremely high
+* SSH'ing is very slow due (e.g. due to lack of entropy)
+* Out of disk space
+
+See [Brooklyn Requirements]({{ site.path.guide }}/ops/requirements.html) for details of server
+requirements.
+
+
+## Machine Diagnostics
+
+The following commands will collect OS-level diagnostics about the machine, and about the AMP
+process. The commands below assume use of CentOS 6.x. Minor adjustments may be required for
+other platforms.
+
+
+#### OS and Machine Details
+
+To display system information, run:
+
+{% highlight bash %}
+uname -a
+{% endhighlight %}
+
+To show details of the CPU and memory available to the machine, run:
+
+{% highlight bash %}
+cat /proc/cpuinfo
+cat /proc/meminfo
+{% endhighlight %}
+
+
+#### User Limits
+
+To display information about user limits, run the command below (while logged in as the same user
+who runs Brooklyn):
+
+{% highlight bash %}
+ulimit -a
+{% endhighlight %}
+
+If Brooklyn is run as a different user (e.g. with user name "adalovelace"), then instead run:
+
+{% highlight bash %}
+ulimit -a -u adalovelace
+{% endhighlight %}
+
+Of particular interest is the limit for "open files".
+
+
+#### Disk Space
+
+The command below will list the disk size for each partition, including the amount used and
+available. If the AMP base directory, persistence directory or logging directory are close
+to 0% available, this can cause serious problems:
+
+{% highlight bash %}
+df -h
+{% endhighlight %}
+
+
+#### CPU and Memory Usage
+
+To view the CPU and memory usage of all processes, and of the machine as a whole, one can use the
+`top` command. This runs interactively, updating every few seconds. To collect the output once
+(e.g. to share diagnostic information in a bug report), run:
+
+{% highlight bash %}
+top -n 1 -b > top.txt
+{% endhighlight %}
+
+
+#### File and Network Usage
+
+To count the number of open files for the Brooklyn process (which includes open socket connections):
+
+{% highlight bash %}
+BROOKLYN_HOME=/home/users/brooklyn/apache-brooklyn-0.9.0-bin
+BROOKLYN_PID=$(cat $BROOKLYN_HOME/pid_java)
+lsof -p $BROOKLYN_PID | wc -l
+{% endhighlight %}
+
+To count (or view the number of "established" internet connections, run:
+
+{% highlight bash %}
+netstat -an | grep ESTABLISHED | wc -l
+{% endhighlight %}
+
+
+#### Linux Kernel Entropy
+
+A lack of entropy can cause random number generation to be extremely slow. This can cause
+tasks like ssh to also be extremely slow. See
+[linux kernel entropy]({{ site.path.website }}/documentation/increase-entropy.html)
+for details of how to work around this.
+
+
+## Process Diagnostics
+
+#### Thread and Memory Usage
+
+To get memory and thread usage for the Brooklyn (Java) process, two useful tools are `jstack`
+and `jmap`. These require the "development kit" to also be installed
+(e.g. `yum install java-1.7.0-openjdk-devel`). Some useful commands are shown below:
+
+{% highlight bash %}
+BROOKLYN_HOME=/home/users/brooklyn/apache-brooklyn-0.9.0-bin
+BROOKLYN_PID=$(cat $BROOKLYN_HOME/pid_java)
+
+jstack $BROOKLYN_PID
+jmap -histo:live $BROOKLYN_PID
+jmap -heap $BROOKLYN_PID
+{% endhighlight %}
+
+
+#### Runnable Threads
+
+The [jstack-active](https://github.com/apache/brooklyn-dist/blob/master/scripts/jstack-active.sh)
+script is a convenient light-weight way to quickly see which threads of a running Brooklyn
+server are attempting to consume the CPU. It filters the output of `jstack`, to show only the
+"really-runnable" threads (as opposed to those that are blocked).
+
+{% highlight bash %}
+BROOKLYN_HOME=/home/users/brooklyn/apache-brooklyn-0.9.0-bin
+BROOKLYN_PID=$(cat $BROOKLYN_HOME/pid_java)
+
+curl -O https://raw.githubusercontent.com/apache/brooklyn-dist/master/scripts/jstack-active.sh
+
+jstack-active $BROOKLYN_PID
+{% endhighlight %}
+
+
+#### Profiling
+
+If an in-depth investigation of the CPU usage (and/or object creation) of a Brooklyn Server is
+requiring, there are many profiling tools designed specifically for this purpose. These generally
+require that the process be launched in such a way that a profiler can attach, which may not be
+appropriate for a production server.
+
+
+#### Remote Debugging
+
+If the Brooklyn Server was originally run to allow a remote debugger to connect (strongly
+discouraged in production!), then this provides a convenient way to investigate why Brooklyn
+is being slow or unresonsive. See the Debugging Tips in the
+tip [Debugging Remote Brooklyn][({{ site.path.guide }}/dev/tips/debugging-remote-brooklyn.html)
+and the [IDE docs]({{ site.path.guide }}/dev/env/ide/) for more information.
+
+
+## Log Files
+
+Apache Brooklyn will by default create brooklyn.info.log and brooklyn.debug.log files. See the
+[Logging](({{ site.path.guide }}/ops/logging.html) docs for more information.
+
+The following are useful log messages to search for (e.g. using `grep`). Note the wording of
+these messages (or their very presence) may change in future version of Brooklyn.
+
+
+#### Normal Logging
+
+The lines below are commonly logged, and can be useful to search for when finding the start of a section of logging.
+
+{% highlight text %}
+2016-05-30 17:05:51,458 INFO o.a.b.l.BrooklynWebServer [main]: Started Brooklyn console at http://127.0.0.1:8081/, running classpath://brooklyn.war
+2016-05-30 17:06:04,098 INFO o.a.b.c.m.h.HighAvailabilityManagerImpl [main]: Management node tF3GPvQ5 running as HA MASTER autodetected
+2016-05-30 17:06:08,982 INFO o.a.b.c.m.r.InitialFullRebindIteration [brooklyn-execmanager-rvpnFTeL-0]: Rebinding from /home/compose/compose-amp-state/brooklyn-persisted-state/data for master rvpnFTeL...
+2016-05-30 17:06:11,105 INFO o.a.b.c.m.r.RebindIteration [brooklyn-execmanager-rvpnFTeL-0]: Rebind complete (MASTER) in 2s: 19 apps, 54 entities, 50 locations, 46 policies, 704 enrichers, 0 feeds, 160 catalog items
+{% endhighlight %}
+
+
+#### Memory Usage
+
+The debug log includes (every minute) a log statement about the memory usage and task activity. For example:
+
+{% highlight text %}
+2016-05-27 12:20:19,395 DEBUG o.a.b.c.m.i.BrooklynGarbageCollector [brooklyn-gc]: brooklyn gc (before) - using 328 MB / 496 MB memory (5.58 kB soft); 69 threads; storage: {datagrid={size=7, createCount=7}, refsMapSize=0, listsMapSize=0}; tasks: 10 active, 33 unfinished; 78 remembered, 1696906 total submitted)
+2016-05-27 12:20:19,395 DEBUG o.a.b.c.m.i.BrooklynGarbageCollector [brooklyn-gc]: brooklyn gc (after) - using 328 MB / 496 MB memory (5.58 kB soft); 69 threads; storage: {datagrid={size=7, createCount=7}, refsMapSize=0, listsMapSize=0}; tasks: 10 active, 33 unfinished; 78 remembered, 1696906 total submitted)
+{% endhighlight %}
+
+These can be extremely useful if investigating a memory or thread leak, or to determine whether a
+surprisingly high number of tasks are being executed.
+
+
+#### Subscriptions
+
+One source of high CPU in Brooklyn is when a subscription (e.g. for a policy or enricher) is being
+triggered many times (i.e. handling many events). A log message like that below will be logged on
+every 1000 events handled by a given single subscription.
+
+{% highlight text %}
+2016-05-30 17:29:09,125 DEBUG o.a.b.c.m.i.LocalSubscriptionManager [brooklyn-execmanager-rvpnFTeL-8]: 1000 events for subscriber Subscription[SCFnav9g;CanopyComposeApp{id=gIeTwhU2}@gIeTwhU2:webapp.url]
+{% endhighlight %}
+
+If a subscription is handling a huge number of events, there are a couple of common reasons:
+* first, it could be subscribing to too much activity - e.g. a wildcard subscription for all
+ events from all entities.
+* second it could be an infinite loop (e.g. where an enricher responds to a sensor-changed event
+ by setting that same sensor, thus triggering another sensor-changed event).
+
+
+#### User Activity
+
+All activity triggered by the REST API or web-console will be logged. Some examples are shown below:
+
+{% highlight text %}
+2016-05-19 17:52:30,150 INFO o.a.b.r.r.ApplicationResource [brooklyn-jetty-server-8081-qtp1058726153-17473]: Launched from YAML: name: My Example App
+location: aws-ec2:us-east-1
+services:
+- type: org.apache.brooklyn.entity.webapp.tomcat.TomcatServer
+
+2016-05-30 14:46:19,516 DEBUG brooklyn.REST [brooklyn-jetty-server-8081-qtp1104967201-20881]: Request Tisj14 starting: POST /v1/applications/NiBy0v8Q/entities/NiBy0v8Q/expunge from 77.70.102.66
+{% endhighlight %}
+
+
+#### Entity Activity
+
+If investigating the behaviour of a particular entity (e.g. on failure), it can be very useful to
+`grep` the info and debug log for the entity's id. For a software process, the debug log will
+include the stdout and stderr of all the commands executed by that entity.
+
+It can also be very useful to search for all effector invocations, to see where the behaviour
+has been triggered:
+
+{% highlight text %}
+2016-05-27 12:45:43,529 DEBUG o.a.b.c.m.i.EffectorUtils [brooklyn-execmanager-gvP7MuZF-14364]: Invoking effector stop on TomcatServerImpl{id=mPujYmPd}
+{% endhighlight %}
diff --git a/guide/start/running.md b/guide/start/running.md
index 3464023..1d5f81a 100644
--- a/guide/start/running.md
+++ b/guide/start/running.md
@@ -7,8 +7,6 @@
This guide will walk you through deploying an example 3-tier web application to a public cloud, and demonstrate the autoscaling capabilities of the Brooklyn platform.
-An overview of core [Brooklyn concepts](./concept-quickstart.html){:target="_blank"} is available for reference.
-
Two methods of deployment are detailed in this tutorial, using virtualisation with Vagrant and an install in your own environment (such as your local machine or in your private/public cloud).
The latter assumes that you have a [Java Runtime Environment (JRE)](https://www.java.com){:target="_blank"} installed (version 7 or later), as Brooklyn is Java under the covers.
@@ -22,8 +20,9 @@
<ul class="nav nav-tabs">
<li class="active impl-1-tab"><a data-target="#impl-1, .impl-1-tab" data-toggle="tab" href="#">Vagrant</a></li>
<li class="impl-2-tab"><a data-target="#impl-2, .impl-2-tab" data-toggle="tab" href="#">Centos / RHEL 7</a></li>
- <li class="impl-3-tab"><a data-target="#impl-3, .impl-3-tab" data-toggle="tab" href="#">OSX / Linux</a></li>
- <li class="impl-4-tab"><a data-target="#impl-4, .impl-4-tab" data-toggle="tab" href="#">Windows</a></li>
+ <li class="impl-3-tab"><a data-target="#impl-3, .impl-3-tab" data-toggle="tab" href="#">Ubuntu / Debian</a></li>
+ <li class="impl-4-tab"><a data-target="#impl-4, .impl-4-tab" data-toggle="tab" href="#">OSX / Linux</a></li>
+ <li class="impl-5-tab"><a data-target="#impl-5, .impl-5-tab" data-toggle="tab" href="#">Windows</a></li>
</ul>
<div class="tab-content">
@@ -38,9 +37,13 @@
* [Vagrant](https://www.vagrantup.com/downloads.html){:target="_blank"}
* [Oracle VirtualBox](https://www.virtualbox.org/wiki/Downloads){:target="_blank"}
-Then download the provided Apache Brooklyn vagrant configuration from [here](https://www.apache.org/dyn/closer.lua?action=download&filename=brooklyn/apache-brooklyn-{{site.brooklyn-version}}/apache-brooklyn-{{site.brooklyn-version}}-vagrant.tar.gz){:target="_blank"}. This archive contains everything you need to create an environment for use with this guide, providing an Apache Brooklyn instance and some blank VMs.
+Then download the provided Apache Brooklyn vagrant configuration from {% if site.brooklyn-version contains 'SNAPSHOT' %}
+from [here](https://repository.apache.org/service/local/artifact/maven/redirect?r=snapshots&g=org.apache.brooklyn&a=brooklyn-vagrant&v={{site.brooklyn-version}}&c=dist&e=zip){:target="_blank"}.
+{% else %}
+[here](https://www.apache.org/dyn/closer.lua?action=download&filename=brooklyn/apache-brooklyn-{{site.brooklyn-version}}/apache-brooklyn-{{site.brooklyn-version}}-vagrant.tar.gz){:target="_blank"}.
+{% endif %} This archive contains everything you need to create an environment for use with this guide, providing an Apache Brooklyn instance and some blank VMs.
-Extract the `tar.gz` archive and navigate into the expanded `apache-brooklyn-{{site.brooklyn-version}}-vagrant` folder
+Extract the `tar.gz` archive and navigate into the expanded `apache-brooklyn-{{site.brooklyn-version}}-vagrant` folder {% if site.brooklyn-version contains 'SNAPSHOT' %}(note: as this is a -SNAPSHOT version, your filename will be slightly different){% endif %}
{% highlight bash %}
$ tar xvf apache-brooklyn-{{site.brooklyn-version}}-vagrant.tar.gz
@@ -53,11 +56,17 @@
<strong class="hidden started-pdf-include">b) Centos / RHEL 7</strong>
+{% if site.brooklyn-version contains 'SNAPSHOT' %}<strong>Please note, an RPM is not available for snapshot builds</strong>{% endif %}
+
For Centos 7 and RHEL 7 users, the recommended way to install Apache Brooklyn on RPM-based Linux distributions is by using the RPM package.
RPM is the de facto standard for packaging software on these Linux distributions and provides a mechanism for installing, upgrading and removing packages such as Apache Brooklyn. The RPM package contains all the necessary files associated with the Apache Brooklyn application.
-Download the Apache Brooklyn [RPM distribution](https://www.apache.org/dyn/closer.lua/brooklyn/apache-brooklyn-{{site.brooklyn-version}}-1.noarch.rpm){:target="_blank"}.
+{% if site.brooklyn-version contains 'SNAPSHOT' %}
+This is a snapshot build and no RPM is available, please download [a different version]({{site.path.website}}/download/).
+{% else %}
+Download the Apache Brooklyn [RPM distribution](https://www.apache.org/dyn/closer.lua/brooklyn/apache-brooklyn-{{site.brooklyn-version}}/apache-brooklyn-{{site.brooklyn-version}}-1.noarch.rpm){:target="_blank"}.
+{% endif %}
Once downloaded, run the following shell command as root:
@@ -68,17 +77,38 @@
</div>
<div id="impl-3" class="tab-pane fade">
-<strong class="hidden started-pdf-include">c) OSX / Linux</strong>
+<strong class="hidden started-pdf-include">c) Debian / Ubuntu</strong>
+
+For Ubuntu and Debian users, the recommended way to install Apache Brooklyn is to use the deb file.
+
+The deb file is the de facto standard for packaging software on these Linux distributions and provides a mechanism for installing, upgrading and removing packages such as Apache Brooklyn. The deb package contains all the necessary files associated with the Apache Brooklyn application.
+
+{% if site.brooklyn-version contains 'SNAPSHOT' %}
+Download the Apache Brooklyn [deb distribution](https://repository.apache.org/service/local/artifact/maven/redirect?r=snapshots&g=org.apache.brooklyn&a=deb-packaging&v={{site.brooklyn-version}}&e=deb){:target="_blank"}.
+{% else %}
+Download the Apache Brooklyn [deb distribution](https://www.apache.org/dyn/closer.lua/brooklyn/apache-brooklyn_{{site.brooklyn-version}}_noarch.deb){:target="_blank"}.
+{% endif %}
+
+Once downloaded, run the following shell command:
+
+{% highlight bash %}
+$ sudo dpkg -i apache-brooklyn_{{site.brooklyn-version}}_noarch.deb
+{% endhighlight %}
+
+</div>
+<div id="impl-4" class="tab-pane fade">
+
+<strong class="hidden started-pdf-include">d) OSX / Linux</strong>
For Linux or OSX please download the Apache Brooklyn `tar.gz` archive from the [download]({{site.path.website}}/download/){:target="_blank"} section.
-{% if brooklyn_version contains 'SNAPSHOT' %}
+{% if site.brooklyn-version contains 'SNAPSHOT' %}
Extract the `tar.gz` archive (note: as this is a -SNAPSHOT version, your filename will be slightly different):
{% else %}
Extract the `tar.gz` archive and navigate into the expanded `apache-brooklyn-{{ site.brooklyn-version }}` folder.
{% endif %}
-{% if brooklyn_version contains 'SNAPSHOT' %}
+{% if site.brooklyn-version contains 'SNAPSHOT' %}
{% highlight bash %}
$ tar -zxf apache-brooklyn-dist-{{ site.brooklyn-version }}-timestamp-dist.tar.gz
$ cd apache-brooklyn-{{ site.brooklyn.version }}
@@ -91,9 +121,9 @@
{% endif %}
</div>
-<div id="impl-4" class="tab-pane fade">
+<div id="impl-5" class="tab-pane fade">
-<strong class="hidden started-pdf-include">d) Windows</strong>
+<strong class="hidden started-pdf-include">e) Windows</strong>
For all versions of Microsoft Windows, please download the Apache Brooklyn zip file from [here]({{site.path.website}}/download/){:target="_blank"}.
@@ -116,8 +146,9 @@
<ul class="nav nav-tabs">
<li class="active impl-1-tab"><a data-target="#impl-1, .impl-1-tab" data-toggle="tab" href="#">Vagrant</a></li>
<li class="impl-2-tab"><a data-target="#impl-2, .impl-2-tab" data-toggle="tab" href="#">Centos / RHEL</a></li>
- <li class="impl-3-tab"><a data-target="#impl-3, .impl-3-tab" data-toggle="tab" href="#">OSX / Linux</a></li>
- <li class="impl-4-tab"><a data-target="#impl-4, .impl-4-tab" data-toggle="tab" href="#">Windows</a></li>
+ <li class="impl-3-tab"><a data-target="#impl-3, .impl-3-tab" data-toggle="tab" href="#">Ubuntu / Debian</a></li>
+ <li class="impl-4-tab"><a data-target="#impl-4, .impl-4-tab" data-toggle="tab" href="#">OSX / Linux</a></li>
+ <li class="impl-5-tab"><a data-target="#impl-5, .impl-5-tab" data-toggle="tab" href="#">Windows</a></li>
</ul>
<div class="tab-content">
@@ -154,7 +185,20 @@
</div>
<div id="impl-3" class="tab-pane fade">
-<strong class="hidden started-pdf-include">c) OSX / Linux</strong>
+<strong class="hidden started-pdf-include">c) Ubuntu / Debian</strong>
+
+Apache Brooklyn should now have been installed and be running as a system service. It can stopped and started with the standard service commands:
+
+{% highlight bash %}
+$ sudo service brooklyn start|stop|restart|status
+{% endhighlight %}
+
+The application should then output its logs to `/var/log/brooklyn/apache-brooklyn.debug.log` and `/var/log/brooklyn/apache-brooklyn.info.log`.
+
+</div>
+<div id="impl-4" class="tab-pane fade">
+
+<strong class="hidden started-pdf-include">d) OSX / Linux</strong>
Now start Apache Brooklyn with the following command:
@@ -165,15 +209,17 @@
The application should then output its log into the console and also `apache-brooklyn.debug.log` and `apache-brooklyn.info.log`
</div>
-<div id="impl-4" class="tab-pane fade">
+<div id="impl-5" class="tab-pane fade">
-<strong class="hidden started-pdf-include">d) Windows</strong>
+<strong class="hidden started-pdf-include">e) Windows</strong>
You can now start Apache Brooklyn by running `c:\Program Files\brooklyn\bin\brooklyn.bat`
The application should then output its log into the console and also `c:\Program Files\brooklyn\apache-brooklyn.debug.log` and `c:\Program Files\brooklyn\apache-brooklyn.info.log`
</div>
+_Notice! Before launching Apache Brooklyn, please check the `date` on the local machine.
+Even several minutes before or after the actual time could cause problems._
</div>
---
@@ -187,10 +233,20 @@
INFO Started Brooklyn console at http://127.0.0.1:8081/, running classpath://brooklyn.war
</pre>
-By default it can be accessed by opening [127.0.0.1:8081](http://127.0.0.1:8081){:target="_blank"} in your web browser.
+By default it can be accessed by opening [127.0.0.1:8081](http://127.0.0.1:8081){:target="_blank"} in your web browser.
The rest of this getting started guide uses the Apache Brooklyn command line interface (CLI) tool, `br`.
-This tool is distributed along with Apache Brooklyn. See details on the [Client CLI Reference](../ops/cli/) page.
+This tool is both distributed with Apache Brooklyn or can be downloaded {% if site.brooklyn-version contains 'SNAPSHOT' %}
+from [here](https://repository.apache.org/service/local/artifact/maven/redirect?r=snapshots&g=org.apache.brooklyn&a=brooklyn-client-cli&v={{site.brooklyn-version}}&c=bin&e=zip).
+{% else %}
+using the most appropriate link for your OS:
+
+* [Windows](https://www.apache.org/dyn/closer.lua/brooklyn/apache-brooklyn-{{site.brooklyn-version}}/apache-brooklyn-{{site.brooklyn-version}}-client-cli-windows.zip)
+* [Linux](https://www.apache.org/dyn/closer.lua/brooklyn/apache-brooklyn-{{site.brooklyn-version}}/apache-brooklyn-{{site.brooklyn-version}}-client-cli-linux.tar.gz)
+* [OSX](https://www.apache.org/dyn/closer.lua/brooklyn/apache-brooklyn-{{site.brooklyn-version}}/apache-brooklyn-{{site.brooklyn-version}}-client-cli-macosx.tar.gz)
+{% endif %}
+
+For details on the CLI, see the [Client CLI Reference](../ops/cli/) page.
## Next
diff --git a/guide/yaml/advanced-example.md b/guide/yaml/advanced-example.md
index b66a3fb..e9aa617 100644
--- a/guide/yaml/advanced-example.md
+++ b/guide/yaml/advanced-example.md
@@ -160,7 +160,7 @@
- type: kibana-standalone
...
name: Kibana Server
- customize.latch: $brooklyn:component("es").attributeWhenReady("service.isUp")
+ customize.latch: $brooklyn:entity("es").attributeWhenReady("service.isUp")
~~~
This latch is used to stop Kibana customizing until the Elasticsearch cluster is up. We do this to ensure that the URL sensors have been setup, so that they can be passed into Kibana during the customization phase.
diff --git a/guide/yaml/ansible/creating-ansible-blueprints.md b/guide/yaml/ansible/creating-ansible-blueprints.md
index 1df1277..845f542 100644
--- a/guide/yaml/ansible/creating-ansible-blueprints.md
+++ b/guide/yaml/ansible/creating-ansible-blueprints.md
@@ -151,7 +151,7 @@
- command: unzip -o -d /etc/ansible/playbooks /tmp/master.zip
- serviceType: org.apache.brooklyn.entity.stock.BasicApplication
- start.latch: $brooklyn:component("bootstrap").attributeWhenReady("service.isUp")
+ start.latch: $brooklyn:entity("bootstrap").attributeWhenReady("service.isUp")
brooklyn.children:
- type: org.apache.brooklyn.entity.cm.ansible.AnsibleEntity
name: test
diff --git a/guide/yaml/ansible/index.md b/guide/yaml/ansible/index.md
index 1cda04e..a2376d1 100644
--- a/guide/yaml/ansible/index.md
+++ b/guide/yaml/ansible/index.md
@@ -7,7 +7,7 @@
---
This guide describes how Brooklyn entities can be created using the Ansible infrastructure management tool
- ([ansiblestack.com](ansiblestack.com)).
+ ([ansible.com](http://ansible.com)).
At present Brooklyn provides basic support for Ansible, operating in a 'masterless' mode.
Comments on this support and suggestions for further development are welcome.
diff --git a/guide/yaml/blueprinting-tips.md b/guide/yaml/blueprinting-tips.md
index 6f02746..bbca6f7 100644
--- a/guide/yaml/blueprinting-tips.md
+++ b/guide/yaml/blueprinting-tips.md
@@ -12,6 +12,19 @@
is very complicated.
+## Be Familiar with Brooklyn
+
+Be familiar with the stock entities available in Brooklyn. For example, prove you understand
+the concepts by making a deployment of a cluster of Tomcat servers before you begin writing your
+own blueprints.
+
+
+## Ask For Help
+
+Ask for help early. The community is keen to help, and also keen to find out what people find
+hard and how people use the product. Such feedback is invaluable for improving future versions.
+
+
## Faster Dev-Test
Writing a blueprint is most efficient and simple when testing is fast, and when testing is
@@ -22,7 +35,19 @@
Options for speeding up provisioning include those below.
-### Deploying to the "localhost" location
+#### Deploying to Bring Your Own Nodes (BYON)
+
+A [BYON location]({{ site.path.guide }}/ops/locations/#byon) can be defined, which avoids the time
+required to provision VMs. This is fast, but has the downside that artifacts installed during a
+previous run can interfere with subsequent runs.
+
+A variant of this is to [use Vagrant]({{ site.path.guide }}/start/running.html) (e.g. with VirtualBox)
+to create VMs on your local machine, and to use these as the target for a BYON location.
+
+These VMs should mirror the target environment as much as possible.
+
+
+#### Deploying to the "localhost" location
This is fast and simple, but has some obvious downsides:
@@ -33,47 +58,76 @@
* Some entities require `sudo` rights, which must be granted to the user running Brooklyn.
-### Deploying to Bring Your Own Nodes (BYON)
-
-A BYON location can be defined, which avoids the time required to provision VMs. This is fast,
-but has the downside that artifacts installed during a previous run can interfere with subsequent
-runs.
-
-A variant of this is to use Vagrant (e.g. with VirtualBox) to create VMs on your local machine,
-and to use these as the target for a BYON location.
-
-
-### Deploying to Clocker
+#### Deploying to Clocker
Docker containers provide a convenient way to test blueprints (and also to run blueprints in
production!).
-The [Clocker project](www.clocker.io) allows the simple setup of Docker Engine(s), and for Docker
+The [Clocker project](http://www.clocker.io) allows the simple setup of Docker Engine(s), and for Docker
containers to be used instead of VMs. For testing, this allows each run to start from a fresh
container (i.e. no install artifacts from previous runs), while taking advantage of the speed
of starting containers.
-### Caching Install Artifacts
+#### Local Repository of Install Artifacts
To avoid re-downloading install artifacts on every run, these can be saved to `~/.brooklyn/repository/`.
The file structure is a sub-directory with the entity's simple name, then a sub-directory with the
version number, and then the files to be downloaded. For example,
`~/.brooklyn/repository/TomcatServer/7.0.56/apache-tomcat-7.0.56.tar.gz`.
+If possible, synchronise this directory with your test VMs.
+
+
+#### Re-install on BYON
+
If using BYON or localhost, the install artifacts will by default be installed to a directory like
`/tmp/brooklyn-myname/installs/`. If install completed successfully, then the install stage will
-be subsequently skipped. To re-test the install phase, delete the install directory (e.g. delete
-`/tmp/brooklyn-myname/installs/TomcatServer_7.0.56/`).
+be subsequently skipped (a marker file being used to indicate completion). To re-test the install
+phase, delete the install directory (e.g. delete `/tmp/brooklyn-myname/installs/TomcatServer_7.0.56/`).
Where installation used something like `apt-get install` or `yum install`, then re-testing the
install phase will require uninstalling these artifacts manually.
+## Monitoring and Managing Applications
+
+Think about what it really means for an application to be running. The out-of-the-box default
+for a software process is the lowest common denominator: that the process is still running.
+Consider checking that the app responds over HTTP etc.
+
+If you have control of the app code, then consider adding an explicit health check URL that
+does more than basic connectivity tests. For example, can it reach the database, message broker,
+and other components that it will need for different operations.
+
+
+## Writing Composite Blueprints
+
+Write everything in discrete chunks that can be composed into larger pieces. Do not write a single
+mega-blueprint. For example, ensure each component is added to the catalog independently, along
+with a blueprint for the composite app.
+
+Experiment with lots of small blueprints to test independent areas before combining them into the
+real thing.
+
+
+## Writing Entity Tests
+
+Use the [test framework]({{ site.path.guide }}/yaml/test/) to write test cases. This will make
+automated (regression) testing easier, and will allow others to easily confirm that the entity
+works in their environment.
+
+If using Maven/Gradle then use the [Brooklyn Maven plugin](https://github.com/brooklyncentral/brooklyn-maven-plugin)
+to test blueprints at build time.
+
+
## Custom Entity Development
If writing a custom integration, the following recommendations may be useful:
+* Always be comfortable installing and running the process yourself before attempting to automate
+ it.
+
* For the software to be installed, use its Installation and Admin guides to ensure best practices
are being followed. Use blogs and advice from experts, when available.
@@ -98,8 +152,32 @@
For example, if deploying a MongoDB cluster then first focus on single-node MongoDB, and then make that
configurable and composable for a cluster.
-* Use the test framework to write test cases, so that others can run these to confirm that the
- entity works in their environment.
-
* Where appropriate, share the new entity with the Brooklyn community so that it can be reviewed,
tested and improved by others in the community!
+
+
+## Cloud Portability
+
+You get a lot of support out-of-the-box for deploying blueprints to different clouds. The points
+below may also be of help:
+
+* Test (and regression test) on each target cloud.
+
+* Be aware that images on different clouds can be very different. For example, two CentOS 6.6 VMs
+ might have different pre-installed libraries, different default iptables or SE Linux settings,
+ different repos, different sudo configuration, etc.
+
+* Different clouds handle private and public IPs differently. One must be careful about which
+ address to advertise to for use by other entities.
+
+* VMs on some clouds may not have a well-configured hostname (e.g. `ping $(hostname)` can fail).
+
+* VMs in different clouds have a different number of NICs. This is important when choosing whether
+ to listen on 0.0.0.0 or on a specific NIC.
+
+
+## Investigating Errors
+
+ALWAYS keep logs when there is an error.
+
+See the [Troubleshooting]({{ site.path.guide }}/ops/troubleshooting/) guide for more information.
diff --git a/guide/yaml/chef/example_yaml/mysql-chef-2.yaml b/guide/yaml/chef/example_yaml/mysql-chef-2.yaml
index ced2dbe..9e9de9b 100644
--- a/guide/yaml/chef/example_yaml/mysql-chef-2.yaml
+++ b/guide/yaml/chef/example_yaml/mysql-chef-2.yaml
@@ -13,9 +13,9 @@
launch_attributes:
mysql:
# these attrs are required by the mysql cookbook under node['mysql']
- server_root_password: $brooklyn:component("db").config("mysql.password")
- server_repl_password: $brooklyn:component("db").config("mysql.password")
- server_debian_password: $brooklyn:component("db").config("mysql.password")
+ server_root_password: $brooklyn:entity("db").config("mysql.password")
+ server_repl_password: $brooklyn:entity("db").config("mysql.password")
+ server_debian_password: $brooklyn:entity("db").config("mysql.password")
# many others are attrs are supported by the cookbook and can be passed here...
# how to determine if the process is running and how to kill it
diff --git a/guide/yaml/chef/writing-chef.md b/guide/yaml/chef/writing-chef.md
index 0593837..671d961 100644
--- a/guide/yaml/chef/writing-chef.md
+++ b/guide/yaml/chef/writing-chef.md
@@ -63,7 +63,7 @@
To help you on your way writing Chef blueprints, here are a handful of pointers
particularly useful in this context:
-* Configuration keys can be inherited from the top-level and accessed using `$brooklyn:component('id').config('key_name')`.
+* Configuration keys can be inherited from the top-level and accessed using `$brooklyn:entity('id').config('key_name')`.
An example of this is shown in the `mysql-chef.yaml` sample recipe contained in the Brooklyn code base
and [here](example_yaml/mysql-chef-2.yaml) for convenience.
Here, `p4ssw0rd` is specified only once and then used for all the attributes required by the stock mysql cookbook.
diff --git a/guide/yaml/configuring-vms.md b/guide/yaml/configuring-vms.md
index 97fb9d0..7ae341f 100644
--- a/guide/yaml/configuring-vms.md
+++ b/guide/yaml/configuring-vms.md
@@ -28,4 +28,4 @@
* `machineCreateAttempts` (for dodgy clouds, and they nearly all fail occasionally!)
* and things like `imageId` and `userMetadata` and disk and networking options (e.g. `autoAssignFloatingIp` for private clouds)
-For more information, see [Operations: Locations](../ops/locations/).
+For more information, see [Operations: Locations]({{ site.path.guide }}/ops/locations/index.html).
diff --git a/guide/yaml/creating-yaml.md b/guide/yaml/creating-yaml.md
index 34a0d29..603b0cd 100644
--- a/guide/yaml/creating-yaml.md
+++ b/guide/yaml/creating-yaml.md
@@ -25,7 +25,7 @@
* The `name` is just for the benefit of us humans.
* The `location` specifies where this should be deployed.
- If you've [set up passwordless localhost SSH access](../ops/locations/#localhost)
+ If you've [set up passwordless localhost SSH access]({{ site.path.guide }}/ops/locations/#localhost)
you can use `localhost` as above, but if not, just wait ten seconds for the next example.
* The `services` block takes a list of the typed services we want to deploy.
@@ -37,7 +37,7 @@
(usually [http://127.0.0.1:8081/](http://127.0.0.1:8081/), paste the copied YAML into the "Yaml" tab of the dialog and press "Finish".
There are several other ways to deploy, including `curl` and via the command-line,
and you can configure users, https, persistence, and more,
-as described [in the ops guide](../ops/).
+as described [in the ops guide]({{ site.path.guide }}/ops/).
[](web-console-yaml.png)
@@ -57,7 +57,7 @@
{% include list-children.html %}
Plenty of examples of blueprints exist in the Brooklyn codebase,
-so another starting point is to [`git clone`]({{ site.path.guide }}/dev/code/index.html) it
+so another starting point is to [`git clone`]({{ site.path.website }}/developers/code/index.html) it
and search for `*.yaml` files therein.
Brooklyn lived as a Java framework for many years before we felt confident
diff --git a/guide/yaml/custom-entities.md b/guide/yaml/custom-entities.md
index 9698aa8..bdaf6f4 100644
--- a/guide/yaml/custom-entities.md
+++ b/guide/yaml/custom-entities.md
@@ -75,6 +75,10 @@
irrespective of whether it matches the `inboundPorts.configRegex`.
To prevent any inferencing of ports to open, you can set the config `inboundPorts.autoInfer` to `false`.
+Furthermore, the port inferencing capability takes in account static `ConfigKey` fields that
+are defined on any Entity sub-class. So, `ConfigKey` fields that are based on `PortRanges` type will
+be also included as required open ports.
+
Note that in the example above, `netcat.port` must be specified in a `brooklyn.config` block.
This block can be used to hold any config (including for example the `launch.command`),
but for convenience Brooklyn allows config keys declared on the underlying type
@@ -201,7 +205,7 @@
`parameters` to pass in per-effector data:
env:
- TARGET_HOSTNAME: $brooklyn:component("netcat-server").attributeWhenReady("host.name")
+ TARGET_HOSTNAME: $brooklyn:entity("netcat-server").attributeWhenReady("host.name")
brooklyn.initializers:
- type: org.apache.brooklyn.core.effector.ssh.SshCommandEffector
brooklyn.config:
diff --git a/guide/yaml/entity-configuration.md b/guide/yaml/entity-configuration.md
new file mode 100644
index 0000000..538e2fe
--- /dev/null
+++ b/guide/yaml/entity-configuration.md
@@ -0,0 +1,305 @@
+---
+title: Entity Configuration
+layout: website-normal
+toc: ../guide_toc.json
+categories: [use, guide, defining-applications]
+---
+
+Within a blueprint or catalog item, entities can be configured. The rules for setting this
+configuration, including when composing and extending existing entities, is described in this
+section.
+
+
+### Basic Configuration
+
+Within a YAML file, entity configuration should be supplied within a `brooklyn.config` map. It is
+also possible to supply configuration at the top-level of the entity. However, that approach is
+discouraged as it can sometimes be ambiguous (e.g. if the config key is called "name" or "type"),
+and also it does not work in all contexts such as for an enricher's configuration.
+
+A simple example is shown below:
+
+{% highlight yaml %}
+services:
+- type: org.apache.brooklyn.entity.webapp.tomcat.TomcatServer
+ brooklyn.config:
+ webapp.enabledProtocols: http
+ http.port: 9080
+ wars.root: http://search.maven.org/remotecontent?filepath=org/apache/brooklyn/example/brooklyn-example-hello-world-webapp/0.9.0/brooklyn-example-hello-world-webapp-0.9.0.war
+{% endhighlight %}
+
+If no config value is supplied, the default for that config key will be used. For example,
+`http.port` would default to 8080 if not explicitly supplied.
+
+Some config keys also have a short-form (e.g. `httpPort` instead of `http.port` would also work
+in the YAML example above). However, that approach is discouraged as it does not work in all contexts
+such as for inheriting configuration from a parent entity.
+
+
+### Configuration in a Catalog Item
+
+When defining an entity in the catalog, it can include configuration values like any other
+blueprint. It can also explicitly declare config keys. For details of how to write and add
+catalog items, see [Catalog]({{ site.path.guide }}/ops/catalog/). For more details of
+declaring config keys, see the section ["Declaring New Config Keys" in Custom Entities](custom-entities.html).
+
+The example below illustrates the principles:
+
+{% highlight yaml %}
+brooklyn.catalog:
+ items:
+ - id: entity-config-example
+ itemType: entity
+ name: Entity Config Example
+ item:
+ type: org.apache.brooklyn.entity.software.base.VanillaSoftwareProcess
+ brooklyn.parameters:
+ - name: custom.message
+ type: string
+ default: Hello
+ brooklyn.config:
+ shell.env:
+ MESSAGE: $brooklyn:config("custom.message")
+ launch.command: |
+ echo "My example launch command: $MESSAGE"
+ checkRunning.command: |
+ echo "My example checkRunning command: $MESSAGE"
+{% endhighlight %}
+
+Once added to the catalog, it can be used with the simple blueprint below (substituting the location
+of your choice). Because no configuration has been overridden, this will use the default value
+for `custom.message`, and will use the given values for `launch.command` and `checkRunning.command`:
+
+{% highlight yaml %}
+location: aws-ec2:us-east-1
+services:
+- type: entity-config-example
+{% endhighlight %}
+
+
+### Inheriting Configuration from a Parent Entity
+
+Configuration passed to an entity is inherited by all child entities, unless explicitly overridden.
+This can simplify some blueprints, but also care should be taken to ensure default values are not
+accidentally overridden.
+
+In the example below, the `wars.root` config key is inherited by all TomcatServer entities created
+under the cluster, so they will use that war:
+
+{% highlight yaml %}
+services:
+- type: org.apache.brooklyn.entity.group.DynamicCluster
+ brooklyn.config:
+ wars.root: http://search.maven.org/remotecontent?filepath=org/apache/brooklyn/example/brooklyn-example-hello-world-webapp/0.9.0/brooklyn-example-hello-world-webapp-0.9.0.war
+ memberSpec:
+ $brooklyn:entitySpec:
+ type: org.apache.brooklyn.entity.webapp.tomcat.TomcatServer
+{% endhighlight %}
+
+
+### Inheriting Configuration from Super-type
+
+When using an entity from the catalog, its configuration values can be overridden. For example,
+consider the `entity-config-example` added to the catalog in the section "Configuration in a
+Catalog Item". We can override these values:
+
+{% highlight yaml %}
+location: aws-ec2:us-east-1
+services:
+- type: entity-config-example
+ brooklyn.config:
+ custom.message: Goodbye
+ launch.command: |
+ echo "Different example launch command: $MESSAGE"
+{% endhighlight %}
+
+If not overridden, then the existing values from the super-type will be used.
+
+
+### Configuration Precedence
+
+There are several places that a configuration value can come from. If different values are
+specified in multiple places, then the order of precedence is as listed below:
+
+1. Configuration on the entity itself
+2. Inherited configuration from the super-type
+3. Inherited configuration from the parent entity (or grandparent, etc)
+4. The config key's default value
+
+
+### Merging Configuration Values
+
+For some configuration values, the most logical behaviour is to merge the configuration value
+with that in the super-type. This depends on the type and meaning of the config key, and is thus
+an option when defining the config key.
+
+Currently it is only supported for merging config keys of type Map.
+
+Some common config keys will default to merging the values from the super-type. These config keys
+include those below. The value is merged with that of its super-type (but will not be merged with
+the value on a parent entity):
+
+* `shell.env`: a map of environment variables to pass to the runtime shell
+* `files.preinstall`: a mapping of files, to be copied before install, to destination name relative to installDir
+* `templates.preinstall`: a mapping of templates, to be filled in and copied before pre-install, to destination name relative to installDir
+* `files.install`: a mapping of files, to be copied before install, to destination name relative to installDir
+* `templates.install`: a mapping of templates, to be filled in and copied before install, to destination name relative to installDir
+* `files.runtime`: a mapping of files, to be copied before customisation, to destination name relative to runDir
+* `templates.runtime`: a mapping of templates, to be filled in and copied before customisation, to destination name relative to runDir
+* `provisioning.properties`: custom properties to be passed in when provisioning a new machine
+
+A simple example of merging `shell.env` is shown below (building on the `entity-config-example` in
+the previous section). The environment variables will include the `MESSAGE` set in the super-type
+and the `MESSAGE2` set here:
+
+{% highlight yaml %}
+location: aws-ec2:us-east-1
+services:
+- type: entity-config-example
+ brooklyn.config:
+ shell.env:
+ MESSAGE2: Goodbye
+ launch.command: |
+ echo "Different example launch command: $MESSAGE and $MESSAGE2"
+{% endhighlight %}
+
+To explicitly remove a value from the super-type's map (rather than adding to it), a blank entry
+can be defined.
+
+When defining a new config key, the exact semantics for inheritance can be defined. There are
+separate options for `inheritance.type` and `inheritance.parent` (the former determines how
+config inheritance from the super-type is handles; the latter determines how inheritance
+from the parent entity is handled. The possible values are:
+
+* `deep_merge`: the inherited and the given value should be merged; maps within the map will also be merged
+* `always`: the inherited value should be used, unless explicitly overridden by the entity
+* `none`: the value should not be inherited; if there is no explicit value on the entity then the default value will be used
+
+Below is a (contrived!) example of inheriting the `example.map` config key. When using this entity
+in a blueprint, the entity's config will be merged with that defined in the super-type, and the
+parent entity's value will never be inherited:
+
+{% highlight yaml %}
+brooklyn.catalog:
+ items:
+ - id: entity-config-example
+ version: "1.1.0-SNAPSHOT"
+ itemType: entity
+ name: Entity Config Example
+ item:
+ type: org.apache.brooklyn.entity.machine.MachineEntity
+ brooklyn.parameters:
+ - name: example.map
+ type: java.util.Map
+ inheritance.type: deep_merge
+ inheritance.parent: none
+ default:
+ MESSAGE_IN_DEFAULT: InDefault
+ brooklyn.config:
+ example.map:
+ MESSAGE: Hello
+{% endhighlight %}
+
+The blueprints below demonstrate the various permutations for setting configuration for the
+config `example.map`. This can be inspected by looking at the entity's config. The config
+we see for app1 is the inherited `{MESSAGE: "Hello"}`; in app2 we define additional configuration,
+which will be merged to give `{MESSAGE: "Hello", MESSAGE_IN_CHILD: "InChild"}`; in app3, the
+config from the parent is not inherited because there is an explicit inheritance.parent of "none",
+so it just has the value `{MESSAGE: "Hello"}`; in app4 again the parent's config is ignored,
+with the super-type and entity's config being merged to give `{MESSAGE: "Hello", MESSAGE_IN_CHILD: "InChild"}`.
+
+{% highlight yaml %}
+location: aws-ec2:us-east-1
+services:
+- type: org.apache.brooklyn.entity.stock.BasicApplication
+ name: app1
+ brooklyn.children:
+ - type: entity-config-example
+
+- type: org.apache.brooklyn.entity.stock.BasicApplication
+ name: app2
+ brooklyn.children:
+ - type: entity-config-example
+ brooklyn.config:
+ example.map:
+ MESSAGE_IN_CHILD: InChild
+
+- type: org.apache.brooklyn.entity.stock.BasicApplication
+ name: app3
+ brooklyn.config:
+ example.map:
+ MESSAGE_IN_PARENT: InParent
+ brooklyn.children:
+ - type: entity-config-example
+
+- type: org.apache.brooklyn.entity.stock.BasicApplication
+ name: app4
+ brooklyn.config:
+ example.map:
+ MESSAGE_IN_PARENT: InParent
+ brooklyn.children:
+ - type: entity-config-example
+ brooklyn.config:
+ example.map:
+ MESSAGE_IN_CHILD: InChild
+{% endhighlight %}
+
+A limitations of `inheritance.parent` is when inheriting values from parent and grandparent
+entities: a value specified on the parent will override (rather than be merged with) the
+value on the grandparent.
+
+
+### Entity provisioning.properties: Overriding and Merging
+
+An entity (which extends `SoftwareProcess`) can define a map of `provisioning.properties`. If
+the entity then provisions a location, it passes this map of properties to the location for
+obtaining the machine. These properties will override and augment the configuration on the location
+itself.
+
+When deploying to a jclouds location, one can specify `templateOptions` (of type map). Rather than
+overriding, these will be merged with any templateOptions defined on the location.
+
+In the example below, the VM will be provisioned with minimum 2G ram and minimum 2 cores. It will
+also use the merged template options value of
+`{placementGroup: myPlacementGroup, securityGroupIds: sg-000c3a6a}`:
+
+{% highlight yaml %}
+location:
+ aws-ec2:us-east-1:
+ minRam: 2G
+ templateOptions:
+ placementGroup: myPlacementGroup
+services:
+- type: org.apache.brooklyn.entity.machine.MachineEntity
+ brooklyn.config:
+ provisioning.properties:
+ minCores: 2
+ templateOptions:
+ securityGroupIds: sg-000c3a6a
+{% endhighlight %}
+
+The merging of `templateOptions` is shallow (i.e. maps within the `templateOptions` are not merged).
+In the example below, the `userMetadata` value within `templateOptions` will be overridden by the
+entity's value, rather than the maps being merged; the value used when provisioning will be
+`{key2: val2}`:
+
+{% highlight yaml %}
+location:
+ aws-ec2:us-east-1:
+ templateOptions:
+ userMetadata:
+ key1: val1
+services:
+- type: org.apache.brooklyn.entity.machine.MachineEntity
+ brooklyn.config:
+ provisioning.properties:
+ userMetadata:
+ key2: val2
+{% endhighlight %}
+
+
+
+### Merging Location, Policy and Enricher Configuration Values
+
+A current limitation is that `inheritance.type` is not supported for configuration of locations,
+policies and enrichers. The current behaviour is that config is not inherited.
diff --git a/guide/yaml/example_yaml/brooklyn-elasticsearch-catalog.bom b/guide/yaml/example_yaml/brooklyn-elasticsearch-catalog.bom
index bbed240..e069721 100644
--- a/guide/yaml/example_yaml/brooklyn-elasticsearch-catalog.bom
+++ b/guide/yaml/example_yaml/brooklyn-elasticsearch-catalog.bom
@@ -1,6 +1,7 @@
brooklyn.catalog:
id: elasticsearch
- version: 1.0
+ version: "1.0"
+ itemType: entity
iconUrl: https://avatars0.githubusercontent.com/u/6764390?v=3&s=400
name: Elasticsearch
license: Apache-2.0
diff --git a/guide/yaml/example_yaml/brooklyn-elk-catalog.bom b/guide/yaml/example_yaml/brooklyn-elk-catalog.bom
index 6fc11f4..f4a6efc 100644
--- a/guide/yaml/example_yaml/brooklyn-elk-catalog.bom
+++ b/guide/yaml/example_yaml/brooklyn-elk-catalog.bom
@@ -1,35 +1,34 @@
brooklyn.catalog:
- version: 1.0
+ id: ELK-Stack
+ version: "1.0"
+ itemType: template
iconUrl: https://avatars0.githubusercontent.com/u/6764390?v=3&s=400
license: Apache-2.0
issues_url: https://github.com/Graeme-Miller/brooklyn-elk/issues
- itemType: template
+ name: ELK Stack
+ description: |
+ Simple ELK stack deployment: provisions Elasticsearch, Kibana and Logtash as a child of Apache Tomcat 8
item:
- type: org.apache.brooklyn.entity.stock.BasicApplication
- name: ELK Stack
- id: ELK-Stack
- description: |
- Simple ELK stack deployment: provisions Elasticsearch, Kibana and Logtash as a child of Apache Tomcat 8
services:
- - type: elasticsearch
- id: es
- name: Elasticsearch Cluster
+ - type: elasticsearch
+ id: es
+ name: Elasticsearch Cluster
+ brooklyn.config:
+ install.version: 1.4.4
+ - type: kibana-standalone
+ id: kibana
+ name: Kibana Server
+ customize.latch: $brooklyn:entity("es").attributeWhenReady("service.isUp")
+ brooklyn.config:
+ kibana.elasticsearch.ip: $brooklyn:entity("es").attributeWhenReady("host.address.first")
+ kibana.elasticsearch.port: $brooklyn:entity("es").config("elasticsearch.http.port")
+ - type: org.apache.brooklyn.entity.webapp.tomcat.Tomcat8Server
+ id: tomcat
+ customize.latch: $brooklyn:entity("es").attributeWhenReady("service.isUp")
+ brooklyn.config:
+ children.startable.mode: background_late
+ brooklyn.children:
+ - type: logstash-child
+ name: Logstash Child
brooklyn.config:
- install.version: 1.4.4
- - type: kibana-standalone
- id: kibana
- name: Kibana Server
- customize.latch: $brooklyn:component("es").attributeWhenReady("service.isUp")
- brooklyn.config:
- kibana.elasticsearch.ip: $brooklyn:component("es").attributeWhenReady("host.address.first")
- kibana.elasticsearch.port: $brooklyn:component("es").config("elasticsearch.http.port")
- - type: org.apache.brooklyn.entity.webapp.tomcat.Tomcat8Server
- id: tomcat
- customize.latch: $brooklyn:component("es").attributeWhenReady("service.isUp")
- brooklyn.config:
- children.startable.mode: background_late
- brooklyn.children:
- - type: logstash-child
- name: Logstash Child
- brooklyn.config:
- logstash.elasticsearch.host: $brooklyn:component("es").attributeWhenReady("urls.http.withBrackets")
+ logstash.elasticsearch.host: $brooklyn:entity("es").attributeWhenReady("urls.http.withBrackets")
diff --git a/guide/yaml/example_yaml/brooklyn-kibana-catalog.bom b/guide/yaml/example_yaml/brooklyn-kibana-catalog.bom
index ee006d2..90eda9e 100644
--- a/guide/yaml/example_yaml/brooklyn-kibana-catalog.bom
+++ b/guide/yaml/example_yaml/brooklyn-kibana-catalog.bom
@@ -1,8 +1,9 @@
brooklyn.catalog:
- version: 0.0.2
+ version: "0.0.2"
iconUrl: http://blog.arungupta.me/wp-content/uploads/2015/07/kibana-logo.png
items:
- id: kibana-standalone
+ itemType: entity
name: "Kibana server"
description: "Single Kibana server"
description: |
diff --git a/guide/yaml/example_yaml/brooklyn-logstash-catalog.bom b/guide/yaml/example_yaml/brooklyn-logstash-catalog.bom
index 7c431f5..5285e2b 100644
--- a/guide/yaml/example_yaml/brooklyn-logstash-catalog.bom
+++ b/guide/yaml/example_yaml/brooklyn-logstash-catalog.bom
@@ -1,8 +1,9 @@
brooklyn.catalog:
- version: 1.5.5
+ version: "1.5.5"
iconUrl: http://logstash.net/images/logstash.png
items:
- id: logstash-standalone
+ itemType: entity
name: "Logstash server"
description: "Single Logstash server"
item:
@@ -45,6 +46,7 @@
nohup /opt/logstash/logstash-${VERSION}/bin/logstash agent -f ${CONFIG_DIR} -l /var/log/logstash/logstash.log &
echo $! > $PID_FILE
- id: logstash-child
+ itemType: entity
name: "Logstash Child"
description: |
Logstash server to be embedded as a child of a SoftwareProcess who
diff --git a/guide/yaml/example_yaml/vanilla-bash-netcat-catalog.bom b/guide/yaml/example_yaml/vanilla-bash-netcat-catalog.bom
index 7551818..6416ab7 100644
--- a/guide/yaml/example_yaml/vanilla-bash-netcat-catalog.bom
+++ b/guide/yaml/example_yaml/vanilla-bash-netcat-catalog.bom
@@ -1,6 +1,7 @@
brooklyn.catalog:
id: netcat-example
version: "1.0"
+ itemType: entity
item:
type: org.apache.brooklyn.entity.software.base.VanillaSoftwareProcess
name: Simple Netcat Server
diff --git a/guide/yaml/example_yaml/vanilla-bash-netcat-w-client.yaml b/guide/yaml/example_yaml/vanilla-bash-netcat-w-client.yaml
index 78ed99e..75d2b79 100644
--- a/guide/yaml/example_yaml/vanilla-bash-netcat-w-client.yaml
+++ b/guide/yaml/example_yaml/vanilla-bash-netcat-w-client.yaml
@@ -48,7 +48,7 @@
# set the hostname of the netcat instance as an env var for the scripts
env:
TARGET_HOSTNAME:
- $brooklyn:component("netcat-server").
+ $brooklyn:entity("netcat-server").
attributeWhenReady("host.name")
# start/check/stop are no-op
@@ -74,5 +74,5 @@
brooklyn.enrichers:
- enricherType: org.apache.brooklyn.enricher.stock.Propagator
brooklyn.config:
- enricher.producer: $brooklyn:component("netcat-server")
+ enricher.producer: $brooklyn:entity("netcat-server")
enricher.propagating.propagatingAll: true
diff --git a/guide/yaml/index.md b/guide/yaml/index.md
index 43d3b25..def24c1 100644
--- a/guide/yaml/index.md
+++ b/guide/yaml/index.md
@@ -7,6 +7,7 @@
- configuring-vms.md
- clusters.md
- multiple-services.md
+- entity-configuration.md
- clusters-and-policies.md
- blueprinting-tips.md
- custom-entities.md
diff --git a/guide/yaml/salt/index.md b/guide/yaml/salt/index.md
index 2992b52..265e07f 100644
--- a/guide/yaml/salt/index.md
+++ b/guide/yaml/salt/index.md
@@ -7,7 +7,7 @@
---
This guide describes how Brooklyn entities can be created using the Salt infrastructure management tool
- ([saltstack.com](saltstack.com)).
+ ([saltstack.com](https://saltstack.com/)).
At present Brooklyn provides basic support for Salt, operating in a 'masterless' mode.
Comments on this support and suggestions for further development are welcome.
diff --git a/guide/yaml/test/example_yaml/entities/loopovergroupmembers-entity.yaml b/guide/yaml/test/example_yaml/entities/loopovergroupmembers-entity.yaml
index e97ab4c..713ffbc 100644
--- a/guide/yaml/test/example_yaml/entities/loopovergroupmembers-entity.yaml
+++ b/guide/yaml/test/example_yaml/entities/loopovergroupmembers-entity.yaml
@@ -1,5 +1,5 @@
- type: org.apache.brooklyn.test.framework.LoopOverGroupMembersTestCase
- target: $brooklyn:component("infrastructure").component("child", "DockerHosts")
+ target: $brooklyn:entity("infrastructure").component("child", "DockerHosts")
testSpec:
$brooklyn:entitySpec:
type: org.apache.brooklyn.test.framework.TestSensor
diff --git a/guide/yaml/test/example_yaml/entities/testeffector-entity.yaml b/guide/yaml/test/example_yaml/entities/testeffector-entity.yaml
index 13e0ebf..e9d570e 100644
--- a/guide/yaml/test/example_yaml/entities/testeffector-entity.yaml
+++ b/guide/yaml/test/example_yaml/entities/testeffector-entity.yaml
@@ -1,6 +1,6 @@
- type: org.apache.brooklyn.test.framework.TestEffector
name: Invoke Deploy Effector
- target: $brooklyn:component("tomcat")
+ target: $brooklyn:entity("tomcat")
effector: deploy
timeout: 5m
params:
diff --git a/guide/yaml/test/example_yaml/entities/testhttpcall-entity.yaml b/guide/yaml/test/example_yaml/entities/testhttpcall-entity.yaml
index bdb3347..e719b82 100644
--- a/guide/yaml/test/example_yaml/entities/testhttpcall-entity.yaml
+++ b/guide/yaml/test/example_yaml/entities/testhttpcall-entity.yaml
@@ -1,6 +1,6 @@
- type: org.apache.brooklyn.test.framework.TestHttpCall
name: Check HTTP Response Status Code
- url: $brooklyn:component("tomcat").attributeWhenReady("webapp.url")
+ url: $brooklyn:entity("tomcat").attributeWhenReady("webapp.url")
timeout: 60s
applyAssertionTo: status
assert:
diff --git a/guide/yaml/test/example_yaml/entities/testsensor-entity.yaml b/guide/yaml/test/example_yaml/entities/testsensor-entity.yaml
index e781d0d..91f55a5 100644
--- a/guide/yaml/test/example_yaml/entities/testsensor-entity.yaml
+++ b/guide/yaml/test/example_yaml/entities/testsensor-entity.yaml
@@ -1,6 +1,6 @@
- type: org.apache.brooklyn.test.framework.TestSensor
name: Check tomcat isUp
- target: $brooklyn:component("tomcat")
+ target: $brooklyn:entity("tomcat")
sensor: service.isUp
timeout: 10m
assert:
diff --git a/guide/yaml/test/example_yaml/entities/simpleshellcommandtest-entity.yaml b/guide/yaml/test/example_yaml/entities/testsshcommand-entity.yaml
similarity index 67%
rename from guide/yaml/test/example_yaml/entities/simpleshellcommandtest-entity.yaml
rename to guide/yaml/test/example_yaml/entities/testsshcommand-entity.yaml
index 09b8339..6bbffc0 100644
--- a/guide/yaml/test/example_yaml/entities/simpleshellcommandtest-entity.yaml
+++ b/guide/yaml/test/example_yaml/entities/testsshcommand-entity.yaml
@@ -1,11 +1,13 @@
+services:
- type: org.apache.brooklyn.test.framework.TestCase
name: testcase1
- targetId: testprocess
brooklyn.children:
- type: org.apache.brooklyn.entity.webapp.tomcat.TomcatServer
id: testprocess
- - type: org.apache.brooklyn.test.framework.SimpleShellCommandTest
+ - type: org.apache.brooklyn.test.framework.TestSshCommand
+ name: Check tomcat process running with ps
+ targetId: testprocess
command: ps -ef
assertStatus:
equals: 0
@@ -14,7 +16,9 @@
assertErr:
isEmpty: true
- - type: org.apache.brooklyn.test.framework.SimpleShellCommandTest
+ - type: org.apache.brooklyn.test.framework.TestSshCommand
+ name: Check hello world script
+ targetId: testprocess
downloadUrl: https://github.com/apache/brooklyn-docs/raw/master/guide/yaml/test/example_yaml/entities/script1.sh
assertStatus:
equals: 0
diff --git a/guide/yaml/test/example_yaml/testcases/effector-test-snippet.yaml b/guide/yaml/test/example_yaml/testcases/effector-test-snippet.yaml
index 54e30da..2e01ba5 100644
--- a/guide/yaml/test/example_yaml/testcases/effector-test-snippet.yaml
+++ b/guide/yaml/test/example_yaml/testcases/effector-test-snippet.yaml
@@ -21,8 +21,8 @@
timeout: 5m
url: >
$brooklyn:formatString("http://%s:%s/newcontext/",
- $brooklyn:component("webappcluster").attributeWhenReady("host.address"),
- $brooklyn:component("webappcluster").attributeWhenReady("proxy.http.port"))
+ $brooklyn:entity("webappcluster").attributeWhenReady("host.address"),
+ $brooklyn:entity("webappcluster").attributeWhenReady("proxy.http.port"))
applyAssertionTo: status
assert:
- isEqualTo: 200
\ No newline at end of file
diff --git a/guide/yaml/test/example_yaml/testcases/getting-started-test-example.yaml b/guide/yaml/test/example_yaml/testcases/getting-started-test-example.yaml
index 5f40abb..d6740ec 100644
--- a/guide/yaml/test/example_yaml/testcases/getting-started-test-example.yaml
+++ b/guide/yaml/test/example_yaml/testcases/getting-started-test-example.yaml
@@ -14,7 +14,7 @@
java.sysprops:
brooklyn.example.db.url: >
$brooklyn:formatString("jdbc:%s%s?user=%s&password=%s",
- component("db").attributeWhenReady("datastore.url"),
+ entity("db").attributeWhenReady("datastore.url"),
"visitors", "brooklyn", "br00k11n")
- type: org.apache.brooklyn.entity.database.mysql.MySqlNode
id: db
@@ -25,8 +25,8 @@
name: Check HTTP Response Status Code
url: >
$brooklyn:formatString("http://%s:%s",
- $brooklyn:component("webappcluster").attributeWhenReady("host.address"),
- $brooklyn:component("webappcluster").attributeWhenReady("proxy.http.port"))
+ $brooklyn:entity("webappcluster").attributeWhenReady("host.address"),
+ $brooklyn:entity("webappcluster").attributeWhenReady("proxy.http.port"))
timeout: 10m
applyAssertionTo: status
assert:
@@ -35,8 +35,8 @@
name: Check HTTP Response Body
url: >
$brooklyn:formatString("http://%s:%s",
- $brooklyn:component("webappcluster").attributeWhenReady("host.address"),
- $brooklyn:component("webappcluster").attributeWhenReady("proxy.http.port"))
+ $brooklyn:entity("webappcluster").attributeWhenReady("host.address"),
+ $brooklyn:entity("webappcluster").attributeWhenReady("proxy.http.port"))
timeout: 10m
applyAssertionTo: body
assert:
@@ -64,8 +64,8 @@
timeout: 5m
url: >
$brooklyn:formatString("http://%s:%s/newcontext/",
- $brooklyn:component("webappcluster").attributeWhenReady("host.address"),
- $brooklyn:component("webappcluster").attributeWhenReady("proxy.http.port"))
+ $brooklyn:entity("webappcluster").attributeWhenReady("host.address"),
+ $brooklyn:entity("webappcluster").attributeWhenReady("proxy.http.port"))
applyAssertionTo: status
assert:
- isEqualTo: 200
\ No newline at end of file
diff --git a/guide/yaml/test/index.md b/guide/yaml/test/index.md
index 02482b7..856cc73 100644
--- a/guide/yaml/test/index.md
+++ b/guide/yaml/test/index.md
@@ -20,7 +20,7 @@
- `TestSensor` - perform assertion on a specified sensor.
- `TestEffector` - perform assertion on response to effector call.
- `TestHttpCall` - perform assertion on response to specified HTTP GET Request.
-- `SimpleShellCommandTest` - test assertions on the result of a shell command on the same node as the target entity.
+- `TestSshCommand` - test assertions on the result of an ssh command on the same machine as the target entity.
TargetableTestComponents can be chained together, with the target being inherited by the components children. For example, a ParallelTestCase could be created that has a TestHttpCall as a child. As long as the TestHttpCall itself does not have a target, it will use the target of it's parent, ParallelTestCase. Using this technique, we can build up complex test scenarios.
diff --git a/guide/yaml/test/test-entities.md b/guide/yaml/test/test-entities.md
index cb435b8..6f5ff02 100644
--- a/guide/yaml/test/test-entities.md
+++ b/guide/yaml/test/test-entities.md
@@ -22,6 +22,7 @@
The `ParallelTestCase` entity can be added as a child to run a subset of entities in parallel as a single step.
+
### ParallelTestCase
The `ParallelTestCase` entity acts as a container for a list of child entities which are started in *parallel*.
@@ -33,6 +34,7 @@
Timeouts on child entities should be set relative to the start of the `ParallelTestCase`.
+
### LoopOverGroupMembersTestCase
The `LoopOverGroupMembersTestCase` entity is configured with a target group and a test specification. For each member of the targeted group, the test case will create a TargetableTestComponent entity from the supplied test specification and set the components target to be the group member.
@@ -41,7 +43,7 @@
{% endhighlight %}
#### Parameters
-- `target` - group who's members are to be tested, specified via DSL. For example, `$brooklyn:component("tomcat")`. See also the `targetId` parameter.
+- `target` - group who's members are to be tested, specified via DSL. For example, `$brooklyn:entity("tomcat")`. See also the `targetId` parameter.
- `targetId` - alternative to the `target` parameter which wraps the DSL component lookup requiring only the `id` be supplied. For example, `tomcat`. Please note, this must point to a group.
- `test.spec` - The TargetableTestComponent to create for each child.
@@ -59,6 +61,7 @@
- `infrastructure.deployment.entity.specs` - the entities to be deployed to the infrastructure
- `infrastructure.deployment.location.sensor` - the name of the sensor on the infrastructure to retrieve the deployment location
+
## Validation Test Entities
### TestSensor
@@ -69,12 +72,19 @@
{% endhighlight %}
#### Parameters
-- `target` - entity whose sensor will be tested, specified via DSL. For example, `$brooklyn:component("tomcat")`. See also the `targetId` parameter.
+- `target` - entity whose sensor will be tested, specified via DSL. For example, `$brooklyn:entity("tomcat")`. See also the `targetId` parameter.
- `targetId` - alternative to the `target` parameter which wraps the DSL component lookup requiring only the `id` be supplied. For example, `tomcat`.
- `sensor` - sensor to evaluate. For example `service.isUp`.
- `timeout` - duration to wait on assertion to return a result. For example `10s`, `10m`, etc
- `assert` - assertion to perform on the specified sensor value. See section on assertions below.
+<div class="alert alert-info">
+ <strong>Tip:</strong> If the <code>TestSensor</code> is wrapped within a <code>TestCase</code>,
+ <code>ParallelTestCase</code> or <code>LoopOverGroupMembersTestCase</code> that set the target,
+ <strong>you don't need to specify the target</strong>, unless you want to test a different entity.
+</div>
+
+
### TestEffector
The `TestEffector` entity invokes the specified effector on a target entity. If the result of the effector is a String, it will then perform assertions on the result.
{% highlight yaml %}
@@ -82,13 +92,20 @@
{% endhighlight %}
#### Parameters
-- `target` - entity whose effector will be invoked, specified via DSL. For example, `$brooklyn:component("tomcat")`. See also the `targetId` parameter.
+- `target` - entity whose effector will be invoked, specified via DSL. For example, `$brooklyn:entity("tomcat")`. See also the `targetId` parameter.
- `targetId` - alternative to the `target` parameter which wraps the DSL component lookup requiring only the `id` be supplied. For example, `tomcat`.
- `timeout` - duration to wait on the effector task to complete. For example `10s`, `10m`, etc
- `effector` - effector to invoke, for example `deploy`.
- `params` - parameters to pass to the effector, these will depend on the entity and effector being tested. The example above shows the `url` and `targetName` parameters being passed to Tomcats `deploy` effector.
- `assert` - assertion to perform on the returned result. See section on assertions below.
+<div class="alert alert-info">
+ <strong>Tip:</strong> If the <code>TestEffector</code> is wrapped within a <code>TestCase</code>,
+ <code>ParallelTestCase</code> or <code>LoopOverGroupMembersTestCase</code> that set the target,
+ <strong>you don't need to specify the target</strong>, unless you want to test a different entity.
+</div>
+
+
### TestHttpCall
The `TestHttpCall` entity performs a HTTP GET on the specified URL and performs an assertion on the response.
{% highlight yaml %}
@@ -96,33 +113,47 @@
{% endhighlight %}
#### Parameters
-- `url` - URL to perform GET request on, this can use DSL for example `$brooklyn:component("tomcat").attributeWhenReady("webapp.url")`.
+- `url` - URL to perform GET request on, this can use DSL for example `$brooklyn:entity("tomcat").attributeWhenReady("webapp.url")`.
- `timeout` - duration to wait on a HTTP response. For example `10s`, `10m`, etc
- `applyAssertionTo` - The filed to apply the assertion to. For example `status`, `body`
- `assert` - assertion to perform on the response. See section on assertions below.
-### SimpleShellCommandTest
+<div class="alert alert-info">
+ <strong>Tip:</strong> If the <code>TestHttpCall</code> is wrapped within a <code>TestCase</code>,
+ <code>ParallelTestCase</code> or <code>LoopOverGroupMembersTestCase</code> that set the target,
+ <strong>you don't need to specify the target</strong>, unless you want to test a different entity.
+</div>
-The SimpleShellCommandTest runs a command on the host of the target entity.
+
+### TestSshCommand
+The TestSshCommand runs a command on the host of the target entity.
The script is expected not to run indefinitely, but to return a result (process exit code), along with its
standard out and error streams, which can then be tested using assertions.
If no assertions are explicitly configured, the default is to assert a non-zero exit code.
-Either a shell command may be provided in the YAML, or a URL for a script which will be executed.
+Either a bash command may be provided in the YAML, or a URL for a script which will be executed.
{% highlight yaml %}
-{% readj example_yaml/entities/simpleshellcommandtest-entity.yaml %}
+{% readj example_yaml/entities/testsshcommand-entity.yaml %}
{% endhighlight %}
#### Parameters
- `command` - The shell command to execute. (This and `downloadUrl` are mutually exclusive.)
- `downloadUrl` - URL for a script to download and execute. (This and `command` are mutually exclusive.)
+- `shell.env` - Map of environment variables to be set.
- `scriptDir` - if `downloadUrl` is used. The directory on the target host where downloaded scripts should be copied to.
- `runDir` - the working directory where the command or script will be executed on the target host.
- `assertStatus` - Assertions on the exit code of the command or script. See section on assertions below.
- `assertOut` - Assertions on the standard output of the command as a String.
- `assertErr` - Assertions on the standard error of the command as a String.
+<div class="alert alert-info">
+ <strong>Tip:</strong> If the <code>TestSshCommand</code> is wrapped within a <code>TestCase</code>,
+ <code>ParallelTestCase</code> or <code>LoopOverGroupMembersTestCase</code> that set the target,
+ <strong>you don't need to specify the target</strong>, unless you want to test a different entity.
+</div>
+
+
## Assertions
The following conditions are provided by those test entities above that include assertions
@@ -141,17 +172,14 @@
Assertions may be provided as a simple map:
-```yaml
- assert:
- contains: 2 users
- matches: .*[\d]* days.*
-```
+ assert:
+ contains: 2 users
+ matches: .*[\d]* days.*
+
If there is the need to make multiple assertions with the same key, the assertions can be specified
as a list of such maps:
-```yaml
- assert:
- - contains: 2 users
- - contains: 2 days
-```
+ assert:
+ - contains: 2 users
+ - contains: 2 days
diff --git a/guide/yaml/test/usage-examples.md b/guide/yaml/test/usage-examples.md
index 086d1fb..08d88e3 100644
--- a/guide/yaml/test/usage-examples.md
+++ b/guide/yaml/test/usage-examples.md
@@ -7,10 +7,10 @@
{% include fields.md %}
## Introduction
-This section describes some simple tests based on the [Getting Started](../../start/blueprints.html#launching-from-a-blueprint) example blueprint:
+This section describes some simple tests based on the [Getting Started]({{ site.path.guide }}/start/blueprints.html#launching-from-a-blueprint) example blueprint:
{% highlight yaml %}
-{% readj ../../start/_my-web-cluster.yaml %}
+{% readj /guide/start/_my-web-cluster.yaml %}
{% endhighlight %}
The following sections contain yaml snippets that be appended to the list of services in the blueprint above, a complete blueprint is also provided [below](#full-example).
@@ -53,6 +53,6 @@
### Full Example
A sample blueprint containing all the tests described above is available [here](./example_yaml/testcases/getting-started-test-example.yaml).
-This blueprint will deploy the [Getting Started](../../start/blueprints.html#launching-from-a-blueprint) application and run all of the test entities, which if successful should appear in the web console as follows.
+This blueprint will deploy the [Getting Started]({{ site.path.guide }}/start/blueprints.html#launching-from-a-blueprint) application and run all of the test entities, which if successful should appear in the web console as follows.
[](images/getting-started-blueprint-test-large.png)
diff --git a/guide/yaml/winrm/index.md b/guide/yaml/winrm/index.md
index 56a66a3..2e5b536 100644
--- a/guide/yaml/winrm/index.md
+++ b/guide/yaml/winrm/index.md
@@ -271,6 +271,9 @@
installation commands can be split between the pre-install, install and post-install phases
in order to do a reboot at the appropriate point of the VM setup.
+We Strongly recommend to **write blueprints in a way that they do NOT restart automatically windows** and
+use one of the `pre.install.reboot.required` or `install.reboot.required` parameters to perform restart.
+
### Install Location
Blueprint authors are encouraged to explicitly specify the full path for file uploads, and
@@ -421,6 +424,53 @@
refer to [How and Why to re-authenticate withing a powershell script](#how-and-why-to-re-authenticate-within-a-powershell-script)
above.
+### WebServiceException: Could not send Message
+
+We detected a `WebServiceException` and different `SocketException`
+during deployment of long lasting Application Blueprint against VcloudDirector.
+
+Launching the blueprint bellow was giving constantly this type of error on launch step.
+
+ services:
+ type: org.apache.brooklyn.entity.software.base.VanillaWindowsProcess
+ brooklyn.config:
+ pre.install.command: echo preInstallCommand
+ install.command: echo installCommand > C:\\install.txt
+ post.install.command: echo postInstallCommand
+ customize.command: echo customizeCommand
+ pre.launch.command: echo preLaunchCommand
+ launch.powershell.command: |
+ Start-Sleep -s 400
+ Write-Host Test Completed
+ post.launch.command: echo postLaunchCommand
+ checkRunning.command: echo checkRunningCommand
+ stop.command: echo stopCommand
+
+With series of tests we concluded that on the Vcloud Director environment we were using
+a restart was happening ~2 minutes after the VM is provisioned.
+Logging in the host and search for System event of type 1074 in Windows Event Viewer, we found two 1074 events where the second one was
+
+ The process C:\Windows\system32\winlogon.exe (W2K12-STD) has initiated the restart of computer WIN-XXXX on behalf of user
+ NT AUTHORITY\SYSTEM for the following reason: Operating System: Upgrade (Planned) Reason Code: 0x80020003 Shutdown Type: restart Comment:
+
+Normally on other clouds only one restart event is registered and the first time winrm connection is made the Windows VM is ready for use.
+
+For this particular case when you want this second restart to finish we made `waitWindowsToStart` location parameter
+which basically adds additional check assuring the Windows VM provisioning is done.
+
+
+For example when using `waitWindowsToStart: 5m` location parameter, Apache Brooklyn will wait 5 minutes to see if a disconnect occurs.
+If it does, then it will again wait 5m for the machine to come back up.
+The default behaviour in Apache Brooklyn is to consider provisioning done on the first successful winrm connection, without waiting for restart.
+
+
+To determine whether you should use this parameter you should carefully inspect how the image you choose to provision is behaving.
+If the description above matches your case and you are getting **connection failure message in the middle of the installation process** for your blueprints,
+a restart probably occurred and you should try this parameter.
+
+Before using this parameter we advice to check whether this is really your case.
+To verify the behavior check as described above.
+
### AMIs not found
If using the imageId of a Windows community AMI, you may find that the AMI is deleted after a few weeks.
diff --git a/guide/yaml/yaml-reference.md b/guide/yaml/yaml-reference.md
index 7a628a0..d198316 100644
--- a/guide/yaml/yaml-reference.md
+++ b/guide/yaml/yaml-reference.md
@@ -191,9 +191,9 @@
can be used to supply config at the root which is used in multiple places in the plan
* `$brooklyn:sensor("sensor.name")` returns the given sensor on the current entity if found, or an untyped (Object) sensor;
`$brooklyn:sensor("com.acme.brooklyn.ContainingEntityClass", "sensor.name")` returns the strongly typed sensor defined in the given class
-* `$brooklyn:component("ID")` refers to a Brooklyn component with the given ID; you can then access the following subfields,
+* `$brooklyn:entity("ID")` refers to a Brooklyn entity with the given ID; you can then access the following subfields,
using the same syntax as defined above but with a different reference entity,
- e.g. `$brooklyn:component("ID").attributeWhenReady("sensor")`:
+ e.g. `$brooklyn:entity("ID").attributeWhenReady("sensor")`:
* `.attributeWhenReady("sensor")`
* `.config("key")`
* `.sensor("sensor.name")`
diff --git a/style/css/_code_blocks.scss b/style/css/_code_blocks.scss
index dd39dd8..3e25172 100644
--- a/style/css/_code_blocks.scss
+++ b/style/css/_code_blocks.scss
@@ -9,7 +9,7 @@
@mixin code() {
font-family: Consolas, Lucida Console, Monaco, monospace;
@include nowrap();
- font-size: 14px;
+ font-size: 80%;
/* override color and bg-color on 'code' from bootstrap, and a touch more padding on top since font-size is smaller */
color: $text_color;
background-color: $code_bg_color;
diff --git a/website/documentation/faq.md b/website/documentation/faq.md
index 7af5f80..483d686 100644
--- a/website/documentation/faq.md
+++ b/website/documentation/faq.md
@@ -31,7 +31,7 @@
Please **increase the ulimit** if you see such error:
On the VM running Apache Brooklyn, we recommend ensuring nproc and nofile are reasonably high (e.g. higher than 1024, which is often the default).
-We recommend setting it limits to a value above 16000.
+We recommend setting it limits to a value of 16384 or higher.
If you want to check the current limits run `ulimit -a`.
diff --git a/website/download/index.md b/website/download/index.md
index c4fc01e..392b632 100644
--- a/website/download/index.md
+++ b/website/download/index.md
@@ -15,7 +15,7 @@
<div class="panel panel-default">
<div class="panel-heading" markdown="1">
-#### **Distribution** (Recommended)
+#### Distribution
</div>
<div class="panel-body" markdown="1">
<div style="height: 9em;" markdown="1">
@@ -24,12 +24,55 @@
(Java 1.7 or 1.8 are supported, including OpenJDK, Oracle, and IBM varieties).*
</div>
-**Choose your preferred file format to see the list of mirrors where you can download this file.**
+<div class="text-center">
+ <a class="btn btn-default" href="https://www.apache.org/dyn/closer.lua?action=download&filename=brooklyn/apache-brooklyn-{{ site.brooklyn-stable-version }}/apache-brooklyn-{{ site.brooklyn-stable-version }}-bin.tar.gz" role="button">Tarball</a>
+ <a class="btn btn-default" href="https://www.apache.org/dyn/closer.lua?action=download&filename=brooklyn/apache-brooklyn-{{ site.brooklyn-stable-version }}/apache-brooklyn-{{ site.brooklyn-stable-version }}-bin.zip" role="button">Zip</a>
+</div>
+ </div>
+</div>
+
+</div><!-- col -->
+<div class="col-md-6" markdown="1">
+
+<div class="panel panel-default">
+ <div class="panel-heading" markdown="1">
+#### RPM Package
+ </div>
+ <div class="panel-body" markdown="1">
+<div style="height: 9em;" markdown="1">
+Suitable for version 7 of CentOS and Red Hat Enterprise Linux.
+</div>
<div class="text-center">
- <a class="btn btn-default" href="https://www.apache.org/dyn/closer.lua/brooklyn/apache-brooklyn-{{ site.brooklyn-stable-version }}/apache-brooklyn-{{ site.brooklyn-stable-version }}-bin.tar.gz" role="button">Tarball</a>
- <a class="btn btn-default" href="https://www.apache.org/dyn/closer.lua/brooklyn/apache-brooklyn-{{ site.brooklyn-stable-version }}/apache-brooklyn-{{ site.brooklyn-stable-version }}-bin.zip" role="button">Zip</a>
- <br /><small>These are not direct download links, sorry</small>
+ <a class="btn btn-default" href="https://www.apache.org/dyn/closer.lua?action=download&filename=brooklyn/apache-brooklyn-{{ site.brooklyn-stable-version }}/apache-brooklyn-{{ site.brooklyn-stable-version }}-1.noarch.rpm" role="button">RPM package</a>
+</div>
+ </div>
+</div>
+
+</div><!-- col -->
+</div><!-- row -->
+
+<div class="row">
+<div class="col-md-6" markdown="1">
+
+<div class="panel panel-default">
+ <div class="panel-heading" markdown="1">
+#### Command line client
+ </div>
+ <div class="panel-body" markdown="1">
+<div style="height: 6.5em;" markdown="1">
+Already got a Brooklyn server? Download just the CLI client here.
+</div>
+
+<div class="text-center" style="margin-bottom: 0.5em">
+ <a class="btn btn-default" href="https://www.apache.org/dyn/closer.lua?action=download&filename=brooklyn/apache-brooklyn-{{ site.brooklyn-stable-version }}/apache-brooklyn-{{ site.brooklyn-stable-version }}-client-cli-linux.tar.gz" role="button">Linux Tarball</a>
+ <a class="btn btn-default" href="https://www.apache.org/dyn/closer.lua?action=download&filename=brooklyn/apache-brooklyn-{{ site.brooklyn-stable-version }}/apache-brooklyn-{{ site.brooklyn-stable-version }}-client-cli-macosx.tar.gz" role="button">Mac OSX Tarball</a>
+ <a class="btn btn-default" href="https://www.apache.org/dyn/closer.lua?action=download&filename=brooklyn/apache-brooklyn-{{ site.brooklyn-stable-version }}/apache-brooklyn-{{ site.brooklyn-stable-version }}-client-cli-windows.tar.gz" role="button">Windows Tarball</a>
+</div>
+<div class="text-center">
+ <a class="btn btn-default" href="https://www.apache.org/dyn/closer.lua?action=download&filename=brooklyn/apache-brooklyn-{{ site.brooklyn-stable-version }}/apache-brooklyn-{{ site.brooklyn-stable-version }}-client-cli-linux.zip" role="button">Linux Zip</a>
+ <a class="btn btn-default" href="https://www.apache.org/dyn/closer.lua?action=download&filename=brooklyn/apache-brooklyn-{{ site.brooklyn-stable-version }}/apache-brooklyn-{{ site.brooklyn-stable-version }}-client-cli-macosx.zip" role="button">Mac OSX Zip</a>
+ <a class="btn btn-default" href="https://www.apache.org/dyn/closer.lua?action=download&filename=brooklyn/apache-brooklyn-{{ site.brooklyn-stable-version }}/apache-brooklyn-{{ site.brooklyn-stable-version }}-client-cli-windows.zip" role="button">Windows Zip</a>
</div>
</div>
</div>
@@ -48,12 +91,9 @@
[Developers pages](../developers/index.html) to find out more.*
</div>
-**Choose your preferred file format to see the list of mirrors where you can download this file.**
-
<div class="text-center">
- <a class="btn btn-default" href="https://www.apache.org/dyn/closer.lua/brooklyn/apache-brooklyn-{{ site.brooklyn-stable-version }}/apache-brooklyn-{{ site.brooklyn-stable-version }}-src.tar.gz" role="button">Tarball</a>
- <a class="btn btn-default" href="https://www.apache.org/dyn/closer.lua/brooklyn/apache-brooklyn-{{ site.brooklyn-stable-version }}/apache-brooklyn-{{ site.brooklyn-stable-version }}-src.zip" role="button">Zip</a>
- <br /><small>These are not direct download links, sorry</small>
+ <a class="btn btn-default" href="https://www.apache.org/dyn/closer.lua?action=download&filename=brooklyn/apache-brooklyn-{{ site.brooklyn-stable-version }}/apache-brooklyn-{{ site.brooklyn-stable-version }}-src.tar.gz" role="button">Tarball</a>
+ <a class="btn btn-default" href="https://www.apache.org/dyn/closer.lua?action=download&filename=brooklyn/apache-brooklyn-{{ site.brooklyn-stable-version }}/apache-brooklyn-{{ site.brooklyn-stable-version }}-src.zip" role="button">Zip</a>
</div>
</div>
</div>
diff --git a/website/download/verify.md b/website/download/verify.md
index 7fff787..e1f33b7 100644
--- a/website/download/verify.md
+++ b/website/download/verify.md
@@ -18,58 +18,124 @@
</tr>
<tr>
+<td>apache-brooklyn-0.9.0-bin.tar.gz</td>
+<td><a href="https://www.apache.org/dist/brooklyn/apache-brooklyn-0.9.0/apache-brooklyn-0.9.0-bin.tar.gz.md5">md5</a></td>
+<td><a href="https://www.apache.org/dist/brooklyn/apache-brooklyn-0.9.0/apache-brooklyn-0.9.0-bin.tar.gz.sha1">sha1</a></td>
+<td><a href="https://www.apache.org/dist/brooklyn/apache-brooklyn-0.9.0/apache-brooklyn-0.9.0-bin.tar.gz.sha256">sha256</a></td>
+</tr>
+<tr>
+<td>apache-brooklyn-0.9.0-bin.zip</td>
+<td><a href="https://www.apache.org/dist/brooklyn/apache-brooklyn-0.9.0/apache-brooklyn-0.9.0-bin.zip.md5">md5</a></td>
+<td><a href="https://www.apache.org/dist/brooklyn/apache-brooklyn-0.9.0/apache-brooklyn-0.9.0-bin.zip.sha1">sha1</a></td>
+<td><a href="https://www.apache.org/dist/brooklyn/apache-brooklyn-0.9.0/apache-brooklyn-0.9.0-bin.zip.sha256">sha256</a></td>
+</tr>
+<tr>
+<td>apache-brooklyn-0.9.0-1.noarch.rpm</td>
+<td><a href="https://www.apache.org/dist/brooklyn/apache-brooklyn-0.9.0/apache-brooklyn-0.9.0-1.noarch.rpm.md5">md5</a></td>
+<td><a href="https://www.apache.org/dist/brooklyn/apache-brooklyn-0.9.0/apache-brooklyn-0.9.0-1.noarch.rpm.sha1">sha1</a></td>
+<td><a href="https://www.apache.org/dist/brooklyn/apache-brooklyn-0.9.0/apache-brooklyn-0.9.0-1.noarch.rpm.sha256">sha256</a></td>
+</tr>
+<tr>
+<td>apache-brooklyn-0.9.0-src.tar.gz</td>
+<td><a href="https://www.apache.org/dist/brooklyn/apache-brooklyn-0.9.0/apache-brooklyn-0.9.0-src.tar.gz.md5">md5</a></td>
+<td><a href="https://www.apache.org/dist/brooklyn/apache-brooklyn-0.9.0/apache-brooklyn-0.9.0-src.tar.gz.sha1">sha1</a></td>
+<td><a href="https://www.apache.org/dist/brooklyn/apache-brooklyn-0.9.0/apache-brooklyn-0.9.0-src.tar.gz.sha256">sha256</a></td>
+</tr>
+<tr>
+<td>apache-brooklyn-0.9.0-src.zip</td>
+<td><a href="https://www.apache.org/dist/brooklyn/apache-brooklyn-0.9.0/apache-brooklyn-0.9.0-src.zip.md5">md5</a></td>
+<td><a href="https://www.apache.org/dist/brooklyn/apache-brooklyn-0.9.0/apache-brooklyn-0.9.0-src.zip.sha1">sha1</a></td>
+<td><a href="https://www.apache.org/dist/brooklyn/apache-brooklyn-0.9.0/apache-brooklyn-0.9.0-src.zip.sha256">sha256</a></td>
+</tr>
+<tr>
+<td>apache-brooklyn-0.9.0-client-cli-linux.tar.gz</td>
+<td><a href="https://www.apache.org/dist/brooklyn/apache-brooklyn-0.9.0/apache-brooklyn-0.9.0-client-cli-linux.tar.gz.md5">md5</a></td>
+<td><a href="https://www.apache.org/dist/brooklyn/apache-brooklyn-0.9.0/apache-brooklyn-0.9.0-client-cli-linux.tar.gz.sha1">sha1</a></td>
+<td><a href="https://www.apache.org/dist/brooklyn/apache-brooklyn-0.9.0/apache-brooklyn-0.9.0-client-cli-linux.tar.gz.sha256">sha256</a></td>
+</tr>
+<tr>
+<td>apache-brooklyn-0.9.0-client-cli-linux.zip</td>
+<td><a href="https://www.apache.org/dist/brooklyn/apache-brooklyn-0.9.0/apache-brooklyn-0.9.0-client-cli-linux.zip.md5">md5</a></td>
+<td><a href="https://www.apache.org/dist/brooklyn/apache-brooklyn-0.9.0/apache-brooklyn-0.9.0-client-cli-linux.zip.sha1">sha1</a></td>
+<td><a href="https://www.apache.org/dist/brooklyn/apache-brooklyn-0.9.0/apache-brooklyn-0.9.0-client-cli-linux.zip.sha256">sha256</a></td>
+</tr>
+<tr>
+<td>apache-brooklyn-0.9.0-client-cli-macosx.tar.gz</td>
+<td><a href="https://www.apache.org/dist/brooklyn/apache-brooklyn-0.9.0/apache-brooklyn-0.9.0-client-cli-macosx.tar.gz.md5">md5</a></td>
+<td><a href="https://www.apache.org/dist/brooklyn/apache-brooklyn-0.9.0/apache-brooklyn-0.9.0-client-cli-macosx.tar.gz.sha1">sha1</a></td>
+<td><a href="https://www.apache.org/dist/brooklyn/apache-brooklyn-0.9.0/apache-brooklyn-0.9.0-client-cli-macosx.tar.gz.sha256">sha256</a></td>
+</tr>
+<tr>
+<td>apache-brooklyn-0.9.0-client-cli-macosx.zip</td>
+<td><a href="https://www.apache.org/dist/brooklyn/apache-brooklyn-0.9.0/apache-brooklyn-0.9.0-client-cli-macosx.zip.md5">md5</a></td>
+<td><a href="https://www.apache.org/dist/brooklyn/apache-brooklyn-0.9.0/apache-brooklyn-0.9.0-client-cli-macosx.zip.sha1">sha1</a></td>
+<td><a href="https://www.apache.org/dist/brooklyn/apache-brooklyn-0.9.0/apache-brooklyn-0.9.0-client-cli-macosx.zip.sha256">sha256</a></td>
+</tr>
+<tr>
+<td>apache-brooklyn-0.9.0-client-cli-windows.tar.gz</td>
+<td><a href="https://www.apache.org/dist/brooklyn/apache-brooklyn-0.9.0/apache-brooklyn-0.9.0-client-cli-windows.tar.gz.md5">md5</a></td>
+<td><a href="https://www.apache.org/dist/brooklyn/apache-brooklyn-0.9.0/apache-brooklyn-0.9.0-client-cli-windows.tar.gz.sha1">sha1</a></td>
+<td><a href="https://www.apache.org/dist/brooklyn/apache-brooklyn-0.9.0/apache-brooklyn-0.9.0-client-cli-windows.tar.gz.sha256">sha256</a></td>
+</tr>
+<tr>
+<td>apache-brooklyn-0.9.0-client-cli-windows.zip</td>
+<td><a href="https://www.apache.org/dist/brooklyn/apache-brooklyn-0.9.0/apache-brooklyn-0.9.0-client-cli-windows.zip.md5">md5</a></td>
+<td><a href="https://www.apache.org/dist/brooklyn/apache-brooklyn-0.9.0/apache-brooklyn-0.9.0-client-cli-windows.zip.sha1">sha1</a></td>
+<td><a href="https://www.apache.org/dist/brooklyn/apache-brooklyn-0.9.0/apache-brooklyn-0.9.0-client-cli-windows.zip.sha256">sha256</a></td>
+</tr>
+<tr>
<td>apache-brooklyn-0.8.0-incubating-bin.tar.gz</td>
-<td><a href="https://www.apache.org/dist/brooklyn/apache-brooklyn-0.8.0-incubating/apache-brooklyn-0.8.0-incubating-bin.tar.gz.md5">md5</a></td>
-<td><a href="https://www.apache.org/dist/brooklyn/apache-brooklyn-0.8.0-incubating/apache-brooklyn-0.8.0-incubating-bin.tar.gz.sha1">sha1</a></td>
-<td><a href="https://www.apache.org/dist/brooklyn/apache-brooklyn-0.8.0-incubating/apache-brooklyn-0.8.0-incubating-bin.tar.gz.sha256">sha256</a></td>
+<td><a href="https://archive.apache.org/dist/brooklyn/apache-brooklyn-0.8.0-incubating/apache-brooklyn-0.8.0-incubating-bin.tar.gz.md5">md5</a></td>
+<td><a href="https://archive.apache.org/dist/brooklyn/apache-brooklyn-0.8.0-incubating/apache-brooklyn-0.8.0-incubating-bin.tar.gz.sha1">sha1</a></td>
+<td><a href="https://archive.apache.org/dist/brooklyn/apache-brooklyn-0.8.0-incubating/apache-brooklyn-0.8.0-incubating-bin.tar.gz.sha256">sha256</a></td>
</tr>
<tr>
<td>apache-brooklyn-0.8.0-incubating-bin.zip</td>
-<td><a href="https://www.apache.org/dist/brooklyn/apache-brooklyn-0.8.0-incubating/apache-brooklyn-0.8.0-incubating-bin.zip.md5">md5</a></td>
-<td><a href="https://www.apache.org/dist/brooklyn/apache-brooklyn-0.8.0-incubating/apache-brooklyn-0.8.0-incubating-bin.zip.sha1">sha1</a></td>
-<td><a href="https://www.apache.org/dist/brooklyn/apache-brooklyn-0.8.0-incubating/apache-brooklyn-0.8.0-incubating-bin.zip.sha256">sha256</a></td>
+<td><a href="https://archive.apache.org/dist/brooklyn/apache-brooklyn-0.8.0-incubating/apache-brooklyn-0.8.0-incubating-bin.zip.md5">md5</a></td>
+<td><a href="https://archive.apache.org/dist/brooklyn/apache-brooklyn-0.8.0-incubating/apache-brooklyn-0.8.0-incubating-bin.zip.sha1">sha1</a></td>
+<td><a href="https://archive.apache.org/dist/brooklyn/apache-brooklyn-0.8.0-incubating/apache-brooklyn-0.8.0-incubating-bin.zip.sha256">sha256</a></td>
</tr>
<tr>
<td>apache-brooklyn-0.8.0-incubating-src.tar.gz</td>
-<td><a href="https://www.apache.org/dist/brooklyn/apache-brooklyn-0.8.0-incubating/apache-brooklyn-0.8.0-incubating-src.tar.gz.md5">md5</a></td>
-<td><a href="https://www.apache.org/dist/brooklyn/apache-brooklyn-0.8.0-incubating/apache-brooklyn-0.8.0-incubating-src.tar.gz.sha1">sha1</a></td>
-<td><a href="https://www.apache.org/dist/brooklyn/apache-brooklyn-0.8.0-incubating/apache-brooklyn-0.8.0-incubating-src.tar.gz.sha256">sha256</a></td>
+<td><a href="https://archive.apache.org/dist/brooklyn/apache-brooklyn-0.8.0-incubating/apache-brooklyn-0.8.0-incubating-src.tar.gz.md5">md5</a></td>
+<td><a href="https://archive.apache.org/dist/brooklyn/apache-brooklyn-0.8.0-incubating/apache-brooklyn-0.8.0-incubating-src.tar.gz.sha1">sha1</a></td>
+<td><a href="https://archive.apache.org/dist/brooklyn/apache-brooklyn-0.8.0-incubating/apache-brooklyn-0.8.0-incubating-src.tar.gz.sha256">sha256</a></td>
</tr>
<tr>
<td>apache-brooklyn-0.8.0-incubating-src.zip</td>
-<td><a href="https://www.apache.org/dist/brooklyn/apache-brooklyn-0.8.0-incubating/apache-brooklyn-0.8.0-incubating-src.zip.md5">md5</a></td>
-<td><a href="https://www.apache.org/dist/brooklyn/apache-brooklyn-0.8.0-incubating/apache-brooklyn-0.8.0-incubating-src.zip.sha1">sha1</a></td>
-<td><a href="https://www.apache.org/dist/brooklyn/apache-brooklyn-0.8.0-incubating/apache-brooklyn-0.8.0-incubating-src.zip.sha256">sha256</a></td>
+<td><a href="https://archive.apache.org/dist/brooklyn/apache-brooklyn-0.8.0-incubating/apache-brooklyn-0.8.0-incubating-src.zip.md5">md5</a></td>
+<td><a href="https://archive.apache.org/dist/brooklyn/apache-brooklyn-0.8.0-incubating/apache-brooklyn-0.8.0-incubating-src.zip.sha1">sha1</a></td>
+<td><a href="https://archive.apache.org/dist/brooklyn/apache-brooklyn-0.8.0-incubating/apache-brooklyn-0.8.0-incubating-src.zip.sha256">sha256</a></td>
</tr>
<tr>
<td>apache-brooklyn-0.7.0-incubating-bin.tar.gz</td>
-<td><a href="https://www.apache.org/dist/brooklyn/apache-brooklyn-0.7.0-incubating/apache-brooklyn-0.7.0-incubating-bin.tar.gz.md5">md5</a></td>
-<td><a href="https://www.apache.org/dist/brooklyn/apache-brooklyn-0.7.0-incubating/apache-brooklyn-0.7.0-incubating-bin.tar.gz.sha1">sha1</a></td>
-<td><a href="https://www.apache.org/dist/brooklyn/apache-brooklyn-0.7.0-incubating/apache-brooklyn-0.7.0-incubating-bin.tar.gz.sha256">sha256</a></td>
+<td><a href="https://archive.apache.org/dist/brooklyn/apache-brooklyn-0.7.0-incubating/apache-brooklyn-0.7.0-incubating-bin.tar.gz.md5">md5</a></td>
+<td><a href="https://archive.apache.org/dist/brooklyn/apache-brooklyn-0.7.0-incubating/apache-brooklyn-0.7.0-incubating-bin.tar.gz.sha1">sha1</a></td>
+<td><a href="https://archive.apache.org/dist/brooklyn/apache-brooklyn-0.7.0-incubating/apache-brooklyn-0.7.0-incubating-bin.tar.gz.sha256">sha256</a></td>
</tr>
<tr>
<td>apache-brooklyn-0.7.0-incubating-bin.zip</td>
-<td><a href="https://www.apache.org/dist/brooklyn/apache-brooklyn-0.7.0-incubating/apache-brooklyn-0.7.0-incubating-bin.zip.md5">md5</a></td>
-<td><a href="https://www.apache.org/dist/brooklyn/apache-brooklyn-0.7.0-incubating/apache-brooklyn-0.7.0-incubating-bin.zip.sha1">sha1</a></td>
-<td><a href="https://www.apache.org/dist/brooklyn/apache-brooklyn-0.7.0-incubating/apache-brooklyn-0.7.0-incubating-bin.zip.sha256">sha256</a></td>
+<td><a href="https://archive.apache.org/dist/brooklyn/apache-brooklyn-0.7.0-incubating/apache-brooklyn-0.7.0-incubating-bin.zip.md5">md5</a></td>
+<td><a href="https://archive.apache.org/dist/brooklyn/apache-brooklyn-0.7.0-incubating/apache-brooklyn-0.7.0-incubating-bin.zip.sha1">sha1</a></td>
+<td><a href="https://archive.apache.org/dist/brooklyn/apache-brooklyn-0.7.0-incubating/apache-brooklyn-0.7.0-incubating-bin.zip.sha256">sha256</a></td>
</tr>
<tr>
<td>apache-brooklyn-0.7.0-incubating-src.tar.gz</td>
-<td><a href="https://www.apache.org/dist/brooklyn/apache-brooklyn-0.7.0-incubating/apache-brooklyn-0.7.0-incubating-src.tar.gz.md5">md5</a></td>
-<td><a href="https://www.apache.org/dist/brooklyn/apache-brooklyn-0.7.0-incubating/apache-brooklyn-0.7.0-incubating-src.tar.gz.sha1">sha1</a></td>
-<td><a href="https://www.apache.org/dist/brooklyn/apache-brooklyn-0.7.0-incubating/apache-brooklyn-0.7.0-incubating-src.tar.gz.sha256">sha256</a></td>
+<td><a href="https://archive.apache.org/dist/brooklyn/apache-brooklyn-0.7.0-incubating/apache-brooklyn-0.7.0-incubating-src.tar.gz.md5">md5</a></td>
+<td><a href="https://archive.apache.org/dist/brooklyn/apache-brooklyn-0.7.0-incubating/apache-brooklyn-0.7.0-incubating-src.tar.gz.sha1">sha1</a></td>
+<td><a href="https://archive.apache.org/dist/brooklyn/apache-brooklyn-0.7.0-incubating/apache-brooklyn-0.7.0-incubating-src.tar.gz.sha256">sha256</a></td>
</tr>
<tr>
<td>apache-brooklyn-0.7.0-incubating-src.zip</td>
-<td><a href="https://www.apache.org/dist/brooklyn/apache-brooklyn-0.7.0-incubating/apache-brooklyn-0.7.0-incubating-src.zip.md5">md5</a></td>
-<td><a href="https://www.apache.org/dist/brooklyn/apache-brooklyn-0.7.0-incubating/apache-brooklyn-0.7.0-incubating-src.zip.sha1">sha1</a></td>
-<td><a href="https://www.apache.org/dist/brooklyn/apache-brooklyn-0.7.0-incubating/apache-brooklyn-0.7.0-incubating-src.zip.sha256">sha256</a></td>
+<td><a href="https://archive.apache.org/dist/brooklyn/apache-brooklyn-0.7.0-incubating/apache-brooklyn-0.7.0-incubating-src.zip.md5">md5</a></td>
+<td><a href="https://archive.apache.org/dist/brooklyn/apache-brooklyn-0.7.0-incubating/apache-brooklyn-0.7.0-incubating-src.zip.sha1">sha1</a></td>
+<td><a href="https://archive.apache.org/dist/brooklyn/apache-brooklyn-0.7.0-incubating/apache-brooklyn-0.7.0-incubating-src.zip.sha256">sha256</a></td>
</tr>
<tr>
<td>apache-brooklyn-0.7.0-M2-incubating</td>
-<td><a href="https://www.apache.org/dist/brooklyn/0.7.0-M2-incubating/apache-brooklyn-0.7.0-M2-incubating.tar.gz.md5">md5</a></td>
-<td><a href="https://www.apache.org/dist/brooklyn/0.7.0-M2-incubating/apache-brooklyn-0.7.0-M2-incubating.tar.gz.sha1">sha1</a></td>
-<td><a href="https://www.apache.org/dist/brooklyn/0.7.0-M2-incubating/apache-brooklyn-0.7.0-M2-incubating.tar.gz.sha256">sha256</a></td>
+<td><a href="https://archive.apache.org/dist/brooklyn/0.7.0-M2-incubating/apache-brooklyn-0.7.0-M2-incubating.tar.gz.md5">md5</a></td>
+<td><a href="https://archive.apache.org/dist/brooklyn/0.7.0-M2-incubating/apache-brooklyn-0.7.0-M2-incubating.tar.gz.sha1">sha1</a></td>
+<td><a href="https://archive.apache.org/dist/brooklyn/0.7.0-M2-incubating/apache-brooklyn-0.7.0-M2-incubating.tar.gz.sha256">sha256</a></td>
</tr>
</table>
@@ -104,24 +170,84 @@
</tr>
<tr>
+<td>apache-brooklyn-0.9.0-bin.tar.gz</td>
+<td><a href="https://www.apache.org/dist/brooklyn/apache-brooklyn-0.9.0/apache-brooklyn-0.9.0-bin.tar.gz.asc">asc</a></td>
+</tr>
+<tr>
+<td>apache-brooklyn-0.9.0-bin.zip</td>
+<td><a href="https://www.apache.org/dist/brooklyn/apache-brooklyn-0.9.0/apache-brooklyn-0.9.0-bin.zip.asc">asc</a></td>
+</tr>
+<tr>
+<td>apache-brooklyn-0.9.0-1.noarch.rpm</td>
+<td><a href="https://www.apache.org/dist/brooklyn/apache-brooklyn-0.9.0/apache-brooklyn-0.9.0-1.noarch.rpm.asc">asc</a></td>
+</tr>
+<tr>
+<td>apache-brooklyn-0.9.0-src.tar.gz</td>
+<td><a href="https://www.apache.org/dist/brooklyn/apache-brooklyn-0.9.0/apache-brooklyn-0.9.0-src.tar.gz.asc">asc</a></td>
+</tr>
+<tr>
+<td>apache-brooklyn-0.9.0-src.zip</td>
+<td><a href="https://www.apache.org/dist/brooklyn/apache-brooklyn-0.9.0/apache-brooklyn-0.9.0-src.zip.asc">asc</a></td>
+</tr>
+<tr>
+<td>apache-brooklyn-0.9.0-client-cli-linux.tar.gz</td>
+<td><a href="https://www.apache.org/dist/brooklyn/apache-brooklyn-0.9.0/apache-brooklyn-0.9.0-client-cli-linux.tar.gz.asc">asc</a></td>
+</tr>
+<tr>
+<td>apache-brooklyn-0.9.0-client-cli-linux.zip</td>
+<td><a href="https://www.apache.org/dist/brooklyn/apache-brooklyn-0.9.0/apache-brooklyn-0.9.0-client-cli-linux.zip.asc">asc</a></td>
+</tr>
+<tr>
+<td>apache-brooklyn-0.9.0-client-cli-macosx.tar.gz</td>
+<td><a href="https://www.apache.org/dist/brooklyn/apache-brooklyn-0.9.0/apache-brooklyn-0.9.0-client-cli-macosx.tar.gz.asc">asc</a></td>
+</tr>
+<tr>
+<td>apache-brooklyn-0.9.0-client-cli-macosx.zip</td>
+<td><a href="https://www.apache.org/dist/brooklyn/apache-brooklyn-0.9.0/apache-brooklyn-0.9.0-client-cli-macosx.zip.asc">asc</a></td>
+</tr>
+<tr>
+<td>apache-brooklyn-0.9.0-client-cli-windows.tar.gz</td>
+<td><a href="https://www.apache.org/dist/brooklyn/apache-brooklyn-0.9.0/apache-brooklyn-0.9.0-client-cli-windows.tar.gz.asc">asc</a></td>
+</tr>
+<tr>
+<td>apache-brooklyn-0.9.0-client-cli-windows.zip</td>
+<td><a href="https://www.apache.org/dist/brooklyn/apache-brooklyn-0.9.0/apache-brooklyn-0.9.0-client-cli-windows.zip.asc">asc</a></td>
+</tr>
+<tr>
+<td>apache-brooklyn-0.8.0-incubating-bin.tar.gz</td>
+<td><a href="https://archive.apache.org/dist/brooklyn/apache-brooklyn-0.8.0-incubating/apache-brooklyn-0.8.0-incubating-bin.tar.gz.asc">asc</a></td>
+</tr>
+<tr>
+<td>apache-brooklyn-0.8.0-incubating-bin.zip</td>
+<td><a href="https://archive.apache.org/dist/brooklyn/apache-brooklyn-0.8.0-incubating/apache-brooklyn-0.8.0-incubating-bin.zip.asc">asc</a></td>
+</tr>
+<tr>
+<td>apache-brooklyn-0.8.0-incubating-src.tar.gz</td>
+<td><a href="https://archive.apache.org/dist/brooklyn/apache-brooklyn-0.8.0-incubating/apache-brooklyn-0.8.0-incubating-src.tar.gz.asc">asc</a></td>
+</tr>
+<tr>
+<td>apache-brooklyn-0.8.0-incubating-src.zip</td>
+<td><a href="https://archive.apache.org/dist/brooklyn/apache-brooklyn-0.8.0-incubating/apache-brooklyn-0.8.0-incubating-src.zip.asc">asc</a></td>
+</tr>
+<tr>
<td>apache-brooklyn-0.7.0-incubating-bin.tar.gz</td>
-<td><a href="https://www.apache.org/dist/brooklyn/apache-brooklyn-0.7.0-incubating/apache-brooklyn-0.7.0-incubating-bin.tar.gz.asc">asc</a></td>
+<td><a href="https://archive.apache.org/dist/brooklyn/apache-brooklyn-0.7.0-incubating/apache-brooklyn-0.7.0-incubating-bin.tar.gz.asc">asc</a></td>
</tr>
<tr>
<td>apache-brooklyn-0.7.0-incubating-bin.zip</td>
-<td><a href="https://www.apache.org/dist/brooklyn/apache-brooklyn-0.7.0-incubating/apache-brooklyn-0.7.0-incubating-bin.zip.asc">asc</a></td>
+<td><a href="https://archive.apache.org/dist/brooklyn/apache-brooklyn-0.7.0-incubating/apache-brooklyn-0.7.0-incubating-bin.zip.asc">asc</a></td>
</tr>
<tr>
<td>apache-brooklyn-0.7.0-incubating-src.tar.gz</td>
-<td><a href="https://www.apache.org/dist/brooklyn/apache-brooklyn-0.7.0-incubating/apache-brooklyn-0.7.0-incubating-src.tar.gz.asc">asc</a></td>
+<td><a href="https://archive.apache.org/dist/brooklyn/apache-brooklyn-0.7.0-incubating/apache-brooklyn-0.7.0-incubating-src.tar.gz.asc">asc</a></td>
</tr>
<tr>
<td>apache-brooklyn-0.7.0-incubating-src.zip</td>
-<td><a href="https://www.apache.org/dist/brooklyn/apache-brooklyn-0.7.0-incubating/apache-brooklyn-0.7.0-incubating-src.zip.asc">asc</a></td>
+<td><a href="https://archive.apache.org/dist/brooklyn/apache-brooklyn-0.7.0-incubating/apache-brooklyn-0.7.0-incubating-src.zip.asc">asc</a></td>
</tr>
<tr>
<td>apache-brooklyn-0.7.0-M2-incubating.tar.gz</td>
-<td><a href="https://www.apache.org/dist/brooklyn/0.7.0-M2-incubating/apache-brooklyn-0.7.0-M2-incubating.tar.gz.asc">asc</a></td>
+<td><a href="https://archive.apache.org/dist/brooklyn/0.7.0-M2-incubating/apache-brooklyn-0.7.0-M2-incubating.tar.gz.asc">asc</a></td>
</tr>
</table>
diff --git a/website/meta/versions.md b/website/meta/versions.md
index f3941d7..a23cb20 100644
--- a/website/meta/versions.md
+++ b/website/meta/versions.md
@@ -19,9 +19,12 @@
Apache Brooklyn has made the following releases:
-* **[0.8.0-incubating](/v/0.8.0-incubating/)**: Package rename to org.apache.brooklyn.*, and many other improvements. Apache-endorsed binary release! (September 2015)
+* **[0.9.0](/v/0.9.0/)**: Adds Brooklyn CLI client, RPM package, getting started
+ using Vagrant. First release as an Apache top-level project! (April 2016)
-* **[0.7.0-incubating](/v/0.7.0-incubating/)**: New policies, more clouds, improved Windows support and many other improvements. Apache-endorsed binary release! (July 2015)
+* **[0.8.0-incubating](/v/0.8.0-incubating/)**: Package rename to org.apache.brooklyn, and many other improvements. (September 2015)
+
+* **[0.7.0-incubating](/v/0.7.0-incubating/)**: New policies, more clouds, improved Windows support and many other improvements. First Apache-endorsed binary release! (July 2015)
* **[0.7.0-M2-incubating](/v/0.7.0-M2-incubating/)**: YAML, persistence, Chef, Windows, Docker. The first Apache release! (December 2014)
