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. -
