You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@brooklyn.apache.org by he...@apache.org on 2016/02/01 18:45:23 UTC
[15/51] [abbrv] [partial] brooklyn-docs git commit: move subdir from
incubator up a level as it is promoted to its own repo (first non-incubator
commit!)
http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/6e86cb02/guide/java/entity.md
----------------------------------------------------------------------
diff --git a/guide/java/entity.md b/guide/java/entity.md
new file mode 100644
index 0000000..6828a17
--- /dev/null
+++ b/guide/java/entity.md
@@ -0,0 +1,90 @@
+---
+layout: website-normal
+title: Writing an Entity
+---
+
+## Ways to write an entity
+
+There are several ways to write a new entity:
+
+* Write pure-java, extending existing base-classes and using utilities such as `HttpTool` and `BashCommands`.
+* Write scripts, and configure (e.g. using YAML) a **`VanillaSoftwareProcess`**.
+* Use Chef recipes, and wire these into the entity by using `ChefConfig` and `ChefLifecycleEffectorTasks`.
+* Use an equivalent of Chef (e.g. Salt or Puppet; support for these is currently less mature than for Chef)
+
+The rest of this section covers writing an entity in pure-java (or other JVM languages).
+
+
+## Things To Know
+
+All entities have an interface and an implementation. The methods on the interface
+are its effectors; the interface also defines its sensors.
+
+Entities are created through the management context (rather than calling the
+constructor directly). This returns a proxy for the entity rather than the real
+instance, which is important in a distributed management plane.
+
+All entity implementations inherit from `AbstractEntity`,
+often through one of the following:
+
+* **`SoftwareProcessImpl`**: if it's a software process
+* **`VanillaJavaAppImpl`**: if it's a plain-old-java app
+* **`JavaWebAppSoftwareProcessImpl`**: if it's a JVM-based web-app
+* **`DynamicClusterImpl`**, **`DynamicGroupImpl`** or **`AbstractGroupImpl`**: if it's a collection of other entities
+
+Software-based processes tend to use *drivers* to install and
+launch the remote processes onto *locations* which support that driver type.
+For example, `AbstractSoftwareProcessSshDriver` is a common driver superclass,
+targetting `SshMachineLocation` (a machine to which Brooklyn can ssh).
+The various `SoftwareProcess` entities above (and some of the exemplars
+listed at the end of this page) have their own dedicated drivers.
+
+Finally, there are a collection of *traits*, such as `Resizable`,
+in the package ``brooklyn.entity.trait``. These provide common
+sensors and effectors on entities, supplied as interfaces.
+Choose one (or more) as appropriate.
+
+
+
+## Key Steps
+
+So to get started:
+
+1. Create your entity interface, extending the appropriate selection from above,
+ to define the effectors and sensors.
+2. Include an annotation like `@ImplementedBy(YourEntityImpl.class)` on your interface,
+ where `YourEntityImpl` will be the class name for your entity implementation.
+3. Create your entity class, implementing your entity interface and extending the
+ classes for your chosen entity super-types. Naming convention is a suffix "Impl"
+ for the entity class, but this is not essential.
+4. Create a driver interface, again extending as appropriate (e.g. `SoftwareProcessDriver`).
+ The naming convention is to have a suffix "Driver".
+5. Create the driver class, implementing your driver interface, and again extending as appropriate.
+ Naming convention is to have a suffix "SshDriver" for an ssh-based implementation.
+ The correct driver implementation is found using this naming convention, or via custom
+ namings provided by the `BasicEntityDriverFactory`.
+6. Wire the `public Class getDriverInterface()` method in the entity implementation, to specify
+ your driver interface.
+7. Provide the implementation of missing lifecycle methods in your driver class (details below)
+8. Connect the sensors from your entity (e.g. overriding `connectSensors()` of `SoftwareProcessImpl`)..
+ See the sensor feeds, such as `HttpFeed` and `JmxFeed`.
+
+Any JVM language can be used to write an entity. However use of pure Java is encouraged for
+entities in core brooklyn.
+
+
+## Helpful References
+
+A few handy pointers will help make it easy to build your own entities.
+Check out some of the exemplar existing entities
+(note, some of the other entities use deprecated utilities and a deprecated class
+hierarchy; it is suggested to avoid these, looking at the ones below instead):
+
+* `JBoss7Server`
+* `MySqlNode`
+
+You might also find the following helpful:
+
+* **[Entity Design Tips]({{site.path.guide}}/dev/tips/index.html#EntityDesign)**
+* The **[User Guide]({{site.path.guide}})**
+* The **[Mailing List](https://mail-archives.apache.org/mod_mbox/incubator-brooklyn-dev/)**
http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/6e86cb02/guide/java/index.md
----------------------------------------------------------------------
diff --git a/guide/java/index.md b/guide/java/index.md
new file mode 100644
index 0000000..279ca4b
--- /dev/null
+++ b/guide/java/index.md
@@ -0,0 +1,23 @@
+---
+title: Java Blueprints
+title_in_menu: Java Blueprints
+layout: website-normal
+children:
+- archetype.md
+- defining-and-deploying.md
+- topology-dependencies-management-policies.md
+- common-usage.md
+- entity.md
+- entities.md
+- policies.md
+- policy.md
+- service-state.md
+- entitlements.md
+---
+
+Java blueprints are much more powerful than YAML but is also rather more difficult.
+Advanced Java skills are required.
+
+{% include list-children.html %}
+
+Brooklyn makes it easy to describe the structure and management of sophisticated distributed applications, and then it makes it easy to launch them in a cloud, with on-going automated management.
http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/6e86cb02/guide/java/policies.md
----------------------------------------------------------------------
diff --git a/guide/java/policies.md b/guide/java/policies.md
new file mode 100644
index 0000000..4eb50fb
--- /dev/null
+++ b/guide/java/policies.md
@@ -0,0 +1,73 @@
+---
+title: Policies
+layout: website-normal
+
+---
+
+Policies perform the active management enabled by Brooklyn.
+They can subscribe to entity sensors and be triggered by them or they can run periodically.
+
+<!---
+TODO, clarify below, memebers of what?
+-->
+Policies can add subscriptions to sensors on any entity. Normally a policy will subscribe to its related entity, to the child entities, and/or those entities which are members.
+
+When a policy runs it can:
+
+* perform calculations,
+* look up other values,
+* invoke effectors (management policies) or,
+* cause the entity associated with the policy to emit sensor values (enricher policies).
+
+Entities can have zero or more ``Policy`` instances attached to them.
+
+
+Off-the-Shelf Policies
+----------------------
+
+Policies are highly reusable as their inputs, thresholds and targets are customizable.
+
+### 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.
+
+ 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.
+
+<!---
+TODO - list some
+TODO - describe how they can be customised (briefly mention sensors)
+-->
+
+
+### Enrichers
+
+* Delta
+
+ Converts absolute sensor values into a delta.
+
+
+* Time-weighted Delta
+
+ Converts absolute sensor values into a delta/second.
+
+* Rolling Mean
+
+ Converts the last *N* sensor values into a mean.
+
+* Rolling Time-window Mean
+
+ Converts the last *N* seconds of sensor values into a weighted mean.
+
+* Custom Aggregating
+
+ 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.
+
+
+Next: Writing a Policy
+---------------------------
+
+To write a policy, see the section on [Writing a Policy](policy.html).
http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/6e86cb02/guide/java/policy.md
----------------------------------------------------------------------
diff --git a/guide/java/policy.md b/guide/java/policy.md
new file mode 100644
index 0000000..93ad8ba
--- /dev/null
+++ b/guide/java/policy.md
@@ -0,0 +1,77 @@
+---
+layout: website-normal
+title: Writing a Policy
+---
+
+### Your First Policy
+
+Policies perform the active management enabled by Brooklyn.
+Each policy instance is associated with an entity,
+and at runtime it will typically subscribe to sensors on that entity or children,
+performing some computation and optionally actions when a subscribed sensor event occurs.
+This action might be invoking an effector or emitting a new sensor,
+depending the desired behavior is.
+
+Writing a policy is straightforward.
+Simply extend ``AbstractPolicy``,
+overriding the ``setEntity`` method to supply any subscriptions desired:
+
+{% highlight java %}
+ @Override
+ public void setEntity(EntityLocal entity) {
+ super.setEntity(entity)
+ subscribe(entity, TARGET_SENSOR, this)
+ }
+{% endhighlight %}
+
+and supply the computation and/or activity desired whenever that event occurs:
+
+{% highlight java %}
+ @Override
+ public void onEvent(SensorEvent<Integer> event) {
+ int val = event.getValue()
+ if (val % 2 == 1)
+ entity.sayYoureOdd();
+ }
+{% endhighlight %}
+
+
+You'll want to do more complicated things, no doubt,
+like access other entities, perform multiple subscriptions,
+and emit other sensors -- and you can.
+See the best practices below and source code for some commonly used policies and enrichers,
+such as ``AutoScalerPolicy`` and ``RollingMeanEnricher``.
+
+One rule of thumb, to close on:
+try to keep policies simple, and compose them together at runtime;
+for instance, if a complex computation triggers an action,
+define one **enricher** policy to aggregate other sensors and emit a new sensor,
+then write a second policy to perform that action.
+
+
+### Best Practice
+
+The following recommendations should be considered when designing policies:
+
+#### Management should take place as "low" as possible in the hierarchy
+* place management responsibility in policies at the entity, as much as possible ideally management should take run as a policy on the relevant entity
+
+* place escalated management responsibility at the parent entity. Where this is impractical, perhaps because two aspects of an entity are best handled in two different places, ensure that the separation of responsibilities is documented and there is a group membership relationship between secondary/aspect managers.
+
+
+#### Policies should be small and composable
+
+e.g. one policy which takes a sensor and emits a different, enriched sensor, and a second policy which responds to the enriched sensor of the first (e.g. a policy detects a process is maxed out and emits a TOO_HOT sensor; a second policy responds to this by scaling up the VM where it is running, requesting more CPU)
+
+#### Where a policy cannot resolve a situation at an entity, the issue should be escalated to a manager with a compatible policy.
+
+Typically escalation will go to the entity parent, and then cascade up.
+e.g. if the earlier VM CPU cannot be increased, the TOO_HOT event may go to the parent, a cluster entity, which attempts to balance. If the cluster cannot balance, then to another policy which attempts to scale out the cluster, and should the cluster be unable to scale, to a third policy which emits TOO_HOT for the cluster.
+
+#### Management escalation should be carefully designed so that policies are not incompatible
+
+Order policies carefully, and mark sensors as "handled" (or potentially "swallow" them locally), so that subsequent policies and parent entities do not take superfluous (or contradictory) corrective action.
+
+### Implementation Classes
+
+- extend ``AbstractPolicy``, or override an existing policy
http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/6e86cb02/guide/java/service-state.md
----------------------------------------------------------------------
diff --git a/guide/java/service-state.md b/guide/java/service-state.md
new file mode 100644
index 0000000..2abbf65
--- /dev/null
+++ b/guide/java/service-state.md
@@ -0,0 +1,73 @@
+---
+title: Service State
+layout: website-normal
+toc: ../guide_toc.json
+categories: [use, guide, defining-applications]
+---
+
+Any entity can use the standard "service-up" and "service-state"
+sensors to inform other entities and the GUI about its status.
+
+In normal operation, entities should publish at least one "service not-up indicator",
+using the `ServiceNotUpLogic.updateNotUpIndicator` method. Each such indicator should have
+a unique name or input sensor. `Attributes.SERVICE_UP` will then be updated automatically
+when there are no not-up indicators.
+
+When there are transient problems that can be detected, to trigger `ON_FIRE` status
+entity code can similarly set `ServiceProblemsLogic.updateProblemsIndicator` with a unique namespace,
+and subsequently clear it when the problem goes away.
+These problems are reflected at runtime in the `SERVICE_PROBLEMS` sensor,
+allowing multiple problems to be tracked independently.
+
+When an entity is changing the expected state, e.g. starting or stopping,
+the expected state can be set using `ServiceStateLogic.setExpectedState`;
+this expected lifecycle state is considered together with `SERVICE_UP` and `SERVICE_PROBLEMS`
+to compute the actual state. By default the logic in `ComputeServiceState` is applied.
+
+For common entities, good out-of-the-box logic is applied, as follows:
+
+* For `SoftwareProcess` entities, lifecycle service state is updated by the framework
+ and a service not-up indicator is linked to the driver `isRunning()` check.
+
+* For common parents, including `AbstractApplication` and `AbstractGroup` subclasses (including clusters, fabrics, etc),
+ the default enrichers analyse children and members to set a not-up indicator
+ (requiring at least one child or member who is up) and a problem indicator
+ (if any children or members are on-fire).
+ In some cases other quorum checks are preferable; this can be set e.g. by overriding
+ the `UP_QUORUM_CHECK` or the `RUNNING_QUORUM_CHECK`, as follows:
+
+ public static final ConfigKey<QuorumCheck> UP_QUORUM_CHECK = ConfigKeys.newConfigKeyWithDefault(AbstractGroup.UP_QUORUM_CHECK,
+ "Require all children and members to be up for this node to be up",
+ QuorumChecks.all());
+
+ Alternatively the `initEnrichers()` method can be overridden to specify a custom-configured
+ enricher or set custom config key values (as done e.g. in `DynamicClusterImpl` so that
+ zero children is permitted provided when the initial size is configured to be 0).
+
+
+For sample code to set and more information on these methods' behaviours,
+see javadoc in `ServiceStateLogic`,
+overrides of `AbstractEntity.initEnrichers()`
+and tests in `ServiceStateLogicTests`.
+
+<!-- TODO include more documentation, sample code (ideally extracted on the fly from test cases so we know it works!) -->
+
+
+## Notes on Advanced Use
+
+The enricher to derive `SERVICE_UP` and `SERVICE_STATE_ACTUAL` from the maps and expected state values discussed above
+is added by the `AbstractEntity.initEnrichers()` method.
+This method can be overridden -- or excluded altogether by by overriding `init()` --
+and can add enrichers created using the `ServiceStateLogic.newEnricherFromChildren()` method
+suitably customized using methods on the returned spec object, for instance to look only at members
+or specify a quorum function (from `QuorumChecks`).
+If different logic is required for computing `SERVICE_UP` and `SERVICE_STATE_ACTUAL`,
+use `ServiceStateLogic.newEnricherFromChildrenState()` and `ServiceStateLogic.newEnricherFromChildrenUp()`,
+noting that the first of these will replace the enricher added by the default `initEnrichers()`,
+whereas the second one runs with a different namespace (unique tag).
+For more information consult the javadoc on those classes.
+
+Entities can set `SERVICE_UP` and `SERVICE_STATE_ACTUAL` directly.
+Provided these entities never use the `SERVICE_NOT_UP_INDICATORS` and `SERVICE_PROBLEMS` map,
+the default enrichers will not override these values.
+
http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/6e86cb02/guide/java/topology-dependencies-management-policies.md
----------------------------------------------------------------------
diff --git a/guide/java/topology-dependencies-management-policies.md b/guide/java/topology-dependencies-management-policies.md
new file mode 100644
index 0000000..249c99a
--- /dev/null
+++ b/guide/java/topology-dependencies-management-policies.md
@@ -0,0 +1,69 @@
+---
+layout: website-normal
+title: Topology, Dependencies, and Management Policies
+title_in_menu: Topology, Dependencies, and Management Policies
+---
+Of course in the real world, application deployments are more interesting;
+they do things and need configuration. For instance you might need to:
+
+* specify a WAR file
+* initialize the database
+* tell the webapp servers where to find the database
+
+Let's show how these are done using Brooklyn.
+We assume the WAR file and the database init script are accessible
+on the classpath, but a range of URL formats is supported.
+The "dependent inter-process configuration" -- giving the database's URL
+to the webapps -- we'll do here with a JVM system property,
+but you're free to use any mechanism you wish.
+
+Under the covers, ``attributeWhenReady`` is monitoring a sensor from MySQL
+and generating a string to pass to the webapp software processes; ``formatString``
+is a similar utility that returns a string once all of its parts have been resolved.
+Due to the use of futures, the Brooklyn webapp entities will automatically
+block "at the last moment" when the value is needed
+(but after e.g. the VMs have been provisioned, to speed things up).
+
+{% highlight java %}
+public class ClusterWebServerDatabaseSample extends AbstractApplication {
+ @Override
+ public void init() {
+ MySqlNode mysql = addChild(EntitySpec.create(MySqlNode.class)
+ .configure(MySqlNode.CREATION_SCRIPT_URL, "classpath://visitors-database-setup.sql"));
+
+ ControlledDynamicWebAppCluster web = addChild(EntitySpec.create(ControlledDynamicWebAppCluster.class)
+ .configure("memberSpec", EntitySpec.create(JBoss7Server.class)
+ .configure("httpPort", "8080+")
+ .configure("war", WAR_PATH)
+ .configure(JavaEntityMethods.javaSysProp("brooklyn.example.db.url"),
+ formatString("jdbc:%s%s?user=%s\\&password=%s",
+ attributeWhenReady(mysql, MySqlNode.MYSQL_URL), DB_TABLE, DB_USERNAME, DB_PASSWORD))));
+ }
+}
+{% endhighlight %}
+
+We now see our app at the Nginx URL:
+
+[](wt-deployed-application.png)
+
+Finally, we'll bring in some active management: we're going to monitor requests per second,
+and scale out if this exceeds 100 up to a maximum of 5 servers.
+This is a naively simple policy, but it shows Brooklyn's real metier,
+running management policies for applications whose topology it knows.
+
+{% highlight java %}
+ web.getCluster().addPolicy(AutoScalerPolicy.builder().
+ metric(DynamicWebAppCluster.AVERAGE_REQUESTS_PER_SECOND).
+ sizeRange(1, 5).
+ metricRange(10, 100).
+ build());
+{% endhighlight %}
+
+*Policies* in Brooklyn typically subscribe to sensors, perform some computation, and if necessary invoke effectors on entities. This is where the ability to group entities
+becomes very useful -- policies can be attached to group entities, and groups themselves can be hierarchical. It's also handy that often Brooklyn creates the entities,
+so it knows what the hierarchy is.
+
+Under the covers, this ``AutoScalerPolicy`` attaches to any ``Resizable`` entity (exposing a ``resize`` effector), and monitors a specified sensor (or function) attempting to keep it within healthy limits. A separate policy operates at the ``Controlled`` cluster to ensure the load-balancer is updated as the pool of web servers expands and contracts.
+
+Fire up a JMeter session (or other load testing tool) and blast the Nginx address. The auto-scaler policy will scale up the cluster.
+
http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/6e86cb02/guide/java/wt-deployed-application-700.png
----------------------------------------------------------------------
diff --git a/guide/java/wt-deployed-application-700.png b/guide/java/wt-deployed-application-700.png
new file mode 100644
index 0000000..7ef90d9
Binary files /dev/null and b/guide/java/wt-deployed-application-700.png differ
http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/6e86cb02/guide/java/wt-deployed-application.png
----------------------------------------------------------------------
diff --git a/guide/java/wt-deployed-application.png b/guide/java/wt-deployed-application.png
new file mode 100644
index 0000000..751402e
Binary files /dev/null and b/guide/java/wt-deployed-application.png differ
http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/6e86cb02/guide/java/wt-starting-700.png
----------------------------------------------------------------------
diff --git a/guide/java/wt-starting-700.png b/guide/java/wt-starting-700.png
new file mode 100644
index 0000000..c87a539
Binary files /dev/null and b/guide/java/wt-starting-700.png differ
http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/6e86cb02/guide/java/wt-starting.png
----------------------------------------------------------------------
diff --git a/guide/java/wt-starting.png b/guide/java/wt-starting.png
new file mode 100644
index 0000000..970805f
Binary files /dev/null and b/guide/java/wt-starting.png differ
http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/6e86cb02/guide/java/wt-tree-jboss-sensors-700.png
----------------------------------------------------------------------
diff --git a/guide/java/wt-tree-jboss-sensors-700.png b/guide/java/wt-tree-jboss-sensors-700.png
new file mode 100644
index 0000000..3dfc7f2
Binary files /dev/null and b/guide/java/wt-tree-jboss-sensors-700.png differ
http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/6e86cb02/guide/java/wt-tree-jboss-sensors.png
----------------------------------------------------------------------
diff --git a/guide/java/wt-tree-jboss-sensors.png b/guide/java/wt-tree-jboss-sensors.png
new file mode 100644
index 0000000..4c44ea9
Binary files /dev/null and b/guide/java/wt-tree-jboss-sensors.png differ
http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/6e86cb02/guide/misc/download.md
----------------------------------------------------------------------
diff --git a/guide/misc/download.md b/guide/misc/download.md
new file mode 100644
index 0000000..21f201b
--- /dev/null
+++ b/guide/misc/download.md
@@ -0,0 +1,175 @@
+---
+layout: website-normal
+title: Downloads
+---
+{% include fields.md %}
+
+{% if site.brooklyn.is_snapshot %}
+**The downloads on this page have not been voted on and should be used at your own risk.
+The latest stable release can be accessed on the [main download page]({{ site.path.website }}/download/).**
+{% endif %}
+
+
+## Download Version {{ site.brooklyn-version }}
+
+<table class="table">
+ <tr>
+ <th style='text-align:left'>Download</th>
+ <th style='text-align:left'>File/Format</th>
+ <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 ><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>
+ </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>
+ </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>
+ </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).
+
+{% comment %}
+TODO
+<a name="examples"></a>
+
+## Examples
+
+Examples can be found in the main Brooklyn codebase, in the `/examples` directory.
+
+A good example to start with is the [Elastic Web Cluster]({{site.path.guide}}/use/examples/webcluster.html).
+
+{% endcomment %}
+
+<a name="maven"></a>
+
+## Maven
+
+If you use Maven, you can add Brooklyn with the following in your pom:
+
+<!-- the comment is included due to a jekyll/highlight bug which
+ removes indentation on the first line in a highlight block;
+ we want the actual XML indented so you can cut and paste into a pom.xml sensibly -->
+{% highlight xml %}
+<!-- include all Brooklyn items in our project -->
+ <dependencies>
+ <dependency>
+ <groupId>org.apache.brooklyn</groupId>
+ <artifactId>brooklyn-all</artifactId>
+ <version>{{ site.brooklyn-version }}</version>
+ </dependency>
+ </dependencies>
+{% endhighlight %}
+
+`brooklyn-all` brings in all dependencies, including jclouds.
+If you prefer a smaller repo you might want just ``brooklyn-core``, ``brooklyn-policies``,
+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:
+
+{% highlight xml %}
+<!-- include repos for snapshot items and other dependencies -->
+ <repositories>
+ <repository>
+ <id>apache-nexus-snapshots</id>
+ <name>Apache Nexus Snapshots</name>
+ <url>https://repository.apache.org/content/repositories/snapshots</url>
+ <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 %}
+
+{% if SNAPSHOT %}
+**Please note**: to add a snapshot version of Brooklyn as a dependency to your project,
+you must either have Brooklyn built locally or one of these snapshot repositories in your POM.
+{% endif %}
+
+
+<a name="source"></a>
+
+## Source Code
+
+Source code is hosted at [github.com/apache/incubator-brooklyn](http://github.com/apache/incubator-brooklyn),
+with this version in branch [{{ site.brooklyn.git_branch }}]({{ site.brooklyn.url.git }}).
+Information on working with the source is [here]({{ site.path.guide }}/dev/code).
+
+You can download archives of the source directly:
+
+<table class="table">
+ <tr>
+ <td style="vertical-align: middle;"><center>{{ site.brooklyn.git_branch }}</center></td>
+ <td>
+<a href="https://github.com/apache/incubator-brooklyn/tarball/{{ site.brooklyn.git_branch }}"><img border="0" width="90" src="https://github.com/images/modules/download/tar.png"></a>
+<a href="https://github.com/apache/incubator-brooklyn/zipball/{{ site.brooklyn.git_branch }}"><img border="0" width="90" src="https://github.com/images/modules/download/zip.png"></a>
+ </td>
+ </tr>
+{% if site.brooklyn.git_branch != 'master' %}
+ <tr>
+ <td style="vertical-align: middle;"><center>master</center></td>
+ <td>
+<a href="https://github.com/apache/incubator-brooklyn/tarball/master"><img border="0" width="90" src="https://github.com/images/modules/download/tar.png"></a>
+<a href="https://github.com/apache/incubator-brooklyn/zipball/master"><img border="0" width="90" src="https://github.com/images/modules/download/zip.png"></a>
+ </td>
+ </tr>
+{% endif %}
+</table>
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/6e86cb02/guide/misc/index.md
----------------------------------------------------------------------
diff --git a/guide/misc/index.md b/guide/misc/index.md
new file mode 100644
index 0000000..fab2222
--- /dev/null
+++ b/guide/misc/index.md
@@ -0,0 +1,21 @@
+---
+# BROOKLYN_VERSION_BELOW
+title: Other 0.9.0-SNAPSHOT Resources
+layout: website-normal
+children:
+- { title: Javadoc, path: javadoc/ }
+- download.md
+- release-notes.md
+- migrate-to-0.8.0.md
+- known-issues.md
+- { path: ../dev/, title_in_menu: "Developer Guide" }
+- { path: /website/documentation/, title_in_menu: "All Documentation", menu_customization: { force_inactive: true } }
+---
+
+Further documentation specific to this version of Brooklyn includes:
+
+{% for item in page.menu %}
+* [{{ item.title_in_menu }}]({{ item.url }})
+{% endfor %}
+
+Also see the [other versions]({{ site.path.website }}/meta/versions.html) or [general documentation]({{ site.path.website }}/documentation/).
http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/6e86cb02/guide/misc/javadoc/index.md
----------------------------------------------------------------------
diff --git a/guide/misc/javadoc/index.md b/guide/misc/javadoc/index.md
new file mode 100644
index 0000000..5cf9ebc
--- /dev/null
+++ b/guide/misc/javadoc/index.md
@@ -0,0 +1,11 @@
+---
+layout: website-normal
+title: API Reference
+toc: ../../toc.json
+---
+
+*Javadoc is not available as part of this build.*
+
+Please see the [source code]({{site.path.guide}}/dev/code) to view javadoc.
+
+<!-- This page is normally overwritten by generated javadoc. -->
http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/6e86cb02/guide/misc/known-issues.md
----------------------------------------------------------------------
diff --git a/guide/misc/known-issues.md b/guide/misc/known-issues.md
new file mode 100644
index 0000000..db54a06
--- /dev/null
+++ b/guide/misc/known-issues.md
@@ -0,0 +1,27 @@
+---
+layout: website-normal
+title: Known Issues
+---
+
+## Unable to Provision certain types of Debian VMs
+
+*Symptom*: Brooklyn fails to provision Debian VMs (e.g. in aws-ec2).
+
+*Cause*: `sudo` is not available on path, causing Brooklyn to fail to confirm that the VM is ssh'able.
+
+*Workaround*: Choose an image that does have sudo (see [wiki.debian.org/Cloud/AmazonEC2Image](http://wiki.debian.org/Cloud/AmazonEC2Image)).
+
+*Fix*: is [Pull #600](https://github.com/brooklyncentral/brooklyn/pull/600); you may also want to run with `brooklyn.location.jclouds.aws-ec2.user=root` if subsequent commands give permission errors.
+
+*Versions Affected*: 0.5.0-M2
+
+
+### Unable to Provision Ubuntu 8 VMs
+
+*Symptom: Brooklyn fails to provision Ubuntu 8 VMs (e.g. in aws-ec2) with the following error 'Cannot insert the iptables rule for port 22. Error: sudo: illegal option `-n''.
+
+*Cause: Ubuntu 8 is too old; the sudo command doesn't support the -n setting.
+
+*Workaround: Choose Ubuntu 10 or higher.
+
+*Versions Affected*: 0.5.0-M2