Skip to content
Browse files
Reference single MD doc files with an explicit file extension
Signed-off-by: Mykola Mandra <>
  • Loading branch information
algairim committed Sep 3, 2021
1 parent a6dce79 commit e86e38b2f0ec60be5aaea13d17df60bed951769e
Showing 78 changed files with 168 additions and 168 deletions.
@@ -6,7 +6,7 @@ To use the examples, you'll need ``curl``, ``git``, ``java`` (1.6+), and ``maven

### Installing Brooklyn

(If you followed the [Getting Started](/use/guide/quickstart/index.html) instructions, you can skip to Installing the Examples.)
(If you followed the [Getting Started](/use/guide/quickstart/) instructions, you can skip to Installing the Examples.)

{% if SNAPSHOT %}

@@ -47,10 +47,10 @@ Grab a copy of the brooklyn-examples source code and build it with Maven:
{% if SNAPSHOT %}
Please note, these instructions are for a SNAPSHOT release of Brooklyn,
so proceed with caution.
For the latest stable version, go [here](/meta/versions.html).
For the latest stable version, go [here](/meta/
{% endif %}

For more information on ways to download Brooklyn please
see the [download page](/guide/start/download.html).
see the [download page](/guide/start/
For more information on the Brooklyn CLI and launching apps,
please visit [this section of the user guide](/guide/use/guide/management/index.html#cli).
@@ -375,4 +375,4 @@ Here are some questions to think about and code challenges to give you a steer f
between the different clusters.
This isn't for the faint-hearted, but whatever you create will certainly be of interest
to people in the Brooklyn community.
Please [let us know](/guide/meta/contact.html) what you've built!
Please [let us know](/guide/meta/ what you've built!
@@ -279,4 +279,4 @@ If you want to try this with a real example application using the Cassandra clus

## Contact us!

If you encounter any difficulties or have any comments, please [tell us](/guide/meta/contact.html) and we'll do our best to help.
If you encounter any difficulties or have any comments, please [tell us](/guide/meta/ and we'll do our best to help.
@@ -33,18 +33,18 @@ open-sourced here and giving you full control over what you want to happen.
More importantly, however, this code can be shared, improved, and extended.

We're still near the beginning of figuring this out:
[join us to make it better](/guide/meta/contact.html).
[join us to make it better](/guide/meta/

## To Get Started

* See the [developer's walkthrough](/guide/start/walkthrough/index.html) for a quick tour
* See the [developer's walkthrough](/guide/start/walkthrough/) for a quick tour
* Check out the [examples](/guide/use/examples/), from a global web fabric with geo-DNS to a movable PaaS target
* Jump in to the [user guide](/guide/use/guide/) describing the
and including a [tutorial](/guide/use/guide/quickstart/)
* Or dive straight in to the code, either [reading](/guide/dev/code/) about it
or [gitting]( it

If you like it, or if you have ideas how it could be better,
[join the discussion](/guide/meta/contact.html).
[join the discussion](/guide/meta/
@@ -41,7 +41,7 @@ A [BYON location](/guide/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](/guide/start/running) (e.g. with VirtualBox)
A variant of this is to [use Vagrant](/guide/start/ (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.
@@ -14,7 +14,7 @@ uploaded bundles so that they are available after a restart or on HA failover.
The bundle must be a ZIP file including a `` in the root.
(The `br` CLI will create a ZIP from a local folder, for convenience.)
The `` must declare a `bundle` identifier and a `version`,
following Brooklyn's [versioning](versioning) rules.
following Brooklyn's [versioning](versioning.html) rules.
Brooklyn will keep track of that bundle, allowing items to be added and removed as a group,
and associated resources to be versioned and included alongside them.
With SNAPSHOT-version bundles, it allows replacement of multiple related items at the same time,
@@ -75,7 +75,7 @@ this field disambiguates between blueprints of the same `id`.
This can be omitted where the `version` is defined at an ancestor node, and in
practice it usually is, so that all items in a bundle take the same version.
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 [Versioning](/guide/blueprints/catalog/versioning).
but rather the version of the blueprint. For more information on versioning, see [Versioning](/guide/blueprints/catalog/versioning.html).
(Also note YAML treats numbers differently to Strings. Explicit quotes are recommended, to avoid
`1.10` being interpretted as the number `1.1`.)

@@ -189,7 +189,7 @@ To avoid this situation, it is highly recommended to use OSGi version stamps as

Specify `auth` if the resource at `url` requires authentication to access.
Do not write the username and password directly into the file; instead
use [external configuration](/guide/ops/
use [external configuration](/guide/ops/externalized-configuration.html)
to reference the values.

@@ -18,7 +18,7 @@ deployment of our `hello-world-sql` application as follows:

This sets up Nginx as the controller by default, but that can be configured
using the `controllerSpec` key.
This uses the same [externalized config](/guide/ops/externalized-configuration)
This uses the same [externalized config](/guide/ops/externalized-configuration.html)
as in other examples to hide the password.

JBoss is actually the default appserver in the `ControlledDynamicWebAppCluster`,
@@ -92,4 +92,4 @@ A set of sensors are defined for dynamic cluster to feed back information on its
### Policies

Dynamic cluster has a set of policies which can auto-replace and resize the members as well as determine primary nodes and other
higher level actions. These policies are detailed on the [clusters and policies](clusters-and-policies) page.
higher level actions. These policies are detailed on the [clusters and policies]( page.
@@ -18,7 +18,7 @@ ignored if deploying to `localhost` or `byon` fixed-IP machines.*

This will create a VM with the specified parameters in your choice of cloud.
In the GUI (and in the REST API), the entity is called "VM",
and the hostname and IP address(es) are reported as [sensors](/guide/concepts/configuration-sensor-effectors).
and the hostname and IP address(es) are reported as [sensors](/guide/concepts/
There are many more `` supported here,

@@ -10,7 +10,7 @@ categories: [use, guide, defining-applications]
The easiest way to write a blueprint is as a YAML file.
This follows the <a href="">OASIS CAMP</a> plan specification,
with some extensions described below.
(A [YAML reference](yaml-reference) has more information,
(A [YAML reference]( has more information,
and if the YAML doesn't yet do what you want,
it's easy to add new extensions using your favorite JVM language.)

@@ -32,7 +32,7 @@ Here's a very simple YAML blueprint plan, to explain the structure:
This is the meat of the blueprint plan, as you'll see below.

Finally, the clipboard in the top-right corner of the example plan box above (hover your cursor over the box) lets you easily copy-and-paste into the web-console:
simply [download and launch](/guide/start/running) Brooklyn,
simply [download and launch](/guide/start/ Brooklyn,
open a new browser window (usually) at [](
Click on the tile "Blueprint Composer", then on the double-arrow located on the top right of the screen (to switch to the YAML mode),
paste the copied YAML into the editor and press "Deploy".
@@ -65,13 +65,13 @@ Brooklyn lived as a Java framework for many years before we felt confident
to make a declarative front-end, so you can do pretty much anything you want to
by dropping to the JVM. For more information on Java:

* start with a [Maven archetype](/guide/blueprints/java/archetype)
* start with a [Maven archetype](/guide/blueprints/java/
* see all [Brooklyn Java guide](/guide/blueprints/java) topics
* look at test cases in the [codebase](

* review some [examples](/guide/use/examples/index.html)
* review some [examples](/guide/use/examples/)

You can also come talk to us, on IRC (#brooklyncentral on Freenode) or
@@ -227,7 +227,7 @@ before the policy restarts it.
For an even more interesting way to test it, look at the blueprint defining
[a netcat server and client](example_yaml/vanilla-bash-netcat-w-client.yaml).
This uses `brooklyn.initializers`
(see in the [YAML reference](yaml-reference))
(see in the [YAML reference](
to define an effector to `sayHiNetcat` on the `Simple Pinger` client,
using `env` variables to inject the `netcat-server` location and
`parameters` to pass in per-effector data:
@@ -287,7 +287,7 @@ command over ssh every 5 seconds. This can be very CPU intensive when there are
is to disable the ssh-polling (by setting `sshMonitoring.enabled: false`) and to configure a different

See documentation on the [Entity's error status](/guide/ops/troubleshooting/overview#entitys-error-status)
See documentation on the [Entity's error status](/guide/ops/troubleshooting/overview.html#entitys-error-status)
for how Brooklyn models an entity's health.

In the snippet below, we'll define a new health-check sensor (via HTTP polling), and will automatically add this
@@ -4,7 +4,7 @@ layout: website-normal

Effectors perform an operation of some kind, carried out by a Brooklyn Entity.
They can be manually invoked or triggered by a [Policy](/guide/blueprints/policies).
They can be manually invoked or triggered by a [Policy](/guide/blueprints/policies/).

Common uses of an effector include the following:

@@ -57,7 +57,7 @@ for `custom.message`, and will use the given values for `launch.command` and `ch
{% endhighlight yaml %}

For details of how to write and add catalog items, see [Catalog](/guide/blueprints/catalog),
and for a complete reference on the syntax of `brooklyn.parameters` see that section of the [YAML Reference](/guide/blueprints/yaml-reference).
and for a complete reference on the syntax of `brooklyn.parameters` see that section of the [YAML Reference](/guide/blueprints/yaml-reference.html).

#### Config Key Constraints
@@ -37,7 +37,7 @@ It is vital that these jars are built correctly as OSGi bundles, and that all tr
dependencies are included. The bundles will be added to Karaf in the order given, so a bundle's
dependencies should be listed before the bundle(s) that depend on them.

In the [GistGenerator example](/guide/blueprints/java/defining-and-deploying), the
In the [GistGenerator example](/guide/blueprints/java/defining-and-deploying.html), the
[ file](/guide/blueprints/java/gist_generator/ included
the URL of the dependency `org.eclipse.egit.github.core`. It also (before that line) included
its transitive dependency, which is a specific version of `gson`.
@@ -119,7 +119,7 @@ inside `src/test/java`.

Again you will need to substitute the github access token you generated in the previous section for
the placeholder text `xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx`. See the section on
[externalised configuration](/guide/ops/externalized-configuration)
[externalised configuration](/guide/ops/
for how to store these credentials more securely.

{% highlight java %}
@@ -31,7 +31,7 @@ which you can see [here]({{ site.brooklyn.url.git }}/core/src/test/java/org/apac
and include in your project by adding the core tests JAR to your `dropins` folder.

There are some entitlements schemes which exist out of the box, so for a simpler setup,
see [Operations: Entitlements](/guide/ops/configuration/brooklyn_cfg#entitlements).
see [Operations: Entitlements](/guide/ops/configuration/

There are also more complex schemes which some users have developed, including LDAP extensions
which re-use the LDAP authorization support in Brooklyn,
@@ -17,7 +17,7 @@ There are several ways to write a new entity:
* Use **[Salt formulas](/guide/blueprints/salt)**.
* Use **[Ansible playbooks](/guide/blueprints/ansible)**.
* Write pure-java, extending existing base-classes. For example, the `GistGenerator`
[example](defining-and-deploying). These can use utilities such as `HttpTool` and
[example]( These can use utilities such as `HttpTool` and
* Write pure-Java blueprints that extend `SoftwareProcess`. However, the YAML approach is strongly
recommended over this approach.
@@ -11,7 +11,7 @@ recommended.

The example below creates a three tier web service, composed of an Nginx load-balancer,
a cluster of Tomcat app-servers, and a MySQL database. It is similar to the [YAML policies
example](/guide/start/policies), but also includes the MySQL database
example](/guide/start/, but also includes the MySQL database
to demonstrate the use of dependent configuration.

{% highlight java %}
@@ -43,7 +43,7 @@ Here there are a few things going on:
* We've injected the URL of the second service into the appserver as a Java system property
(so our app knows where to find the database)
* We've used externalized config to keep secret information out of the blueprint;
this is loaded at runtime from an [externalized config provider](../ops/externalized-config.html),
this is loaded at runtime from an [externalized config provider](../ops/,
such as a remote credentials store

**Caution: Be careful if you write your YAML in an editor which attempts to put "smart-quotes" in.
@@ -50,7 +50,7 @@ brooklyn.policies:
{% endhighlight %}

Typically this is used in conjunction with the ServiceFailureDetector enricher to emit the trigger sensor.
The [introduction to policies](/guide/start/policies) shows a worked
The [introduction to policies](/guide/start/ shows a worked
example of these working together.

@@ -60,7 +60,7 @@ example of these working together.

The ServiceReplacer attaches to a DynamicCluster and replaces a failed member in response to
`ha.entityFailed` (or other configurable sensor) as typically emitted by the ServiceFailureDetector enricher.
The [introduction to policies](/guide/start/policies) shows a worked
The [introduction to policies](/guide/start/ shows a worked
example of this policy in use.

@@ -70,7 +70,7 @@ example of this policy in use.

The ServiceFailureDetector enricher detects problems and fires an `ha.entityFailed` (or other configurable sensor)
for use by ServiceRestarter and ServiceReplacer.
The [introduction to policies](/guide/start/policies) shows a worked
The [introduction to policies](/guide/start/ shows a worked
example of this in use.

@@ -120,7 +120,7 @@ the User Guide.
### Externalized Configuration

For simplicity, the examples above have included the cloud credentials. For a production system,
it is strongly recommended to use [Externalized Configuration](/guide/ops/externalized-configuration)
it is strongly recommended to use [Externalized Configuration](/guide/ops/
to retrieve the credentials from a secure credentials store, such as [Vault](

@@ -7,7 +7,7 @@ layout: website-normal
{% include %}

## Introduction
This section describes some simple tests based on the [Getting Started](/guide/start/blueprints#launching-from-a-blueprint) example blueprint:
This section describes some simple tests based on the [Getting Started](/guide/start/ example blueprint:

{% highlight yaml %}
{% read /guide/start/_my-web-cluster.yaml %}
@@ -123,5 +123,5 @@ Use an Apache Brooklyn BYON blueprint to try easily other connection options.
1. Restart WinRM on both machines (some changes need a restart to take effect): `Restart-Service WinRM`
1. If you want to configure Windows target host with HTTPS then check the article [Configuring WINRM for HTTPS](

In some cases the problems may be outwith the client, and it might be useful to look at [Troubleshooting](troubleshoot).
In some cases the problems may be outwith the client, and it might be useful to look at [Troubleshooting](

@@ -23,7 +23,7 @@ Management](

WinRM is available by default in Windows Server, but is not enabled by default. Brooklyn will, in most cases, be able
to switch on WinRM support, but this is dependent on your cloud provider supporting a user metadata service with script
execution (see [below](/guide/blueprints/winrm/troubleshoot#user-metadata-service-requirement))
execution (see [below](/guide/blueprints/winrm/

Locations for Windows
@@ -73,7 +73,7 @@ A Sample Blueprint

Creating a Windows VM is done using the `` entity type. This is very similar
to `VanillaSoftwareProcess`, but adapted to work for Windows and WinRM instead of Linux. We suggest you read the
[documentation for VanillaSoftwareProcess](/guide/blueprints/custom-entities#vanilla-software-using-bash) to find out what you
[documentation for VanillaSoftwareProcess](/guide/blueprints/ to find out what you
can do with this entity.

Entity authors are strongly encouraged to write Windows PowerShell or Batch scripts as separate
@@ -116,8 +116,8 @@ Learn More

A few other WinRM resources are available:

* [Tips and Tricks](tips)
* [About the Winrm4j Client](client)
* [Troubleshooting](troubleshoot)
* [Limitations](limitations)
* [Tips and Tricks](
* [About the Winrm4j Client](
* [Troubleshooting](
* [Limitations](

@@ -14,7 +14,7 @@ For a given phase, only one of the commands (PowerShell or Batch) should be supp
### Execution Phases

Bear in mind that
the best practices for other entities (e.g. using [VanillaSoftwareProcess](/guide/blueprints/custom-entities#vanilla-software-using-bash))
the best practices for other entities (e.g. using [VanillaSoftwareProcess](/guide/blueprints/
apply for WinRM as well.

Blueprint authors are strongly encouraged to provide an implementation for install, launch, stop
@@ -51,7 +51,7 @@ command line or in a script, cmdlet, or provider, such as the
errors generated by the Write-Error cmdlet.

See [Incorrect Exit Codes](limitations#incorrect-exit-codes) under Known Limitations.
See [Incorrect Exit Codes]( under Known Limitations.

### Executing Scripts From Batch Commands
@@ -156,7 +156,7 @@ Re-authentication also requires that the password credentials are passed in plai
script. Please be aware that it is normal for script files - and therefore the plaintext password -
to be saved to the VM's disk. The scripts are also accessible via the Brooklyn web-console's
activity view. Access to the latter can be controlled via

As an example (taken from MSSQL install), the command below works when run locally, but fails over

0 comments on commit e86e38b

Please sign in to comment.