You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@brooklyn.apache.org by m4...@apache.org on 2017/04/19 08:56:33 UTC
[04/14] brooklyn-docs git commit: Refactor Blueprinting
http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/f38b9e7b/guide/ops/locations/_ssh-keys.md
----------------------------------------------------------------------
diff --git a/guide/ops/locations/_ssh-keys.md b/guide/ops/locations/_ssh-keys.md
deleted file mode 100644
index acf30d7..0000000
--- a/guide/ops/locations/_ssh-keys.md
+++ /dev/null
@@ -1,88 +0,0 @@
----
-section: SSH Keys
-section_position: 9
-section_type: inline
----
-
-### SSH Keys
-
-SSH keys are one of the simplest and most secure ways to access remote servers.
-They consist of two parts:
-
-* A private key (e.g. `id_rsa`) which is known only to one party or group
-
-* A public key (e.g. `id_rsa.pub`) which can be given to anyone and everyone,
- and which can be used to confirm that a party has a private key
- (or has signed a communication with the private key)
-
-In this way, someone -- such as you -- can have a private key,
-and can install a public key on a remote machine (in an `authorized_keys` file)
-for secure automated access.
-Commands such as `ssh` (and Brooklyn) can log in without
-revealing the private key to the remote machine,
-the remote machine can confirm it is you accessing it (if no one else has the private key),
-and no one snooping on the network can decrypt of any of the traffic.
-
-
-#### Creating an SSH Key
-
-If you don't have an SSH key, create one with:
-
-{% highlight bash %}
-$ ssh-keygen -t rsa -N "" -f ~/.ssh/id_rsa
-{% endhighlight %}
-
-
-#### Localhost Setup
-
-If you want to deploy to `localhost`, ensure that you have a public and private key,
-and that your key is authorized for ssh access:
-
-{% highlight bash %}
-# _Appends_ id_rsa.pub to authorized_keys. Other keys are unaffected.
-$ cat ~/.ssh/id_rsa.pub >> ~/.ssh/authorized_keys
-{% endhighlight %}
-
-Now verify that your setup by running the command: `ssh localhost echo hello world`
-
-If your setup is correct, you should see `hello world` printed back at you.
-
-On the first connection, you may see a message similar to this:
-
-<pre>
-The authenticity of host 'localhost (::1)' can't be established.
-RSA key fingerprint is 7b:e3:8e:c6:5b:2a:05:a1:7c:8a:cf:d1:6a:83:c2:ad.
-Are you sure you want to continue connecting (yes/no)?
-</pre>
-
-Simply answer 'yes' and then repeat the command again.
-
-If this isn't the case, see below.
-
-
-
-
-#### Potential Problems
-
-* **MacOS user?** In addition to the above, enable "Remote Login" in "System Preferences > Sharing".
-
-* **Got a passphrase?** Set `brooklyn.location.localhost.privateKeyPassphrase`
- as described [here](index.html#os-setup).
- If you're not sure, or you don't know what a passphrase is, you can test this by executing `ssh-keygen -y`.
- If it does *not* ask for a passphrase, then your key has no passphrase.
- If your key does have a passphrase, you can remove it by running `ssh-keygen -p`.
-
-* Check that you have an `~/.ssh/id_rsa` file (or `id_dsa`) and a corresponding public key with a `.pub` extension;
- if not, create one as described above
-
-* `~/.ssh/` or files in that directory may have permissions they shouldn't:
- they should be visible only to the user (apart from public keys),
- both on the source machine and the target machine.
- You can verify this with `ls -l ~/.ssh/`: lines should start with `-rw-------` or `-r--------` (or `-rwx------` for directories).
- If it does not, execute `chmod go-rwx ~/.ssh ~/.ssh/*`.
-
-* Sometimes machines are configured with different sets of support SSL/TLS versions and ciphers;
- if command-line `ssh` and `scp` work, but Brooklyn/java does not, check the versions enabled in Java and on both servers.
-
-* Missing entropy: creating and using ssh keys requires randomness available on the servers,
- usually in `/dev/random`; see [here]({{ site.path.guide }}/ops/troubleshooting/increase-entropy.html) for more information
http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/f38b9e7b/guide/ops/locations/cloud-credentials.md
----------------------------------------------------------------------
diff --git a/guide/ops/locations/cloud-credentials.md b/guide/ops/locations/cloud-credentials.md
deleted file mode 100644
index 36041e0..0000000
--- a/guide/ops/locations/cloud-credentials.md
+++ /dev/null
@@ -1,6 +0,0 @@
----
-title: More Clouds
-layout: website-normal
----
-
-This page has moved. See [More Clouds](index.html#more-details-on-specific-clouds) instead.
http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/f38b9e7b/guide/ops/locations/index.md
----------------------------------------------------------------------
diff --git a/guide/ops/locations/index.md b/guide/ops/locations/index.md
deleted file mode 100644
index 4a8b40d..0000000
--- a/guide/ops/locations/index.md
+++ /dev/null
@@ -1,21 +0,0 @@
----
-title: Locations
-layout: website-normal
-children:
-- { path: location-customizers.md, section_position: 8 }
-check_directory_for_children: true
----
-
-Locations are the environments to which Brooklyn deploys applications. Most commonly these
-are cloud services such as AWS, GCE, and IBM Softlayer. Brooklyn also supports deploying
-to a pre-provisioned network or to localhost (primarily useful for testing blueprints).
-
-See also:
-
-* The [Locations yaml guide]({{ site.path.guide }}/yaml/setting-locations.html)
-* Use within an entity of the configuration option
- [provisioning.properties]({{ site.path.guide }}/yaml/entity-configuration.html#entity-provisioningproperties-overriding-and-merging)
-* How to add location definitions to the [Catalog]({{ site.path.guide }}/ops/catalog/); and
-* How to use [Externalized Configuration]({{ site.path.guide }}/ops/externalized-configuration.html).
-
-{% child_content %}
http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/f38b9e7b/guide/ops/locations/location-customizers.md
----------------------------------------------------------------------
diff --git a/guide/ops/locations/location-customizers.md b/guide/ops/locations/location-customizers.md
deleted file mode 100644
index 405bb14..0000000
--- a/guide/ops/locations/location-customizers.md
+++ /dev/null
@@ -1,169 +0,0 @@
----
-title: Location Customizers
-layout: website-normal
----
-
-Apache Brooklyn supports a number of ways to configure and customize locations. These include
-the `JcloudsLocationCustomizer`, which is for advanced customization of VM provisioning through jclouds.
-There is also a `MachineLocationCustomizer`, which allows customization of machines being obtained
-from any kind of location (including [Bring Your Own Nodes](index.html#byon)).
-
-
-## Usage Guidelines
-
-Clearly there is an overlap for where things can be done. This section describes the recommended
-separation of responsibilities.
-
-These are guidelines only - users are obviously free to make alternative usage decisions based on
-their particular use-cases.
-
-### Responsibilities of Entity versus Location
-
-From an entity's perspective, it calls `location.obtain(options)` and gets back a usable
-`MachineLocation` that has a standard base operating system that gives remote access
-(e.g. for Linux it expects credentials for a user with `sudo` rights, and ssh access).
-
-However, there are special cases - for example the `location.obtain(options)` could return
-a Docker container with the software pre-installed, and no remote access (see the
-[Clocker project](http://clocker.io) for more information on use of Docker with Brooklyn).
-
-The entity is then responsible for configuring that machine according to the needs of the software
-to be installed.
-
-For example, the entity may install software packages, upload/update configuration files, launch
-processes, etc.
-
-The entity may also configure `iptables`. This is also possible through the `JcloudsLocation`
-configuration. However, it is preferable to do this in the entity because it is part of
-configuring the machine in the way required for the given software component.
-
-The entity may also perform custom OS setup, such as installing security patches. However, whether
-this is appropriate depends on the nature of the security patch: if the security patch is specific
-to the entity type, then it should be done within the entity; but if it is to harden the base OS
-to make it comply with an organisation's standards (e.g. to overcome shortcomings of the base
-image, or to install security patches) then a `MachineLocationCustomizer` is more appropriate.
-
-### Location Configuration Options
-
-This refers to standard location configuration: explicit config keys, and explicit jclouds template
-configuration that can be passed through.
-
-This kind of configuration is simplest to use. It is the favoured mechanism when it comes to VM
-provisioning, and should be used wherever possible.
-
-Note that a jclouds `TemplateBuilder` and cloud-specific `TemplateOptions` are the generic mechanisms
-within jclouds for specifying the details of the compute resource to be provisioned.
-
-### Jclouds Location Customizer
-A `JcloudsLocationCustomizer` has customization hooks to execute code at the various points of building
-up the jclouds template and provisioning the machine. Where jclouds is being used and where the required
-use of jclouds goes beyond simple configuration, this is an appropriate solution.
-
-For example, there is a `org.apache.brooklyn.location.jclouds.networking.JcloudsLocationSecurityGroupCustomizer`
-which gives more advanced support for setting up security groups (e.g. in AWS-EC2).
-
-### Machine Customizer
-
-The `MachineLocationCustomizer` allows customization of machines being obtained from any kind of location.
-For example, this includes for jclouds and for Bring Your Own Nodes (BYON).
-
-It provides customization hooks for when the machine has been provisioned (before it is returned by the location)
-and when the machine is about to be released by the location.
-
-An example use would be to register (and de-register) the machine in a CMDB.
-
-
-## Jclouds Location Customizers
-
-*Warning: additional methods (i.e. customization hooks) may be added to the `JcloudsLocationCustomizer`
-interface in future releases. Users are therefore strongly encouraged to sub-class
-`BasicJcloudsLocationCustomizer`, rather than implementing JcloudsLocationCustomizer directly.*
-
-The `JcloudsLocationCustomizer` provides customization hooks at various points of the Brooklyn's
-use of jclouds. These can be used to adjust the configuration, to do additional setup, to do
-custom logging, etc.
-
-* Customize the `org.jclouds.compute.domain.TemplateBuilder`, before it is used to build the template.
- This is used to influence the choice of VM image, hardware profile, etc. This hook is not normally
- required as the location configuration options can be used in instead.
-
-* Customize the `org.jclouds.compute.domain.Template`, to be used when creating the machine. This
- hook is most often used for performing custom actions - for example to create or modify a security
- group or volume, and to update the template's options to use that.
-
-* Customize the `org.jclouds.compute.options.TemplateOptions` to be used when creating the machine.
- The `TemplateOptions` could be cast to a cloud-specific sub-type (if this does not have to work
- across different clouds). Where the use-case is to just set simple configuration on the
- `TemplateOptions`, consider instead using the config key `templateOptions`, which takes a map
- of type String to Object - the strings should match the method names in the `TemplateOptions`.
-
-* Customize the `org.apache.brooklyn.location.jclouds.JcloudsMachineLocation` that has been
- created. For Linux-based VMs, if the config `waitForSshable` was not false, then this machine
- is guaranteed to be ssh'able. Similarly for WinRM access to Windows machines, if
- `waitForWinRmAvailable` was not false.
-
-* Pre-release of the machine. If the actions required are specific to jclouds (e.g. using jclouds
- to make calls to the cloud provider) then this should be used; otherwise one should use the more
- generic `MachineLocationCustomizer`.
-
-* Post-release of the machine (i.e. after asking jclouds to destroying the machine).
-
-To register a `JcloudsLocationCustomizer` in YAML, the config key `customizers` can be used to
-provide a list of instances. Each instance can be defined using `$brooklyn:object` to indicate
-the type and its configuration. For example:
-
- location:
- jclouds:aws-ec2:us-east-1:
- customizers:
- - $brooklyn:object:
- type: com.acme.brooklyn.MyJcloudsLocationCustomizer
-
-To register `JcloudsLocationCustomizer` instances programmatically, set the config key
-`JcloudsLocationConfig.JCLOUDS_LOCATION_CUSTOMIZERS` on the location, or pass this
-config option when calling `location.obtain(options)`.
-
-
-The `SharedLocationSecurityGroupCustomizer` configures a shared security group on Jclouds locations.
-It only works on AWS and Azure ARM.
-
-To register a `SharedLocationSecurityGroupCustomizer` in YAML, you can use the config key `customizers`
-and configure it with `$brooklyn:object` and `object.fields`. For example:
-
- location:
- jclouds:aws-ec2:us-east-1:
- customizers:
- - $brooklyn:object:
- type: org.apache.brooklyn.location.jclouds.networking.SharedLocationSecurityGroupCustomizer
- object.fields: {locationName: "myloc", tcpPortRanges: ["22", "8080", "9443"], udpPortRanges: ["2001", "4013"], cidr: "82.40.153.101/24"}
-
-where `cidr` can be optionally set to restrict the range that the ports that are to be opened can be accessed from.
-
-
-
-## Machine Location Customizers
-
-*Warning: additional methods (i.e. customization hooks) may be added to the `MachineLocationCustomizer`
-interface in future releases. Users are therefore strongly encouraged to sub-class
-`BasicMachineLocationCustomizer`, rather than implementing `MachineLocationCustomizer` directly.*
-
-The `MachineLocationCustomizer` provides customization hooks for when a machine is obtained/released
-from a `MachineProvisioningLocation`. The following hooks are supported:
-
-* After the machine has been provisioned/allocated, but before it has been returned.
-
-* When the machine is about to be released, but prior to actually destroying/unallocating the
- machine.
-
-To register a `MachineLocationCustomizer` in YAML, the config key `machineCustomizers` can be used
-to provide a list of instances. Each instance can be defined using `$brooklyn:object` to indicate
-the type and its configuration. For example:
-
- location:
- jclouds:aws-ec2:us-east-1:
- machineCustomizers:
- - $brooklyn:object:
- type: com.acme.brooklyn.MyMachineLocationCustomizer
-
-To register `MachineLocationCustomizer` instances programmatically, set the config key
-`CloudLocationConfig.MACHINE_LOCATION_CUSTOMIZERS` on the location, or pass this
-config option when calling `location.obtain(options)`.
http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/f38b9e7b/guide/ops/persistence/index.md
----------------------------------------------------------------------
diff --git a/guide/ops/persistence/index.md b/guide/ops/persistence/index.md
index a565fbb..4d19062 100644
--- a/guide/ops/persistence/index.md
+++ b/guide/ops/persistence/index.md
@@ -313,7 +313,7 @@ Behaviour on rebind:
* By extending `SoftwareProcess`, entities get a lot of the rebind logic for free. For
example, the default `rebind()` method will call `connectSensors()`.
- See [`SoftwareProcess` Lifecycle]({{site.path.guide}}/java/entities.html#SoftwareProcess-lifecycle)
+ See [`SoftwareProcess` Lifecycle]({{site.path.guide}}/blueprints/java/entities.html#SoftwareProcess-lifecycle)
for more details.
* If necessary, implement rebind. The `entity.rebind()` is called automatically by the
Brooklyn framework on rebind, after configuring the entity's config/attributes but before
http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/f38b9e7b/guide/ops/production-installation.md
----------------------------------------------------------------------
diff --git a/guide/ops/production-installation.md b/guide/ops/production-installation.md
index 517f6ef..e1ef8cd 100644
--- a/guide/ops/production-installation.md
+++ b/guide/ops/production-installation.md
@@ -27,8 +27,8 @@ 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/index.html#ssh-keys), if not available
-* if the "localhost" location will be used, enable [passwordless ssh login]({{ site.path.guide }}/ops/locations/index.html#ssh-keys)
+* install an [SSH key]({{ site.path.guide }}/locations/index.html#ssh-keys), if not available
+* if the "localhost" location will be used, enable [passwordless ssh login]({{ site.path.guide }}/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.guide }}/ops/troubleshooting/increase-entropy.html) is sufficient
http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/f38b9e7b/guide/start/blueprints.md
----------------------------------------------------------------------
diff --git a/guide/start/blueprints.md b/guide/start/blueprints.md
index 3ebc717..509f31d 100644
--- a/guide/start/blueprints.md
+++ b/guide/start/blueprints.md
@@ -63,7 +63,7 @@ location:
</div>
<div id="impl-2" class="tab-pane fade">
-Apache Brooklyn uses [Apcahe jclouds](http://jclouds.apache.org/){:target="_blank"} to support a range of cloud locations. More information on the range of providers and configurations is available [here]({{ site.path.guide }}/ops/locations/#clouds){:target="_blank"}.
+Apache Brooklyn uses [Apcahe jclouds](http://jclouds.apache.org/){:target="_blank"} to support a range of cloud locations. More information on the range of providers and configurations is available [here]({{ site.path.guide }}/locations/#clouds){:target="_blank"}.
As an example, here is a configuration for [Amazon Web Services (AWS)](http://www.aws.amazon.com){:target="_blank"}. Swap the identity and credential with your AWS account details, then replace the location in your "myapp.yaml" with this.
@@ -77,7 +77,7 @@ location:
</div>
<div id="impl-3" class="tab-pane fade">
-The Bring Your Own Nodes (BYON) configuration allows Apache Brooklyn to make use of already available servers. These can be specified by a list of IP addresses with a user and password as shown below. More information including the full range of configuration options is available [here]({{ site.path.guide }}/ops/locations/#byon){:target="_blank"}.
+The Bring Your Own Nodes (BYON) configuration allows Apache Brooklyn to make use of already available servers. These can be specified by a list of IP addresses with a user and password as shown below. More information including the full range of configuration options is available [here]({{ site.path.guide }}/locations/#byon){:target="_blank"}.
Replace the hosts, user and password in the example below with your own server details, then replace the location in your "myapp.yaml" with this.
@@ -98,7 +98,7 @@ location:
---
-**Note**: For instructions on setting up a variety of locations or storing credentials/locations in a file on disk rather than in the blueprint, see __[Locations]({{ site.path.guide }}/ops/locations)__ in the Operations section of the User Guide.
+**Note**: For instructions on setting up a variety of locations or storing credentials/locations in a file on disk rather than in the blueprint, see __[Locations]({{ site.path.guide }}/locations)__ in the Operations section of the User Guide.
## Deploying the Application
http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/f38b9e7b/guide/start/brooklyn.properties
----------------------------------------------------------------------
diff --git a/guide/start/brooklyn.properties b/guide/start/brooklyn.properties
index 8714364..cecd292 100644
--- a/guide/start/brooklyn.properties
+++ b/guide/start/brooklyn.properties
@@ -97,7 +97,7 @@
############################ Deploying to Localhost #####################################
## Deploying to Localhost
-## see: info on locations at http://brooklyn.apache.org/v/latest/ops/locations/index.html#localhost
+## see: info on locations at http://brooklyn.apache.org/v/latest/locations/index.html#localhost
##
## Brooklyn defaults to using ~/.ssh/id_rsa, if it exists.
# brooklyn.location.localhost.privateKeyFile = ~/.ssh/id_rsa
http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/f38b9e7b/guide/start/running.md
----------------------------------------------------------------------
diff --git a/guide/start/running.md b/guide/start/running.md
index 9a421e4..75f00cd 100644
--- a/guide/start/running.md
+++ b/guide/start/running.md
@@ -140,7 +140,7 @@ to configure security. Documentation of configuration options include:
* [Security]({{ site.path.guide }}/ops/brooklyn_properties.html)
* [Persistence]({{ site.path.guide }}/ops/persistence/)
-* [Cloud credentials]({{ site.path.guide }}/ops/locations/)
+* [Cloud credentials]({{ site.path.guide }}/locations/)
## Launch Apache Brooklyn
http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/f38b9e7b/guide/start/running/control.md
----------------------------------------------------------------------
diff --git a/guide/start/running/control.md b/guide/start/running/control.md
new file mode 100644
index 0000000..29e403d
--- /dev/null
+++ b/guide/start/running/control.md
@@ -0,0 +1,25 @@
+---
+section: Control Apache Brooklyn
+section_type: inline
+section_position: 3
+---
+
+## Control Apache Brooklyn
+
+Apache Brooklyn has a web console which can be used to control the application. The Brooklyn log will contain the
+address of the management interface:
+
+<pre>
+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.
+
+The rest of this getting started guide uses the Apache Brooklyn command line interface (CLI) tool, `br`.
+This tool is both distributed with Apache Brooklyn or can be downloaded using the most appropriate link for your OS:
+
+* [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)
+
+For details on the CLI, see the [Client CLI Reference](../ops/cli/) page.
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/f38b9e7b/guide/start/running/index.md
----------------------------------------------------------------------
diff --git a/guide/start/running/index.md b/guide/start/running/index.md
new file mode 100644
index 0000000..ce923d1
--- /dev/null
+++ b/guide/start/running/index.md
@@ -0,0 +1,28 @@
+---
+title: Running Apache Brooklyn
+title_in_menu: Running Apache Brooklyn
+layout: website-normal
+menu_parent: /guide/start/index.md
+---
+
+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.
+
+To get you up-and-running quickly, the Vagrant option will provision four compute nodes for you to deploy applications to.
+
+
+{% child_content %}
+
+
+## Next
+
+<div class="started-pdf-exclude">
+
+The first thing we want to do with Brooklyn is **[deploy a blueprint](blueprints.html)**.
+
+</div>
http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/f38b9e7b/guide/start/running/install.md
----------------------------------------------------------------------
diff --git a/guide/start/running/install.md b/guide/start/running/install.md
new file mode 100644
index 0000000..ae787ca
--- /dev/null
+++ b/guide/start/running/install.md
@@ -0,0 +1,101 @@
+---
+section: Install Apache Brooklyn
+section_type: inline
+section_position: 1
+---
+
+## Install Apache Brooklyn
+
+{::options parse_block_html="true" /}
+
+<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>
+</ul>
+
+<div class="tab-content">
+<div id="impl-1" class="tab-pane fade in active">
+
+<strong class="hidden started-pdf-include">a) Vagrant</strong>
+
+[Vagrant](https://www.vagrantup.com/){:target="_blank"} is a software package which automates the process of setting up virtual machines (VM) such as [Oracle VirtualBox](https://www.virtualbox.org){:target="_blank"}. We recommend it as the easiest way of getting started with Apache Brooklyn.
+
+Firstly, download and install:
+
+ * [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.
+
+Extract the `tar.gz` archive and navigate into the expanded `apache-brooklyn-{{site.brooklyn-version}}-vagrant` folder
+
+{% highlight bash %}
+$ tar xvf apache-brooklyn-{{site.brooklyn-version}}-vagrant.tar.gz
+$ cd apache-brooklyn-{{site.brooklyn-version}}-vagrant
+{% endhighlight %}
+
+
+</div>
+<div id="impl-2" class="tab-pane fade">
+
+<strong class="hidden started-pdf-include">b) Centos / RHEL 7</strong>
+
+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"}.
+
+Once downloaded, run the following shell command as root:
+
+{% highlight bash %}
+$ yum install apache-brooklyn-{{site.brooklyn-version}}-1.rpm
+{% endhighlight %}
+
+</div>
+<div id="impl-3" class="tab-pane fade">
+
+<strong class="hidden started-pdf-include">c) 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' %}
+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' %}
+{% highlight bash %}
+$ tar -zxf apache-brooklyn-dist-{{ site.brooklyn-version }}-timestamp-dist.tar.gz
+$ cd apache-brooklyn-{{ site.brooklyn.version }}
+{% endhighlight %}
+{% else %}
+{% highlight bash %}
+$ tar -zxf apache-brooklyn-{{ site.brooklyn-version }}-dist.tar.gz
+$ cd apache-brooklyn-{{ site.brooklyn.version }}
+{% endhighlight %}
+{% endif %}
+
+</div>
+<div id="impl-4" class="tab-pane fade">
+
+<strong class="hidden started-pdf-include">d) Windows</strong>
+
+For all versions of Microsoft Windows, please download the Apache Brooklyn zip file from [here]({{site.path.website}}/download/){:target="_blank"}.
+
+Extract this zip file to a directory on your computer such as `c:\Program Files\brooklyn` where `c` is the letter of your operating system drive.
+
+</div>
+</div>
+
+---
+
+It is not necessary at this time, but depending on what you are going to do,
+you may wish to set up other configuration options first:
+
+* [Security](../ops/brooklyn_properties.html)
+* [Persistence](../ops/persistence/)
+* [Cloud credentials](../locations/)
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/f38b9e7b/guide/start/running/launch.md
----------------------------------------------------------------------
diff --git a/guide/start/running/launch.md b/guide/start/running/launch.md
new file mode 100644
index 0000000..4f9ce31
--- /dev/null
+++ b/guide/start/running/launch.md
@@ -0,0 +1,72 @@
+---
+section: Launch Apache Brooklyn
+section_type: inline
+section_position: 2
+---
+
+## Launch Apache Brooklyn
+
+<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>
+</ul>
+
+<div class="tab-content">
+<div id="impl-1" class="tab-pane fade in active">
+
+<strong class="hidden started-pdf-include">a) Vagrant</strong>
+
+Now start Apache Brooklyn with the following command:
+
+{% highlight bash %}
+$ vagrant up brooklyn
+{% endhighlight %}
+
+You can see if Apache Brooklyn launched OK by viewing the log files with the command
+
+{% highlight bash %}
+$ vagrant ssh brooklyn --command 'sudo journalctl -n15 -f -u brooklyn'
+{% endhighlight %}
+
+
+</div>
+<div id="impl-2" class="tab-pane fade">
+
+<strong class="hidden started-pdf-include">b) Centos / RHEL 7</strong>
+
+Apache Brooklyn should now have been installed and be running as a system service. It can stopped and started with the standard systemctl commands:
+
+{% highlight bash %}
+$ systemctl start|stop|restart|status brooklyn
+{% 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-3" class="tab-pane fade">
+
+<strong class="hidden started-pdf-include">c) OSX / Linux</strong>
+
+Now start Apache Brooklyn with the following command:
+
+{% highlight bash %}
+$ bin/brooklyn launch
+{% endhighlight %}
+
+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">
+
+<strong class="hidden started-pdf-include">d) 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>
+</div>
+
+---
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/f38b9e7b/guide/yaml/advanced-example.md
----------------------------------------------------------------------
diff --git a/guide/yaml/advanced-example.md b/guide/yaml/advanced-example.md
deleted file mode 100644
index 6513191..0000000
--- a/guide/yaml/advanced-example.md
+++ /dev/null
@@ -1,283 +0,0 @@
----
-title: YAML Blueprint Advanced Example
-layout: website-normal
----
-
-By this point you should be familiar with the fundamental concepts behind both Apache Brooklyn and YAML blueprints. This section of the documentation is intended to show a complete, advanced example of a YAML blueprint.
-
-The intention is that this example is used to learn the more in-depth concepts, and also to serve as a reference when writing your own blueprints. This page will first explain what the example application is and how to run it, then it will spotlight interesting features.
-
-
-### ELK Stack Example
-
-This example demonstrates the deployment of an ELK Stack (Elasticsearch, Logstash and Kibana), using the provided blueprint to deploy, install, run and manage all three. Briefly, the component parts are:
-
-* Elasticsearch: A clustered search engine
-* Logstash: Collects, parses and stores logs. For our example it will store logs in Elasticsearch
-* Kibana: A web front end to Elasticsearch
-
-We also deploy a simple webserver whose logs will be collected.
-
-* Tomcat 8: Web server whose logs will be stored in Elasticsearch by Logstash.
-
-For more about the ELK stack, please see the documentation [here](https://www.elastic.co/webinars/introduction-elk-stack).
-
-
-#### The Blueprints
------------
-
-There are four blueprints that make up this application. Each of them are used to add one or more catalog items to Brooklyn. You can find them below:
-
-* [Elasticsearch](https://github.com/brooklyncentral/brooklyn-elk/blob/master/brooklyn-elasticsearch-catalog.bom)
-* [Logstash](https://github.com/brooklyncentral/brooklyn-elk/blob/master/brooklyn-logstash-catalog.bom)
-* [Kibana](https://github.com/brooklyncentral/brooklyn-elk/blob/master/brooklyn-kibana-catalog.bom)
-* [ELK](https://github.com/brooklyncentral/brooklyn-elk/blob/master/brooklyn-elk-catalog.bom)
-
-#### Running the example
-First, add all four blueprints to the Brooklyn Catalog. This can be done by clicking the 'Catalog' tab, clicking the '+'
- symbol and pasting the YAML. Once this is done, click the 'Application' tab, then the '+' button to bring up the add
-application wizard. A new Catalog application will be available called 'ELK Stack'. Using the add application wizard,
-you should be able to deploy an ELK stack to a location of your choosing. Alternatively use the `br` Brooklyn
-command line tool and add the files with `br catalog add`.
-
-#### Exploring the example
-After the application has been deployed, you can ensure it is working as expected by checking the following:
-
-* There is a Kibana sensor called `main.uri`, the value of which points to the Kibana front end. You can explore this
-front end, and observe the logs stored in Elasticsearch. Many Brooklyn applications have a `main.uri` set to point you
-in the right direction.
-* You can also use the Elasticsearch REST API to explore further. The Elasticsearch Cluster entity has a `urls.http.list`
-sensor. Using a host:port from that list you will be able to access the REST API. The following URL will give you the
-state of the cluster `http://<host:port>/_cluster/health?pretty=true`. As you can see the `number_of_nodes` is
-currently 2, indicating that the Elasticsearch nodes are communicating with each other.
-
-### Interesting Feature Spotlight
-We will mainly focus on the Elasticsearch blueprint, and will be clear when another blueprint is being discussed. This blueprint describes a cluster of Elasticsearch nodes.
-
-#### Provisioning Properties
-Our Elasticsearch blueprint has a few requirements of the location in which it is run. Firstly, it must be run on an
-Ubuntu machine as the example has been written specifically for this OS. Secondly, two ports must opened to ensure
-that the entities can be accessed from the outside world. Both of these requirements are configured via
-`provisioning.properties` as follows:
-
-~~~yaml
-brooklyn.config:
- elasticsearch.http.port: 9220
- elasticsearch.tcp.port: 9330
- provisioning.properties:
- osFamily: ubuntu
- inboundPorts:
- - $brooklyn:config("elasticsearch.http.port")
- - $brooklyn:config("elasticsearch.tcp.port")
-~~~
-
-#### VanillaSoftwareProcess
-When composing a YAML blueprint, the VanillaSoftwareProcess is a very useful entity to be aware of.
-A VanillaSoftwareProcess will instruct Brooklyn to provision an instance, and run a series of shell
-commands to setup, run, monitor and teardown your program. The commands are specified as configuration
-on the VanillaSoftwareProcess and there are several available. We will spotlight a few now. To simplify
- this blueprint, we have specified ubuntu only installs so that our commands can be tailored to this
- system (e.g. use apt-get rather than yum).
-
-##### Customize Command
-The Customize Command is run after the application has been installed but before it is run. It is the perfect
- place to create and amend config files. Please refer to the following section of the Elasticsearch blueprint:
-
-~~~yaml
-customize.command: |
- sudo rm -fr sudo tee /etc/elasticsearch/elasticsearch.yml
- echo discovery.zen.ping.multicast.enabled: false | sudo tee -a /etc/elasticsearch/elasticsearch.yml
- echo discovery.zen.ping.unicast.enabled: true | sudo tee -a /etc/elasticsearch/elasticsearch.yml
- echo discovery.zen.ping.unicast.hosts: ${URLS_WITH_BRACKETS} | sudo tee -a /etc/elasticsearch/elasticsearch.yml
- echo http.port: ${ES_HTTP_PORT} | sudo tee -a /etc/elasticsearch/elasticsearch.yml
- echo transport.tcp.port: ${ES_TCP_PORT} | sudo tee -a /etc/elasticsearch/elasticsearch.yml
- echo network.host: ${IP_ADDRESS} | sudo tee -a /etc/elasticsearch/elasticsearch.yml
-~~~
-
-The purpose of this section is to create a YAML file with all of the required configuration. We use the YAML
-literal style `|` indicator to write a multi line command. We start our series of commands by using the `rm` command to remove the
-previous config file. We then use `echo` and `tee` to create the new config file and insert the config. Part
-of the configuration is a list of all hosts that is set on the parent entity- this is done by using a combination
- of the `component` and `attributeWhenReady` DSL commands. More on how this is generated later.
-
-##### Check running
-After an app is installed and run, this command is scheduled to run regularly and used to populate the `service.isUp`
-sensor. If this command is not specified, or returns an exit code of anything other than zero, then Brooklyn will
-assume that your entity has failed and will display the fire status symbol. Please refer to the following section
-of the Elasticsearch blueprint:
-
-~~~yaml
-checkRunning.command: sudo systemctl status kibana.service
-~~~
-
-There are many different ways to implement this command. For this example, we are simply using the systemctl status
-of the appropriate service.
-
-#### Enrichers
-
-##### Elasticsearch URLS
-To ensure that all Elasticsearch nodes can communicate with each other they need to be configured with the TCP URL
-of all other nodes. Similarly, the Logstash instances need to be configured with all the HTTP URLs of the Elasticsearch
-nodes. The mechanism for doing this is the same, and involves using Transformers, Aggregators and Joiners, as follows:
-
-~~~yaml
-brooklyn.enrichers:
- - type: org.apache.brooklyn.enricher.stock.Transformer
- brooklyn.config:
- enricher.sourceSensor: $brooklyn:sensor("host.subnet.address")
- enricher.targetSensor: $brooklyn:sensor("url.tcp")
- enricher.targetValue: $brooklyn:formatString("%s:%s", $brooklyn:attributeWhenReady("host.subnet.address"), $brooklyn:config("elasticsearch.tcp.port"))
-~~~
-
-In this example, we take the host.subnet.address and append the TCP port, outputting the result as `url.tcp`.
-After this has been done, we now need to collect all the URLs into a list in the Cluster entity, as follows:
-
-~~~yaml
-brooklyn.enrichers:
- - type: org.apache.brooklyn.enricher.stock.Aggregator
- brooklyn.config:
- enricher.sourceSensor: $brooklyn:sensor("url.tcp")
- enricher.targetSensor: $brooklyn:sensor("urls.tcp.list")
- enricher.aggregating.fromMembers: true
-
-~~~
-
-In the preceding example, we aggregated all of the TCP URLs generated in the early example.
-These are then stored in a sensor called `urls.tcp.list`. This list is then joined together into one long string:
-
-~~~yaml
-- 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
-~~~
-
-Finally, the string has brackets added to the start and end:
-
-~~~yaml
-- 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"))
-~~~
-
-The resulting sensor will be called `urls.tcp.withBrackets` and will be used by all Elasticsearch nodes during setup.
-
-##### Kibana URL
-Kibana also needs to be configured such that it can access the Elasticsearch cluster. However, Kibana can
- only be configured to point at one Elasticsearch instance. To enable this, we use another enricher in the
- cluster to select the first URL from the list, as follows:
-
-~~~yaml
-- type: org.apache.brooklyn.enricher.stock.Aggregator
- brooklyn.config:
- enricher.sourceSensor: $brooklyn:sensor("host.subnet.address")
- enricher.targetSensor: $brooklyn:sensor("host.address.first")
- enricher.aggregating.fromMembers: true
- enricher.transformation:
- $brooklyn:object:
- type: "org.apache.brooklyn.util.collections.CollectionFunctionals$FirstElementFunction"
-~~~
-
-Similar to the above Aggregator, this Aggregator collects all the URLs from the members of the cluster.
-However, this Aggregator specifies a transformation. In this instance a transformation is a Java class that
-implements a Guava Function `<? super Collection<?>, ?>>`, i.e. a function that takes in a collection and
-returns something. In this case we specify the FirstElementFunction from the CollectionFunctionals to ensure
-that we only get the first member of the URL list.
-
-#### Latches
-In the ELK blueprint, there is a good example of a latch. Latches are used to force an entity to wait until
-certain conditions are met before continuing. For example:
-
-~~~yaml
-- type: kibana-standalone
- id: kibana
- name: Kibana Server
- customize.latch: $brooklyn:component("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.
-
-Latches can also be used to control how many entities can execute the same step at any given moment. When
-a latch is given the value of a `MaxConcurrencySensor` it will unblock execution only when there are
-available "slots" to execute (think of it as a semaphore). For example to let a single entity execute the
-launch step of the start effector:
-
-~~~yaml
-services:
-- type: cluster
-
- brooklyn.initializers:
- - type: org.apache.brooklyn.core.sensor.MaxConcurrencySensor
- brooklyn.config:
- name: single-executor
- latch.concurrency.max: 1
-
- brooklyn.config:
- initialSize: 10
- memberSpec:
- $brooklyn:entitySpec:
- type: vanilla-bash-server
- brooklyn.config:
- launch.command: sleep 2
- checkRunning.command: true
- launch.latch: $brooklyn:parent().attributeWhenReady("single-executor")
-~~~
-
-It's important to note that the above setup is not reentrant. This means that users should be careful to
-avoid deadlocks. For example having a start and launch latches against the `single-executor` from above.
-The launch latch will block forever since the start latch already would've acquired the free slot.
-
-#### Child entities
-The ELK blueprint also contains a good example of a child entity.
-
-~~~yaml
-- type: org.apache.brooklyn.entity.webapp.tomcat.Tomcat8Server
- brooklyn.config:
- children.startable.mode: background_late
- ...
- brooklyn.children:
- - type: logstash-child
-~~~
-
-In this example, a logstash-child is started as a child of the parent Tomcat server. The Tomcat server needs
-to be configured with a `children.startable.mode` to inform Brooklyn when to bring up the child. In this case
- we have selected background so that the child is disassociated from the parent entity, and late to specify that
- the parent entity should start before we start the child.
-
-The example also shows how to configure Logstash inputs and filters, if necessary, for a particular application,
-in this case Tomcat.
-
-~~~yaml
-- type: logstash-child
- name: Logstash
- brooklyn.config:
- logstash.elasticsearch.hosts: $brooklyn:entity("es").attributeWhenReady("urls.http.withBrackets")
- logstash.config.input:
- $brooklyn:formatString:
- - |
- input {
- file {
- path => "%s/logs/localhost_access_log.*"
- start_position => "beginning"
- }
- }
- - $brooklyn:entity("tomcat").attributeWhenReady("run.dir")
- logstash.config.filter: |
- filter {
- grok {
- match => { "message" => "%{COMBINEDAPACHELOG}" }
- }
- date {
- match => [ "timestamp" , "dd/MMM/yyyy:HH:mm:ss Z" ]
- }
- }
-~~~
-
-Configuring an appropriate visualisation on the Kibana server (access it via the URL on the summary tab for
-that entity) allows a dashboard to be created such as
-
-
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/f38b9e7b/guide/yaml/ansible/about-ansible.md
----------------------------------------------------------------------
diff --git a/guide/yaml/ansible/about-ansible.md b/guide/yaml/ansible/about-ansible.md
deleted file mode 100644
index 9886993..0000000
--- a/guide/yaml/ansible/about-ansible.md
+++ /dev/null
@@ -1,34 +0,0 @@
----
-title: About Ansible
-title_in_menu: About Ansible
-layout: website-normal
----
-
-## What you need to know about Ansible
-
-[Ansible](http://docs.ansible.com/ansible/) is a deployment tool designed to work in an agent-less manner, normally
-performing its operations on a node over SSH from some central administrating node. Brooklyn can deploy software
-via Ansible on one of its managed nodes, by first installing Ansible on the node itself and then using Ansible to deploy
-the required software.
-
-A 'Playbook' in Ansible is a specification of the configuration and deployment of a system.
-Playbooks are expressed in YAML format, and contain a number of 'plays', which are in turn lists of tasks to carry out
-to achieve the desired configuration on the system. 'Roles' are pre-written modular collections of tasks, and can
-be included in playbooks.
-
-Ansible comes with built-in support for many software systems, and has a community repository of roles exists at
-[https://galaxy.ansible.com](https://galaxy.ansible.com).
-
-
-### How Brooklyn interacts with Ansible
-
-Brooklyn provides a Ansible entity type. An entity of this type can be specified in a blueprint in order to provision the
-node through Ansible. The Ansible entity will download Ansible and install it on the node. The entity type supports the
-configuration of Ansible playbooks to download, or write inline in the blueprint, for simple playbooks.
-Configuration values for the playbooks can be supplied in the blueprint.
-
-Brooklyn will deploy the software specified in the playbook when the entity starts. In addition, an effector is
-provided on the entity that supports general purpose Ansible instructions.
-
-
-
http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/f38b9e7b/guide/yaml/ansible/creating-ansible-blueprints.md
----------------------------------------------------------------------
diff --git a/guide/yaml/ansible/creating-ansible-blueprints.md b/guide/yaml/ansible/creating-ansible-blueprints.md
deleted file mode 100644
index 845f542..0000000
--- a/guide/yaml/ansible/creating-ansible-blueprints.md
+++ /dev/null
@@ -1,213 +0,0 @@
----
-title: Creating Blueprints with Ansible
-title_in_menu: Creating Blueprints with Ansible
-layout: website-normal
----
-
-To write a blueprint to use Ansible with Brooklyn it will help to have a degree of familiarity with Ansible itself. In the
-sections below, when the Brooklyn configuration is described, the underlying Ansible operation is also noted briefly, for
-clarity for readers who know Ansible.
-
-To manage a node with Ansible, create a blueprint containing a service of type `org.apache.brooklyn.entity.cm.ansible.AnsibleEntity`
-and define and minimum the `playbook` value, and one or other of `playbook.url` or `playbook.yaml`. You must also define
-the `service.name` that will be tested in order to determine if the entity is running successfully.
-
-For example:
-
- name: myweb
- location: ...
- services:
- - type: org.apache.brooklyn.entity.cm.ansible.AnsibleEntity
- id: apache
- name: apache
- service.name: apache2
- playbook: apache-playbook
- playbook.url: http://myhost/projectX/apache-playbook.yaml
-
-
-This example specifies that Brooklyn should use Ansible to download the playbook from the repository on
-"myhost". The playbook contains the instructions to install the Apache web server. To start the
-entity, Brooklyn will use Ansible's "ansible-playbook" command to run the playbook, which will bring up the web server.
-
-
-### Lifecycle of AnsibleEntity
-
-The start effector applies the playbook and verifies that it has started the software correctly by checking the service
-defined as `service.name` is running. This can be customized, see `ansible.service.start` configuration below.
-
-The stop effector will stop the service `service.name`. Again, this can be customized, with `ansible.service.stop`.
-
-The restart effector will apply stop and then start.
-
-
-### Configuration of AnsibleEntity
-
-The `playbook` configuration key names the top level list of states that will be applied using Ansible.
- This configuration key is mandatory.
-
-The playbook must be defined using one or other (both together are not permitted) of `playbook.yaml` or `playbook.url`.
-The former allows the playbook content to be defined inline within the blueprint, using the normal YAML format of an
-Ansible playbook. The latter obtains the playbook from an external URL.
-
-The `ansible.service.start` configuration key allows the blueprint author to override the command used by default to
-verify that the service `service.name` is running (or to start it, if the playbook did not specify it should run by
-default). The default value is:
-
- sudo ansible localhost -c local -m service -a "name=<service.name> state=started"
-
-Similarly the `ansible.service.stop` configuration key permits override of the instruction used to get Ansible to stop the
-service, by default
-
- sudo ansible localhost -c local -m service -a "name=<service.name> state=stopped"
-
-The `ansible.service.checkPort` configuration key allows the user to override the mechanism used to check that the
-service `service.name` is operating. By default Brooklyn checks that the service process is running. However, if the
- service is one that listens on a particular port, this configuration key allows the blueprint author to instruct
- Brooklyn to check that the port is being listened on, using the Ansible `wait_for` module. The value of the key is
- the port number to check.
-
-The `ansible.vars` configuration key allows the blueprint author to provide entity-specific values for configuration
-variables used in the playbook, so that one playbook can be used by multiple entities, each customized appropriately.
-The value of `ansible.vars` is an arbitrary block of YAML configuration that will be applied to the playbook using
-Ansible's `--extra-vars` mechanism, as described in the
-Ansible [documentation](http://docs.ansible.com/ansible/playbooks_variables.html#passing-variables-on-the-command-line).
-For example, if the playbook in the example above contained configuration such as:
-
- - hosts: all
- vars:
- http_port: 80
- max_clients: 200
- remote_user: root
- tasks:
- ...
-
- then to change the port that the webserver in the example above runs on, it would be possible to define the following
- in the blueprint:
-
- name: myweb
- location: ...
- services:
- - type: org.apache.brooklyn.entity.cm.ansible.AnsibleEntity
- id: apache
- name: apache
- service.name: apache2
- playbook: apache-playbook
- playbook.url: http://myhost/projectX/apache-playbook.yaml
- ansible.vars:
- http_port: 8080
-
-
-### ansibleCall Effector
-
-The Ansible entity includes a general purpose Ansible effector, `ansibleCommand`, which permits execution of Ansible
-commands via `ansible`. It contains a two parameters:
-1. `module` specifies the Ansible module to invoke. The default is "command".
-2. `args` specifies the argument data for the Ansible module. For example, to download an additional file for the
-webserver, the command could be invoked with the following arguments. (For convenience this
-example uses the client CLI, "br", but the effector could be invoked by any applicable means, e.g. via the web UI
-or REST API.)
-
- $ br app myweb ent apache effector ansibleCommand invoke \
- -P module=shell -P args='curl http://myhost:8080/additional.html > /var/www/html/additional.html'
-
-### Roles and Multi-Playbook Installations
-
-There is no specific configuration in AnsibleEntity for Ansible [Roles](http://docs.ansible.com/ansible/playbooks_roles.html),
- or to install multiple playbooks. However, the installation of roles or multiple playbooks can be carried out first
- by taking advantage of Brooklyn's SameServerEntity. The installation step can be applied in one child of the same server
- entity, while the AnsibleEntity can operate under the second child. It will typically be necessary to delay the start
- of the AnsibleEntity until the first child has carried out whatever preparation is required. The examples below
- illustrate the concept (with just one playbook, for brevity).
-
- One way to a achieve this, as with any Brooklyn entity, is to use the idiom of making it a child of a BasicApplication
- with a start latch waiting on the first child, such as in the following example, which installs the standalone Tomcat example,
- with its playbook and roles, from the "Ansible Examples" Github site.
- (Note, this is designed for installation on Redhat/Centos 6.)
- The first child in the SameServerEntity downloads
- and unpacks the Ansible examples. This might also install standalone Ansible roles, or whatever other resources the
- AnsibleEntity might require. The second child uses `attributeWhenReady` to block until the first is ready, before
- starting the AnsibleEntity to apply the desired playbook.
-
-
- name: multi
- location:
- red1
- services:
- - serviceType: brooklyn.entity.basic.SameServerEntity
- name: Entities
- brooklyn.children:
-
- - serviceType: org.apache.brooklyn.entity.cm.ansible.AnsibleEntity
- id: bootstrap
- service.name: crond
- playbook: bootstrap
- playbook.yaml: |
- ---
- - hosts: localhost
- tasks:
- - shell: printf "[tomcat-servers]\nlocalhost ansible_connection=local\n" >> /etc/ansible/hosts
- - file: path=/etc/ansible/playbooks state=directory mode=0755
- - get_url: url=https://github.com/ansible/ansible-examples/archive/master.zip dest=/tmp/master.zip mode=0440
- - command: unzip -o -d /etc/ansible/playbooks /tmp/master.zip
-
- - serviceType: org.apache.brooklyn.entity.stock.BasicApplication
- start.latch: $brooklyn:entity("bootstrap").attributeWhenReady("service.isUp")
- brooklyn.children:
- - type: org.apache.brooklyn.entity.cm.ansible.AnsibleEntity
- name: test
- service.name: tomcat
- playbook: tomcat
- playbook.yaml: |
- ---
- - hosts: localhost
- - include: /etc/ansible/playbooks/ansible-examples-master/tomcat-standalone/site.yml
- vars:
- http_port: 8080
- https_port: 8443
- admin_username: admin
- admin_password: secret
-
-
-An alternative to the above is to use Ansible itself to do the waiting, as in the variant below, which uses AnsibleEntity
-itself in the first SameServerEntity child, to install the required material. In the second child, which is simply an
-AnsibleEntity rather than a BasicApplication, Ansible's `wait_for` operation is used as the first step in the playbook,
-to block the remaining steps in its playbook until the first is complete.
-
- name: multi
- location:
- red1
- services:
- - serviceType: brooklyn.entity.basic.SameServerEntity
- name: Entities
- brooklyn.children:
-
- - serviceType: org.apache.brooklyn.entity.cm.ansible.AnsibleEntity
- id: bootstrap
- service.name: crond
- playbook: bootstrap
- playbook.yaml: |
- ---
- - hosts: localhost
- tasks:
- - command: rm -f /tmp/bootstrap.done
- - shell: printf "[tomcat-servers]\nlocalhost ansible_connection=local\n" >> /etc/ansible/hosts
- - file: path=/etc/ansible/playbooks state=directory mode=0755
- - get_url: url=https://github.com/ansible/ansible-examples/archive/master.zip dest=/tmp/master.zip mode=0440
- - command: unzip -o -d /etc/ansible/playbooks /tmp/master.zip
- - file: path=/tmp/bootstrap.done state=touch
-
- - serviceType: org.apache.brooklyn.entity.cm.ansible.AnsibleEntity
- name: test
- service.name: tomcat
- playbook: tomcat
- playbook.yaml: |
- ---
- - tasks:
- - wait_for: path=/tmp/bootstrap.done
- include: /etc/ansible/playbooks/ansible-examples-master/tomcat-standalone/site.yml
- vars:
- http_port: 8080
- https_port: 8443
- admin_username: admin
- admin_password: secret
-
http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/f38b9e7b/guide/yaml/ansible/index.md
----------------------------------------------------------------------
diff --git a/guide/yaml/ansible/index.md b/guide/yaml/ansible/index.md
deleted file mode 100644
index a2376d1..0000000
--- a/guide/yaml/ansible/index.md
+++ /dev/null
@@ -1,16 +0,0 @@
----
-title: Ansible in YAML Blueprints
-layout: website-normal
-children:
-- about-ansible.md
-- creating-ansible-blueprints.md
----
-
-This guide describes how Brooklyn entities can be created using the Ansible infrastructure management tool
- ([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.
-
-This guide assumes you are familiar with the basics of [creating YAML blueprints](../).
-
-{% include list-children.html %}
http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/f38b9e7b/guide/yaml/blueprinting-tips.md
----------------------------------------------------------------------
diff --git a/guide/yaml/blueprinting-tips.md b/guide/yaml/blueprinting-tips.md
deleted file mode 100644
index bbca6f7..0000000
--- a/guide/yaml/blueprinting-tips.md
+++ /dev/null
@@ -1,183 +0,0 @@
----
-title: Blueprinting Tips
-layout: website-normal
----
-
-## YAML Recommended
-
-The recommended way to write a blueprint is as a YAML file. This is true both for building
-an application out of existing blueprints, and for building new integrations.
-
-The use of Java is reserved for those use-cases where the provisioning or configuration logic
-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
-done incrementally as features of the blueprint are written.
-
-The slowest stages of deploying a blueprint are usually VM provisioning and downloading/installing
-of artifacts (e.g. RPMs, zip files, etc).
-
-Options for speeding up provisioning include those below.
-
-#### 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:
-
-* Artifacts are installed directly on your desktop/server.
-
-* The artifacts installed during previous runs can interfere with subsequent runs.
-
-* Some entities require `sudo` rights, which must be granted to the user running Brooklyn.
-
-
-#### Deploying to Clocker
-
-Docker containers provide a convenient way to test blueprints (and also to run blueprints in
-production!).
-
-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.
-
-
-#### 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 (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.
-
-* Where there is a choice of installation approaches, use the approach that is most appropriate for
- production use-cases (even if this is harder to test on locahost). For example,
- prefer the use of RPMs versus unpacking zip files, and prefer the use of services versus invoking
- a `bin/start` script.
-
-* Ensure every step is scriptable (e.g. manual install does not involve using a text editor to
- modify configuration files, or clicking on things in a web-console).
-
-* Write scripts (or Chef recipes, or Puppet manifests, etc), and test these by executing manually.
- Only once these work in isolation, add them to the entity blueprint.
-
-* Externalise the configuration where appropriate. For example, if there is a configuration file
- then include a config key for the URL of the configuration file to use. Consider using FreeMarker
- templating for such configuration files.
-
-* Focus on a single OS distro/version first, and clearly document these assumptions.
-
-* Breakdown the integration into separate components, where possible (and thus develop/test them separately).
- For example, if deploying a MongoDB cluster then first focus on single-node MongoDB, and then make that
- configurable and composable for a cluster.
-
-* 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.
http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/f38b9e7b/guide/yaml/chef/about-chef.md
----------------------------------------------------------------------
diff --git a/guide/yaml/chef/about-chef.md b/guide/yaml/chef/about-chef.md
deleted file mode 100644
index 8f87d07..0000000
--- a/guide/yaml/chef/about-chef.md
+++ /dev/null
@@ -1,50 +0,0 @@
----
-title: About Chef
-title_in_menu: About Chef
-layout: website-normal
----
-
-## What you need to know about Chef
-
-Chef works in two different modes, *server* and *solo*. *Server* is where the Chef client talks to a central server
-to retrieve information about its roles, policies and cookbooks (where a cookbook defines how to install and
-configure a particular piece of software). With *solo*, the client works in isolation, therefore its configuration
-and cookbooks must be supplied by another means.
-
-Chef *client* is the Chef agent. This is a Ruby application which is installed on each and every managed host. When
-invoked in server mode, it will contact the Chef server to check for updates to cookbooks and policy; it then "runs"
-the recipes in its run lists, to converge the machine to a known state. In solo mode, it reads the locally-maintained
-cookbooks and policies. The client may be run as a daemon that checks the server regularly, or it could merely be
-run manually when required.
-
-The *policy* is a set of rules on the Chef server. A client starts with a set of *attributes*, which could be as
-simple as its name and a recipe runlist, or which may involve a more complex set of attributes about how it is to be
-configured. The client then augments this with auto-detected metadata - a tool called `ohai` is run that collects
-detailed information about the host. Next, the policy on the server modifies these attributes - overriding some,
-setting defaults for others - to produce a final set of attributes. It is these which are the input to the recipes.
-Finally, the attributes are uploaded to the server where they are stored as metadata for the node, where they can be
-inspected and modified by the system operator.
-
-Also of interest is `knife`, which is the workstation toolkit for Chef. Typically this would be installed on the
-operation engineer's workstation, where it would be used to interact with the Chef server and clients. Of particular
-interest to us is the *bootstrap* operation, which is used for setting up new Chef clients - given a virtual machine,
-it will install the Chef client on it, configure it with enough information to find the Chef server and performs its
-first run, and then kicks off the Chef client for the first time.
-
-There is often a preconception about how a Chef client is bootstrapped; mistakenly, there is the belief that the
-`knife` tool configures the Chef server with information about the client, and the client finds out about itself from
-the server. This is not the case - the bootstrap operation does not involve `knife` talking to the server. Instead,
-`knife` packages up all of the required information and sends it to the client - the client will then introduce
-itself to the server, passing on its configuration.
-
-This diagram summarises the interaction between Brooklyn, the new node, and the various Chef tools. Note that there
-is no interaction between the Apache Brooklyn Server and the Chef Server.
-
-[](chef-call-flow.png)
-
-### How Brooklyn interacts with Chef
-
-Brooklyn understands both the *server* and *solo* modes of operation. Server mode utilises the `knife` toolkit, and
-therefore `knife` must be installed onto the Apache Brooklyn server and configured appropriately. Solo mode does not have any
-special requirements; when running in solo mode, Brooklyn will install and configure the Chef client over SSH, just
-like it does most other kinds of entities.
http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/f38b9e7b/guide/yaml/chef/advanced-chef-integration.md
----------------------------------------------------------------------
diff --git a/guide/yaml/chef/advanced-chef-integration.md b/guide/yaml/chef/advanced-chef-integration.md
deleted file mode 100644
index 0d65286..0000000
--- a/guide/yaml/chef/advanced-chef-integration.md
+++ /dev/null
@@ -1,48 +0,0 @@
----
-title: Advanced Chef Integration
-title_in_menu: Advanced Chef Integration
-layout: website-normal
----
-
-### Adding Sensors and Effectors
-
-Custom sensors and effectors can be added using an `entity.initializer` section in the YAML blueprint.
-
-One common pattern is to have sensors which extract information from Ohai.
-Another common pattern is to install a monitoring agent as part of the run list,
-configured to talk to a monitoring store, and then to add a sensor feed which reads data from that store.
-
-On the effector side, you can add SSH-based effectors in the usual way.
-You can also describe additional chef converge targets following the pattern set down in
-`ChefLifecycleEffectorTasks`, making use of conveniences in `ChefSoloTasks` and `ChefServerTasks`,
-or provide effectors which invoke network API's of the systems under management
-(for example to supply the common `executeScript` effector as on the standard `MySqlNode`).
-
-
-### Next Steps: Simpifying sensors and effectors, transferring files, and configuring ports
-
-The Brooklyn-Chef integration is work in progress, with a few open issues we'd still like to add.
-Much of the thinking for this is set forth in the [Google document](https://docs.google.com/a/cloudsoftcorp.com/document/d/18ZwzmncbJgJeQjnSvMapTWg6N526cvGMz5jaqdkxMf8)
-indicated earlier. If you'd like to work with us to implement these, please let us know.
-
-
-## Reference
-
-A general schema for the supported YAML is below:
-
-{% highlight yaml %}
-- type: chef:cookbook_name
- cookbook_urls:
- cookbook_name: url://for/cookbook.tgz
- dependency1: url://for/dependency1.tgz
- launch_run_list: [ "cookbook_name::start" ]
- launch_attributes: # map of arguments to set in the chef node
- service_name: cookbook_service
- pid_file: /var/run/cookbook.pid
-{% endhighlight %}
-
-If you are interested in exploring the Java code for creating blueprints,
-start with the `TypedToyMySqlEntiyChef` class, which essentially does what this tutorial has shown;
-and then move on to the `DynamicToyMySqlEntiyChef` which starts to look at more sophisticated constructs.
-(Familiarity with BASH and basic Java blueprints may be useful at that stage.)
-
http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/f38b9e7b/guide/yaml/chef/chef-call-flow.png
----------------------------------------------------------------------
diff --git a/guide/yaml/chef/chef-call-flow.png b/guide/yaml/chef/chef-call-flow.png
deleted file mode 100644
index d899de2..0000000
Binary files a/guide/yaml/chef/chef-call-flow.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/f38b9e7b/guide/yaml/chef/creating-blueprints.md
----------------------------------------------------------------------
diff --git a/guide/yaml/chef/creating-blueprints.md b/guide/yaml/chef/creating-blueprints.md
deleted file mode 100644
index 8d30131..0000000
--- a/guide/yaml/chef/creating-blueprints.md
+++ /dev/null
@@ -1,105 +0,0 @@
----
-title: Creating Blueprints from Chef
-title_in_menu: Creating Blueprints from Chef
-layout: website-normal
----
-
-In a nutshell, a new Chef-based entity can be defined as a service by specifying
-`chef:cookbook_name` as the `service_type`, along with a collection of optional configuration.
-An illustrative example is below:
-
-{% highlight yaml %}
-{% readj example_yaml/mysql-chef-1.yaml %}
-{% endhighlight %}
-
-*This works without any installation: try it now, copying-and-pasting to the Brooklyn console.
-(Don't forget to add your preferred `location: some-cloud` to the spec.)*
-
-Notice, if you target `google-compute-engine` location, you may need to specify `bind_address: 0.0.0.0` for the `mysql` cookbook, as described [here](https://github.com/chef-cookbooks/mysql/blob/46dccac22d282a05ee6a401e10ae8f5f8114fd66/README.md#parameters).
-
-We'll now walk through the important constituent parts,
-and then proceed to describing things which can be done to simplify the deployment.
-
-
-### Cookbook Primary Name
-
-The first thing to note is the type definition:
-
- - type: chef:mysql
-
-This indicates that the Chef entity should be used (`org.apache.brooklyn.entity.chef.ChefEntity`)
-to interpret and pass the configuration,
-and that it should be parameterised with a `brooklyn.chef.cookbook.primary.name` of `mysql`.
-This is the cookbook namespace used by default for determining what to install and run.
-
-
-### Importing Cookbooks
-
-Next we specify which cookbooks are required and where they can be pulled from:
-
- cookbook_urls:
- mysql: https://github.com/opscode-cookbooks/mysql/archive/v4.0.12.tar.gz
- openssl: https://github.com/opscode-cookbooks/openssl/archive/v1.1.0.tar.gz
- build-essential: https://github.com/opscode-cookbooks/build-essential/archive/v1.4.4.tar.gz
-
-Here, specific versions are being downloaded from the canonical github repository.
-Any URL can be used, so long as it is resolvable on either the target machine or the
-Brooklyn server; this includes `file:` and `classpath:` URLs.
-
-The archive can be ZIP or TAR or TGZ.
-
-The structure of the archive must be that a single folder is off the root,
-and in that folder contains the usual Chef recipe and auxiliary files.
-For example, the archive might contain `mysql-master/recipes/server.rb`.
-Archives such as those above from github match this format.
-The name of that folder does not matter, as often they contain version information.
-When deployed, these will be renamed to match the short name (the key in the `cookbooks_url` map,
-for instance `mysql` or `openssl`).
-
-If Chef server is configured (see below), this section can be omitted.
-
-
-### Launch Run List and Attributes
-
-The next part is to specify the Chef run list and attributes to store when launching the entity:
-
- launch_run_list:
- - mysql::server
-
- launch_attributes:
- mysql:
- server_root_password: p4ssw0rd
- server_repl_password: p4ssw0rd
- server_debian_password: p4ssw0rd
-
-For the `launch_run_list`, you can use either the YAML `- recipe` syntax or the JSON `[ "recipe" ]` syntax.
-
-The `launch_attributes` key takes a map which will be stored against the `node` object in Chef.
-Thus in this example, the parameter `node['mysql']['server_root_password']` required by the mysql blueprint
-is set as specified.
-
-You can of course set many other attributes in this manner, in addition to those that are required!
-
-
-### Simple Monitoring
-
-The final section determines how Brooklyn confirms that the service is up.
-Sophisticated solutions may install monitoring agents as part of the `launch_run_list`,
-with Brooklyn configured to read monitoring information to confirm the launch was successful.
-However for convenience, two common mechanisms are available out of the box:
-
- #service_name: mysqld
- pid_file: /var/run/mysqld/mysqld.pid
-
-If `service_name` is supplied, Brooklyn will check the return code of the `status` command
-run against that service, ensuring it is 0. (Note that this is not universally reliable,
-although it is the same mechanism which Chef typically uses to test status when determining
-whether to start a service. Some services, e.g. postgres, will return 0 even if the service
-is not running.)
-
-If a `pid_file` is supplied, Brooklyn will check whether a process with the PID specified in that
-file is running. This has been selected for mysql because it appears to be more portable:
-the service name varies among OS's: it is `mysqld` on CentOS but `mysql` on Ubuntu!
-
-
-
http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/f38b9e7b/guide/yaml/chef/example_yaml/mysql-chef-1.yaml
----------------------------------------------------------------------
diff --git a/guide/yaml/chef/example_yaml/mysql-chef-1.yaml b/guide/yaml/chef/example_yaml/mysql-chef-1.yaml
deleted file mode 100644
index bdac530..0000000
--- a/guide/yaml/chef/example_yaml/mysql-chef-1.yaml
+++ /dev/null
@@ -1,24 +0,0 @@
-name: chef-mysql-sample
-services:
-- type: chef:mysql
-
- cookbook_urls:
- # only needed for chef solo; URL can be local to brooklyn, or github, etc...
- mysql: https://github.com/opscode-cookbooks/mysql/archive/v4.0.12.tar.gz
- openssl: https://github.com/opscode-cookbooks/openssl/archive/v1.1.0.tar.gz
- build-essential: https://github.com/opscode-cookbooks/build-essential/archive/v1.4.4.tar.gz
-
- launch_run_list: [ "mysql::server" ]
- launch_attributes:
- mysql:
- # these attrs are required by the mysql cookbook under node['mysql']
- server_root_password: p4ssw0rd
- server_repl_password: p4ssw0rd
- server_debian_password: p4ssw0rd
- # 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
- # (supported options are `service_name` and `pid_file`; normally you should just pick one.
- # here we use the pid_file because the service_name varies, mysql on centos, mysqld on ubuntu!)
- #service_name: mysqld
- pid_file: /var/run/mysqld/mysqld.pid
http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/f38b9e7b/guide/yaml/chef/example_yaml/mysql-chef-2.yaml
----------------------------------------------------------------------
diff --git a/guide/yaml/chef/example_yaml/mysql-chef-2.yaml b/guide/yaml/chef/example_yaml/mysql-chef-2.yaml
deleted file mode 100644
index 9e9de9b..0000000
--- a/guide/yaml/chef/example_yaml/mysql-chef-2.yaml
+++ /dev/null
@@ -1,28 +0,0 @@
-name: chef-mysql-sample
-services:
-- type: chef:mysql
- id: db
-
- cookbook_urls:
- # only needed for chef solo; URL can be local to brooklyn, or github, etc...
- mysql: https://github.com/opscode-cookbooks/mysql/archive/v4.0.12.tar.gz
- openssl: https://github.com/opscode-cookbooks/openssl/archive/v1.1.0.tar.gz
- build-essential: https://github.com/opscode-cookbooks/build-essential/archive/v1.4.4.tar.gz
-
- launch_run_list: [ "mysql::server" ]
- launch_attributes:
- mysql:
- # these attrs are required by the mysql cookbook under node['mysql']
- 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
- # (supported options are `service_name` and `pid_file`; normally you should just pick one.
- # here we use the pid_file because the service_name varies, mysql on centos, mysqld on ubuntu!)
- #service_name: mysqld
- pid_file: /var/run/mysqld/mysqld.pid
-
-brooklyn.config:
- mysql.password: p4ssw0rd
http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/f38b9e7b/guide/yaml/chef/index.md
----------------------------------------------------------------------
diff --git a/guide/yaml/chef/index.md b/guide/yaml/chef/index.md
deleted file mode 100644
index f0fa3d0..0000000
--- a/guide/yaml/chef/index.md
+++ /dev/null
@@ -1,18 +0,0 @@
----
-title: Chef in YAML Blueprints
-layout: website-normal
-children:
-- about-chef.md
-- creating-blueprints.md
-- writing-chef.md
-- advanced-chef-integration.md
----
-
-This guide describes how Brooklyn entities can be easily created from Chef cookbooks.
-As of this writing (May 2014) some of the integration points are under active development,
-and comments are welcome.
-A plan for the full integration is online [here](https://docs.google.com/a/cloudsoftcorp.com/document/d/18ZwzmncbJgJeQjnSvMapTWg6N526cvGMz5jaqdkxMf8).
-
-This guide assumes you are familiar with the basics of [creating YAML blueprints](../).
-
-{% include list-children.html %}
http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/f38b9e7b/guide/yaml/chef/writing-chef.md
----------------------------------------------------------------------
diff --git a/guide/yaml/chef/writing-chef.md b/guide/yaml/chef/writing-chef.md
deleted file mode 100644
index 671d961..0000000
--- a/guide/yaml/chef/writing-chef.md
+++ /dev/null
@@ -1,79 +0,0 @@
----
-title: Writing Chef for Blueprints
-title_in_menu: Writing Chef for Blueprints
-layout: website-normal
----
-
-## Making it Simpler
-
-The example we've just seen shows how existing Chef cookbooks can be
-used as the basis for entities. If you're *writing* the Chef recipes,
-there are a few simple techniques we've established with the Chef community
-which make blueprints literally as simple as:
-
- - type: chef:mysql
- brooklyn.config:
- mysql_password: p4ssw0rd
- pid_file: /var/run/mysqld/mysqld.pid
-
-
-### Some Basic Conventions
-
-* **A `start` recipe**:
- The first step is to provide a `start` recipe in `recipes/start.rb`;
- if no `launch_run_list` is supplied, this is what will be invoked to launch the entity.
- It can be as simple as a one-line file:
-
- include_recipe 'mysql::server'
-
-* **Using `brooklyn.config`**:
- All the `brooklyn.config` is passed to Chef as node attributes in the `node['brooklyn']['config']` namespace.
- Thus if the required attributes in the mysql recipe are set to take a value set in
- `node['brooklyn']['config']['mysql_password']`, you can dispense with the `launch_attributes` section.
-
-
-## Using Chef Server
-
-The examples so far have not required Chef Server, so they will work without any external
-Chef dependencies (besides the built-in install from `https://www.opscode.com/chef/install.sh`
-and the explicitly referenced cookbooks). If you use Chef Server, however, you'll want your
-managed nodes to be integrated with it. This is easy to set up, with a few options:
-
-If you have `knife` set up in your shell environment, the Brooklyn Chef support will use it
-by default. If the recipes are installed in your Chef server, you can go ahead and remove
-the `cookbooks_url` section!
-
-Use of `solo` or `knife` can be forced by setting the `chef_mode` flag (`brooklyn.chef.mode` config key)
-to either of those values. (It defaults to `autodetect`, which will use `knife` if it is on the path and satisfies
-sanity checks).
-
-If you want to specify a different configuration, there are a number of config keys you can use:
-
-* `brooklyn.chef.knife.executableFile`: this should be point to the knife binary to use
-* `brooklyn.chef.knife.configFile`: this should point to the knife configuration to use
-* `brooklyn.chef.knife.setupCommands`: an optional set of commands to run prior to invoking knife,
- for example to run `rvm` to get the right ruby version on the Brooklyn server
-
-If you're interested in seeing the Chef REST API be supported directly (without knife),
-please let us know. We'd like to see this too, and we'll help you along the way!
-
-
-## Tips and Tricks
-
-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: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.
-
-* Github tarball downloads! You'll have noticed these in the example already, but they are so useful we thought
- we'd call them out again. Except when you're developing, we recommend using specific tagged versions rather than master.
-
-* The usual machine `provisioning.properties` are supported with Chef blueprints,
- so you can set things like `minRam` and `osFamily`
-
-* To see more configuration options, and understand the ones presented here in more detail, see the javadoc or
- the code for the class `ChefConfig` in the Brooklyn code base.
-