http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/58bb3aa0/guide/blueprints/chef/about-chef.md ---------------------------------------------------------------------- diff --git a/guide/blueprints/chef/about-chef.md b/guide/blueprints/chef/about-chef.md deleted file mode 100644 index 8f87d07..0000000 --- a/guide/blueprints/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/58bb3aa0/guide/blueprints/chef/advanced-chef-integration.md ---------------------------------------------------------------------- diff --git a/guide/blueprints/chef/advanced-chef-integration.md b/guide/blueprints/chef/advanced-chef-integration.md deleted file mode 100644 index 1081cd3..0000000 --- a/guide/blueprints/chef/advanced-chef-integration.md +++ /dev/null @@ -1,49 +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 - brooklyn.config: - 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/58bb3aa0/guide/blueprints/chef/chef-call-flow.png ---------------------------------------------------------------------- diff --git a/guide/blueprints/chef/chef-call-flow.png b/guide/blueprints/chef/chef-call-flow.png deleted file mode 100644 index d899de2..0000000 Binary files a/guide/blueprints/chef/chef-call-flow.png and /dev/null differ http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/58bb3aa0/guide/blueprints/chef/creating-blueprints.md ---------------------------------------------------------------------- diff --git a/guide/blueprints/chef/creating-blueprints.md b/guide/blueprints/chef/creating-blueprints.md deleted file mode 100644 index 8d30131..0000000 --- a/guide/blueprints/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/58bb3aa0/guide/blueprints/chef/example_yaml/mysql-chef-1.yaml ---------------------------------------------------------------------- diff --git a/guide/blueprints/chef/example_yaml/mysql-chef-1.yaml b/guide/blueprints/chef/example_yaml/mysql-chef-1.yaml deleted file mode 100644 index d1c244f..0000000 --- a/guide/blueprints/chef/example_yaml/mysql-chef-1.yaml +++ /dev/null @@ -1,25 +0,0 @@ -name: chef-mysql-sample -services: -- type: chef:mysql - - brooklyn.config: - 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/58bb3aa0/guide/blueprints/chef/example_yaml/mysql-chef-2.yaml ---------------------------------------------------------------------- diff --git a/guide/blueprints/chef/example_yaml/mysql-chef-2.yaml b/guide/blueprints/chef/example_yaml/mysql-chef-2.yaml deleted file mode 100644 index 756f374..0000000 --- a/guide/blueprints/chef/example_yaml/mysql-chef-2.yaml +++ /dev/null @@ -1,27 +0,0 @@ -name: chef-mysql-sample -services: -- type: chef:mysql - id: db - - brooklyn.config: - 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 - mysql.password: p4ssw0rd http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/58bb3aa0/guide/blueprints/chef/index.md ---------------------------------------------------------------------- diff --git a/guide/blueprints/chef/index.md b/guide/blueprints/chef/index.md deleted file mode 100644 index f0fa3d0..0000000 --- a/guide/blueprints/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/58bb3aa0/guide/blueprints/chef/writing-chef.md ---------------------------------------------------------------------- diff --git a/guide/blueprints/chef/writing-chef.md b/guide/blueprints/chef/writing-chef.md deleted file mode 100644 index 671d961..0000000 --- a/guide/blueprints/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. - http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/58bb3aa0/guide/blueprints/clusters-and-policies.md ---------------------------------------------------------------------- diff --git a/guide/blueprints/clusters-and-policies.md b/guide/blueprints/clusters-and-policies.md deleted file mode 100644 index 0e9630f..0000000 --- a/guide/blueprints/clusters-and-policies.md +++ /dev/null @@ -1,46 +0,0 @@ ---- -title: Clusters and Policies -layout: website-normal -toc: ../guide_toc.json -categories: [use, guide, defining-applications] ---- - -Now let's bring the concept of the "cluster" back in. -We could wrap our appserver in the same `DynamicCluster` we used earlier, -although then we'd need to define and configure the load balancer. -But another blueprint, the `ControlledDynamicWebAppCluster`, does this for us. -It takes the same `dynamiccluster.memberspec`, so we can build a fully functional elastic 3-tier -deployment of our `hello-world-sql` application as follows: - -{% highlight yaml %} -{% readj example_yaml/appserver-clustered-w-db.yaml %} -{% endhighlight %} - -This sets up Nginx as the controller by default, but that can be configured -using the `controllerSpec` key. -This uses the same [externalized config](../ops/externalized-config.html) -as in other examples to hide the password. - -JBoss is actually the default appserver in the `ControlledDynamicWebAppCluster`, -so because `brooklyn.config` keys in Brooklyn are inherited by default, -the same blueprint can be expressed more concisely as: - -{% highlight yaml %} -{% readj example_yaml/appserver-clustered-w-db-concise.yaml %} -{% endhighlight %} - -The other nicety supplied by the `ControlledDynamicWebAppCluster` blueprint is that -it aggregates sensors from the appserver, so we have access to things like -`webapp.reqs.perSec.windowed.perNode`. -These are convenient for plugging in to policies! -We can set up our blueprint to do autoscaling based on requests per second -(keeping it in the range 10..100, with a maximum of 5 appserver nodes) -as follows: - -{% highlight yaml %} -{% readj example_yaml/appserver-w-policy.yaml %} -{% endhighlight %} - -Use your favorite load-generation tool (`jmeter` is one good example) to send a huge -volume of requests against the server and see the policies kick in to resize it. - http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/58bb3aa0/guide/blueprints/clusters.md ---------------------------------------------------------------------- diff --git a/guide/blueprints/clusters.md b/guide/blueprints/clusters.md deleted file mode 100644 index 4c1312c..0000000 --- a/guide/blueprints/clusters.md +++ /dev/null @@ -1,34 +0,0 @@ ---- -title: Clusters, Specs, and Composition -layout: website-normal -toc: ../guide_toc.json -categories: [use, guide, defining-applications] ---- - -What if you want multiple machines? - -One way is just to repeat the `- type: org.apache.brooklyn.entity.software.base.EmptySoftwareProcess` block, -but there's another way which will keep your powder [DRY](http://en.wikipedia.org/wiki/Don't_repeat_yourself): - -{% highlight yaml %} -{% readj example_yaml/cluster-vm.yaml %} -{% endhighlight %} - -Here we've composed the previous blueprint introducing some new important concepts, the `DynamicCluster` -the `$brooklyn` DSL, and the "entity-spec". Let's unpack these. - -The `DynamicCluster` creates a set of homogeneous instances. -At design-time, you specify an initial size and the specification for the entity it should create. -At runtime you can restart and stop these instances as a group (on the `DynamicCluster`) or refer to them -individually. You can resize the cluster, attach enrichers which aggregate sensors across the cluster, -and attach policies which, for example, replace failed members or resize the cluster dynamically. - -The specification is defined in the `dynamiccluster.memberspec` key. As you can see it looks very much like the -previous blueprint, with one extra line. Entries in the blueprint which start with `$brooklyn:` -refer to the Brooklyn DSL and allow a small amount of logic to be embedded -(if there's a lot of logic, it's recommended to write a blueprint YAML plugin or write the blueprint itself -as a plugin, in Java or a JVM-supported language). - -In this case we want to indicate that the parameter to `dynamiccluster.memberspec` is an entity specification -(`EntitySpec` in the underlying type system); the `entitySpec` DSL command will do this for us. -The example above thus gives us 5 VMs identical to the one we created in the previous section. http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/58bb3aa0/guide/blueprints/config-files.md ---------------------------------------------------------------------- diff --git a/guide/blueprints/config-files.md b/guide/blueprints/config-files.md deleted file mode 100644 index f92aeb8..0000000 --- a/guide/blueprints/config-files.md +++ /dev/null @@ -1,102 +0,0 @@ ---- -title: Uploading Script and Configuration Files -layout: website-normal -toc: ../guide_toc.json -categories: [use, guide, defining-applications] ---- - -Blueprints often require that parameterized scripts and configuration files are available to be copied to the -target VM. These must be URLs resolvable from the Brooklyn instance, or on the Brooklyn classpath. - -There are two types of file that can be uploaded: plain files and templated files. A plain -file is uploaded unmodified. A templated file is interpreted as a [FreeMarker](http://freemarker.org) -template. This supports a powerful set of substitutions. In brief, anything (unescaped) of the form -`${name}` will be substituted, in this case looking up "name" for the value to use. - - -## Writing templates - -Templated files (be they configuration files or scripts) give a powerful way to inject dependent -configuration when installing an entity (e.g. for customising the install, or for referencing the -connection details of another entity). Available substitutions are: - -| Substitution | Effect | -|---------------------------|--------------------------------------------------------------------| -| `${config['key']}` | Equivalent to `entity.config().get(key)` | -| `${attribute['key']}` | Equivalent to `entity.sensors().get(key)` | -| `${mgmt['key']}` | Loads the value for `key` from the management context's properties | -| `${entity.foo}` | FreeMarker calls `getFoo` on the entity | -| `${driver.foo}` | FreeMarker calls `getFoo` on the entity's [driver](http://brooklyn.apache.org/v/latest/java/entity.html#things-to-know) | -| `${location.foo}` | FreeMarker calls `getFoo` on the entity's location | -| `${javaSysProps.foo.bar}` | Loads the system property named `foo.bar` | - -Additional substitutions can be given per-entity by setting the `template.substitutions` key. For example, -to include the address of an entity called db: - - brooklyn.config - template.substitutions: - databaseAddress: $brooklyn:entity("db").attributeWhenReady("host.address") - -The value can be referenced in a template with `${databaseAddress}`. - -FreeMarker evaluates all expressions between `${}` which may be inappropriate in certain kinds of files. -To include the literal `${value}` in a script you might: - * specify a [raw string literal](http://freemarker.org/docs/dgui_template_exp.html#dgui_template_exp_direct_string): - `${r"${value}"}` - * use the [noparse](http://freemarker.org/docs/ref_directive_noparse.html) directive: `<#noparse>${value}</#noparse>` - * use FreeMarker's [alternative syntax](http://freemarker.org/docs/dgui_misc_alternativesyntax.html). - -A common pattern for templating Bash files is to set environment variables at the top of the script and to surround -the rest of its contents with `noparse`. For example: - - GREETING=${config['greeting']} - NAME=${config['name']} - - <#noparse> - # The remainder of the script can be written as normal. - echo "${GREETING}, ${NAME}!" - </#noparse> - - -## Using templates in blueprints - -Files can be uploaded at several stages of an entity's lifecycle: - -| Config key | Copied before lifecycle phase | Templated | Relative to | -|------------------------|-------------------------------|-----------|--------------| -| `files.preinstall` | Pre-install | â | `installDir` | -| `files.install` | Install | â | `installDir` | -| `files.customize` | Pre-customize command | â | `installDir` | -| `files.runtime` | Pre-launch command | â | `run.dir` | -| `templates.preinstall` | Pre-install | â | `installDir` | -| `templates.install` | Install | â | `installDir` | -| `templates.customize` | Pre-customize command | â | `installDir` | -| `templates.runtime` | Pre-launch command | â | `run.dir` | - -Each key accepts a map of values where a key indicates the source of a file and a value its destination -on the instance. - -Files can be referenced as URLs. This includes support for: - * `classpath://mypath/myfile.bat`, which looks for the given (fully qualified) resource on the Brooklyn classpath - or inside the bundle, if using the OSGi version of Brooklyn with a catalog blueprint. - * `file://`, which looks for the given file on the Brooklyn server, and - * `http://`, which requires the file to be accessible from the Brooklyn instance. - -Destinations may be absolute or relative. Absolute paths need not exist beforehand, but Brooklyn's SSH user must -have sufficient permission to create all parent directories and the file itself. Relative paths are copied as -described in the table above. - - -### Example - - files.preinstall: - # Reference a fixed resource - classpath://com/acme/installAcme.ps1: C:\\acme\installAcme.ps1 - # Inject the source from a config key - $brooklyn:config("acme.conf"): C:\\acme\acme.conf - - -## Windows notes - -* When writing scripts for Windows ensure that each line ends with "\r\n", rather than just "\n". -* The backslash character (\\) must be escaped in paths. For example: `C:\\install7zip.ps1`. http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/58bb3aa0/guide/blueprints/configuring-vms.md ---------------------------------------------------------------------- diff --git a/guide/blueprints/configuring-vms.md b/guide/blueprints/configuring-vms.md deleted file mode 100644 index e7e7f47..0000000 --- a/guide/blueprints/configuring-vms.md +++ /dev/null @@ -1,31 +0,0 @@ ---- -title: Configuring VMs -layout: website-normal -toc: ../guide_toc.json -categories: [use, guide, defining-applications] ---- - -Another simple blueprint will just create a VM which you can use, without any software installed upon it: - -{% highlight yaml %} -{% readj example_yaml/simple-vm.yaml %} -{% endhighlight %} - - -*We've omitted the `location` section here and in many of the examples below; -add the appropriate choice when you paste your YAML. Note that the `provisioning.properties` will be -ignored if deploying to `localhost` or `byon` fixed-IP machines.* - -This will create a VM with the specified parameters in your choice of cloud. -In the GUI (and in the REST API), the entity is called "VM", -and the hostname and IP address(es) are reported as [sensors]({{ site.path.guide }}/concepts/entities.html). -There are many more `provisioning.properties` supported here, -including: - -* a `user` to create (if not specified it creates the same username as `brooklyn` is running under) -* a `password` for him or a `publicKeyFile` and `privateKeyFile` (defaulting to keys in `~/.ssh/id_rsa{.pub,}` and no password, - so if you have keys set up you can immediately ssh in!) -* `machineCreateAttempts` (for dodgy clouds, and they nearly all fail occasionally!) -* and things like `imageId` and `userMetadata` and disk and networking options (e.g. `autoAssignFloatingIp` for private clouds) - -For more information, see [Operations: Locations]({{ site.path.guide }}/locations/index.html). http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/58bb3aa0/guide/blueprints/creating-yaml.md ---------------------------------------------------------------------- diff --git a/guide/blueprints/creating-yaml.md b/guide/blueprints/creating-yaml.md deleted file mode 100644 index 6f91784..0000000 --- a/guide/blueprints/creating-yaml.md +++ /dev/null @@ -1,78 +0,0 @@ ---- -title: The Basic Structure -layout: website-normal -toc: ../guide_toc.json -categories: [use, guide, defining-applications] ---- - -## A First Blueprint - -The easiest way to write a blueprint is as a YAML file. -This follows the <a href="https://www.oasis-open.org/committees/camp/";>OASIS CAMP</a> plan specification, -with some extensions described below. -(A [YAML reference](yaml-reference.html) has more information, -and if the YAML doesn't yet do what you want, -it's easy to add new extensions using your favorite JVM language.) - -### The Basic Structure - -Here's a very simple YAML blueprint plan, to explain the structure: - -{% highlight yaml %} -{% readj example_yaml/simple-appserver.yaml %} -{% endhighlight %} - -* The `name` is just for the benefit of us humans. - -* The `location` specifies where this should be deployed. - If you've [set up passwordless localhost SSH access]({{ site.path.guide }}/locations/#localhost) - you can use `localhost` as above, but if not, just wait ten seconds for the next example. - -* The `services` block takes a list of the typed services we want to deploy. - This is the meat of the blueprint plan, as you'll see below. - -Finally, the clipboard in the top-right corner of the example plan box above (hover your cursor over the box) lets you easily copy-and-paste into the web-console: -simply [download and launch]({{ site.path.guide }}/start/running.html) Brooklyn, -then in the "Create Application" dialog at the web console -(usually [http://127.0.0.1:8081/](http://127.0.0.1:8081/), paste the copied YAML into the "Yaml" tab of the dialog and press "Finish". -There are several other ways to deploy, including `curl` and via the command-line, -and you can configure users, https, persistence, and more, -as described [in the ops guide]({{ site.path.guide }}/ops/). - -[](web-console-yaml.png) - - - -<!-- -TODO building up children entities - ---> - - - -### More Information - -Topics to explore next on the topic of YAML blueprints are: - -{% include list-children.html %} - -Plenty of examples of blueprints exist in the Brooklyn codebase, -so another starting point is to [`git clone`]({{ site.path.website }}/developers/code/index.html) it -and search for `*.yaml` files therein. - -Brooklyn lived as a Java framework for many years before we felt confident -to make a declarative front-end, so you can do pretty much anything you want to -by dropping to the JVM. For more information on Java: - -* start with a [Maven archetype]({{site.path.guide}}/blueprints/java/archetype.html) -* see all [Brooklyn Java guide]({{site.path.guide}}/blueprints/java/) topics -* look at test cases in the [codebase](https://github.com/apache/brooklyn) - -<!-- -TODO -* review some [examples]({{site.path.guide}}/use/examples/index.html) ---> - -You can also come talk to us, on IRC (#brooklyncentral on Freenode) or -any of the usual [hailing frequencies]({{site.path.website}}/community/), -as these documents are a work in progress. http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/58bb3aa0/guide/blueprints/custom-entities.md ---------------------------------------------------------------------- diff --git a/guide/blueprints/custom-entities.md b/guide/blueprints/custom-entities.md deleted file mode 100644 index efd03ba..0000000 --- a/guide/blueprints/custom-entities.md +++ /dev/null @@ -1,343 +0,0 @@ ---- -title: Custom Entities -layout: website-normal -toc: ../guide_toc.json -categories: [use, guide, defining-applications] ---- - -So far we've covered how to configure and compose entities. -There's a large library of blueprints available, but -there are also times when you'll want to write your own. - -For complex use cases, you can write JVM, but for many common situations, -some of the highly-configurable blueprints make it easy to write in YAML, -including `bash` and Chef. - - -### Vanilla Software using `bash` - -The following blueprint shows how a simple script can be embedded in the YAML -(the `|` character is special YAML which makes it easier to insert multi-line text): - -{% highlight yaml %} -{% readj example_yaml/vanilla-bash-netcat.yaml %} -{% endhighlight %} - -This starts a simple `nc` listener on port 4321 which will respond `hello` to the first -session which connects to it. Test it by running `telnet localhost 4321` -or opening `http://localhost:4321` in a browser. - -Note that it only allows you connect once, and after that it fails. -This is deliberate! We'll repair this later in this example. -Until then however, in the *Applications* view you can click the server, -go to the `Effectors` tab, and click `restart` to bring if back to life. - -This is just a simple script, but it shows how any script can be easily embedded here, -including a script to download and run other artifacts. -Many artifacts are already packaged such that they can be downloaded and launched -with a simple script, and `VanillaSoftwareProcess` can also be used for them. - - -#### Downloading Files - -We can specify a `download.url` which downloads an artifact -(and automatically unpacking TAR, TGZ, and ZIP archives) -before running `launch.command` relative to where that file is installed (or unpacked), -with the default `launch.command` being `./start.sh`. - -So if we create a file `/tmp/netcat-server.tgz` containing just `start.sh` in the root -which contains the line `echo hello | nc -l 4321`, -we can instead write our example as: - -{% highlight yaml %} -{% readj example_yaml/vanilla-bash-netcat-file.yaml %} -{% endhighlight %} - - -#### Determining Successful Launch - -The default method used to determine a successful launch of `VanillaSoftwareProcess` is to run a -command over ssh to do a health check. The health check is done post-launch (repeating until it -succeeds, before then reporting that the entity has started). - -The default command used to carry out this health check will determine if the pid, written to -`$PID_FILE` is running. This is why we included in the entity's launch script the line -`echo $! > $PID_FILE`. - -You'll observe this if you connect to one of the netcat services (e.g. via `telnet localhost 4321`): -the `nc` process exits afterwards, causing Brooklyn to set the entity to an `ON_FIRE` state. -(You can also test this with a `killall nc`). - -There are other options for determining health: you can set `checkRunning.command` and `stop.command` instead, -as documented on the javadoc and config keys of the -{% include java_link.html class_name="VanillaSoftwareProcess" package_path="org/apache/brooklyn/entity/software/base" project_subpath="software/base" %} class, -and those scripts will be used instead of checking and stopping the process whose PID is in `$PID_FILE`. For example: - -{% highlight yaml %} -{% readj example_yaml/vanilla-bash-netcat-more-commands.yaml %} -{% endhighlight %} - - -#### Periodic Health Check - -After start-up is complete, the health check described above is also run periodically, defaulting -to every 5 seconds (configured with the config key `softwareProcess.serviceProcessIsRunningPollPeriod`). - -This ssh-based polling can be turned off by configuring `sshMonitoring.enabled: false`. However, if -no alternative health-check is defined then failure of the process would never be detected by Brooklyn. - -See [Health Check Sensors](#health-check-sensors) for alternative ways of detecting failures. - - -#### Port Inferencing - -If you're deploying to a cloud machine, a firewall might block the port 4321. -We can tell Brooklyn to open this port explicitly by specifying `inboundPorts: [ 4321 ]`; -however a more idiomatic way is to specify a config ending with `.port`, -such as: - -{% highlight yaml %} -{% readj example_yaml/vanilla-bash-netcat-port.yaml %} -{% endhighlight %} - -The regex for ports to be opened can be configured using -the config `inboundPorts.configRegex` (which has `.*\.port` as the default value). - -Config keys of type `org.apache.brooklyn.api.location.PortRange` (aka `port`) -have special behaviour: when configuring, you can use range notation `8000-8100` or `8000+` to tell Brooklyn -to find **one** port matching; this is useful when ports might be in use. -In addition, any such config key will be opened, -irrespective of whether it matches the `inboundPorts.configRegex`. -To prevent any inferencing of ports to open, you can set the config `inboundPorts.autoInfer` to `false`. - -Furthermore, the port inferencing capability takes in account static `ConfigKey` fields that -are defined on any Entity sub-class. So, `ConfigKey` fields that are based on `PortRanges` type will -be also included as required open ports. - -Note that in the example above, `netcat.port` must be specified in a `brooklyn.config` block. -This block can be used to hold any config (including for example the `launch.command`), -but for convenience Brooklyn allows config keys declared on the underlying type -to be specified up one level, alongside the type. -However config keys which are *not* declared on the type *must* be declared in the `brooklyn.config` block. - - -### Passing custom variables - -Blueprint scripts can be parametrised through environment variables, making them reusable in different use-cases. -Define the variables in the `env` block and then reference them using the standard bash notation: - -{% highlight yaml %} -{% readj example_yaml/vanilla-bash-netcat-env.yaml %} -{% endhighlight %} - -Non-string objects in the `env` map will be serialized to JSON before passing them to the script. - - -#### Declaring New Config Keys - -We can define config keys to be presented to the user -using the `brooklyn.parameters` block: - -{% highlight yaml %} -{% readj example_yaml/vanilla-bash-netcat-port-parameter.yaml %} -{% endhighlight %} - -The example above will allow a user to specify a message to send back -and the port where netcat will listen. -The metadata on these parameters is available at runtime in the UI -and through the API, and is used when populating a catalog. - -The example also shows how these values can be passed as environment variables to the launch command. -The `$brooklyn:config(...)` function returns the config value supplied or default. -For the type `port`, an attribute sensor is also created to report the *actual* port used after port inference, -and so the `$brooklyn:attributeWhenReady(...)` function is used. -(If `$brooklyn:config("netcat.port")` had been used, `4321+` would be passed as `NETCAT_PORT`.) - -This gives us quite a bit more power in writing our blueprint: - -* Multiple instances of the server can be launched simultaneously on the same host, - as the `4321+` syntax enables Brooklyn to assign them different ports -* If this type is added to the catalog, a user can configure the message and the port; - we'll show this in the next section - - -### Using the Catalog and Clustering - -The *Catalog* tab allows you to add blueprints which you can refer to in other blueprints. -In that tab, click *+* then *YAML*, and enter the following: - -{% highlight yaml %} -{% readj example_yaml/vanilla-bash-netcat-catalog.bom %} -{% endhighlight %} - -This is the same example as in the previous section, wrapped according to the catalog YAML requirements, -with one new block added defining an enricher. An enricher creates a new sensor from other values; -in this case it will create a `main.uri` sensor by populating a `printf`-style string `"http://%s:%s"` -with the sensor values. - -With this added to the catalog, we can reference the type `netcat-example` when we deploy an application. -Return to the *Home* or *Applications* tab, click *+*, and submit this YAML blueprint: - -{% highlight yaml %} -{% readj example_yaml/vanilla-bash-netcat-reference.yaml %} -{% endhighlight %} - -This extends the previous blueprint which we registered in the catalog, -meaning that we don't need to include it each time. -Here, we've elected to supply our own message, but we'll use the default port. -More importantly, we can package it for others to consume -- or take items others have built. - -We can go further and use this to deploy a cluster, -this time giving a custom port as well as a custom message: - -{% highlight yaml %} -{% readj example_yaml/vanilla-bash-netcat-cluster.yaml %} -{% endhighlight %} - -In either of the above examples, if you explore the tree in the *Applications* view -and look at the *Summary* tab of any of the server instances, you'll now see the URL where netcat is running. -But remember, netcat will stop after one run, so you'll only be able to use each link once -before you have to restart it. You can also run `restart` on the cluster, -and if you haven't yet experimented with `resize` on the cluster you might want to do that. - - -### Attaching Policies - -Besides detecting this failure, Brooklyn policies can be added to the YAML to take appropriate -action. A simple recovery here might just to automatically restart the process: - -{% highlight yaml %} -{% readj example_yaml/vanilla-bash-netcat-restarter.yaml %} -{% endhighlight %} - -Autonomic management in Brooklyn often follows the principle that complex behaviours emerge -from composing simple policies. -The blueprint above uses one policy to triggering a failure sensor when the service is down, -and another responds to such failures by restarting the service. -This makes it easy to configure various aspects, such as to delay to see if the service itself recovers -(which here we've set to 15 seconds) or to bail out on multiple failures within a time window (which again we are not doing). -Running with this blueprint, you'll see that the service shows as on fire for 15s after a `telnet localhost 4321`, -before the policy restarts it. - - -### Sensors and Effectors - -#### Effectors - -For an even more interesting way to test it, look at the blueprint defining -[a netcat server and client](example_yaml/vanilla-bash-netcat-w-client.yaml). -This uses `brooklyn.initializers` to define an effector to `sayHiNetcat` on the `Simple Pinger` client, -using `env` variables to inject the `netcat-server` location and -`parameters` to pass in per-effector data: - - env: - TARGET_HOSTNAME: $brooklyn:entity("netcat-server").attributeWhenReady("host.name") - brooklyn.initializers: - - type: org.apache.brooklyn.core.effector.ssh.SshCommandEffector - brooklyn.config: - name: sayHiNetcat - description: Echo a small hello string to the netcat entity - command: | - echo $message | nc $TARGET_HOSTNAME 4321 - parameters: - message: - description: The string to pass to netcat - defaultValue: hi netcat - - -#### Sensors - -This blueprint also uses initializers to define sensors on the `netcat-server` entity -so that the `$message` we passed above gets logged and reported back: - - launch.command: | - echo hello | nc -l 4321 >> server-input & - echo $! > $PID_FILE - brooklyn.initializers: - - type: org.apache.brooklyn.core.sensor.ssh.SshCommandSensor - brooklyn.config: - name: output.last - period: 1s - command: tail -1 server-input - - -#### Windows Command Sensor - -Like the blueprint above, the following example also uses `brooklyn.initializers` to define sensors on the entity, -this time however it is a windows VM and uses `WinRmCommandSensor`. - - - type: org.apache.brooklyn.entity.software.base.VanillaWindowsProcess - brooklyn.config: - launch.command: echo launching - checkRunning.command: echo running - brooklyn.initializers: - - type: org.apache.brooklyn.core.sensor.windows.WinRmCommandSensor - brooklyn.config: - name: ip.config - period: 60s - command: hostname - - -#### Health Check Sensors - -As mentioned [previously](#periodic-health-check), the default health check is to execute the check-running -command over ssh every 5 seconds. This can be very CPU intensive when there are many entities. An alternative -is to disable the ssh-polling (by setting `sshMonitoring.enabled: false`) and to configure a different -health-check. - -See documentation on the [Entity's error status]({{ site.path.guide }}/ops/troubleshooting/overview.html#entitys-error-status) -for how Brooklyn models an entity's health. - -In the snippet below, we'll define a new health-check sensor (via http polling), and will automatically add this -to the `service.notUp.indicators`. If that map is non-empty, then the entity's `service.isUp` will be set -automatically to `false`: - - services: - - type: org.apache.brooklyn.entity.software.base.VanillaSoftwareProcess - brooklyn.config: - launch.command: | - ... - checkRunning.command: true - sshMonitoring.enabled: false - - brooklyn.initializers: - - type: org.apache.brooklyn.core.sensor.http.HttpRequestSensor - brooklyn.config: - name: http.healthy - period: 5s - suppressDuplicates: true - jsonPath: "$" - uri: - $brooklyn:formatString: - - "http://%s:8080/healthy"; - - $brooklyn:attributeWhenReady("host.name") - - brooklyn.enrichers: - - type: org.apache.brooklyn.enricher.stock.UpdatingMap - brooklyn.config: - enricher.sourceSensor: $brooklyn:sensor("http.healthy") - enricher.targetSensor: $brooklyn:sensor("service.notUp.indicators") - enricher.updatingMap.computing: - $brooklyn:object: - type: "com.google.guava:com.google.common.base.Functions" - factoryMethod.name: "forMap" - factoryMethod.args: - - true: null - false: "false" - - "no value" - -The `HttpRequestSensor` configures the entity to poll every 5 seconds on the given URI, -taking the json result as the sensor value. - -The `UpdatingMap` enricher uses that sensor to populate an entry in the `service.notUp.indicators`. -It transforms the `http.healthy` sensor value using the given function: if the http poll returned -`true`, then it is mapped to `null` (so is removed from the `service.noUp.indicators`); if the -poll returned `false`, then `"false"` is added to the indicators map; otherwise `"no value"` is -added to the indicators map. - - -#### Summary - -These examples do relatively simple things, but they -illustrate many of the building blocks used in real-world blueprints, -and how they can often be easily described and combined in Brooklyn YAML blueprints. http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/58bb3aa0/guide/blueprints/effectors.md ---------------------------------------------------------------------- diff --git a/guide/blueprints/effectors.md b/guide/blueprints/effectors.md deleted file mode 100644 index 41eb645..0000000 --- a/guide/blueprints/effectors.md +++ /dev/null @@ -1,185 +0,0 @@ ---- -title: Effectors -layout: website-normal ---- - -Effectors perform an operation of some kind, carried out by a Brooklyn Entity. -They can be manually invoked or triggered by a [Policy]({{ site.path.guide }}/blueprints/policies.html). - -Common uses of an effector include the following: - -* Perform a command on a remote machine. -* Collect data and publish them to sensors. - -Entities have default effectors, the lifecycle management effectors like `start`, `stop`, `restart`, and clearly more `Effectors` can be attached to them. - -Off-the-Shelf Effectors ----------------------- - -Effectors are highly reusable as their inputs, thresholds and targets are customizable. - -### SSHCommandEffector - -An `Effector` to invoke a command on a node accessible via SSH. - -It enables execution of a `command` in a specific `execution director` (executionDir) by using a custom `shell environment` (shellEnv). -By default, the specified command will be executed on the entity where the effector is attached or on all *children* or all *members* (if it is a group) by configuring `executionTarget`. - -There are a number of additional configuration keys available for the `SSHCommandEffector`: - -| Configuration Key | Default | Description | -|-----------------------------------|---------|--------------------------------------------------------------------------------------| -| command | | command to be executed on the execution target | -| executionDir | | possible values: 'GET', 'HEAD', 'POST', 'PUT', 'PATCH', 'DELETE', 'OPTIONS', 'TRACE' | -| shellEnv | | custom shell environment where the command is executed | -| executionTarget | ENTITY | possible values: 'MEMBERS', 'CHILDREN' | - -Here is a simple example of an `SshCommandEffector` definition: - -{% highlight yaml %} - brooklyn.initializers: - - type: org.apache.brooklyn.core.effector.ssh.SshCommandEffector - brooklyn.config: - name: sayHiNetcat - description: Echo a small hello string to the netcat entity - command: | - echo $message | nc $TARGET_HOSTNAME 4321 - parameters: - message: - description: The string to pass to netcat - defaultValue: hi netcat -{% endhighlight %} - -See [`here`](https://brooklyn.apache.org/v/latest/misc/javadoc/org/apache/brooklyn/core/effector/ssh/SshCommandEffector.html) for more details. - -### HTTPCommandEffector - -An `Effector` to invoke HTTP endpoints. - -It allows the user to specify the URI, the HTTP verb, credentials for authentication and HTTP headers. - -There are a number of additional configuration keys available for the `HTTPCommandEffector`: - -| Configuration Key | Default | Description | -|-----------------------------------|------------------|---------------------------------------------------------------------------------------------------------------| -| uri | | URI of the endpoint | -| httpVerb | | possible values: 'GET', 'HEAD', 'POST', 'PUT', 'PATCH', 'DELETE', 'OPTIONS', 'TRACE' | -| httpUsername | | user name for the authentication | -| httpPassword | | password for the authentication | -| headers | application/json | It explicitly supports `application/x-www-form-urlencoded` | -| httpPayload | | The body of the http request | -| jsonPath | | A jsonPath expression to extract values from a json object | -| jsonPathAndSensors | | A map where keys are jsonPath expressions and values the name of the sensor where to publish extracted values | - - -When a the header `HttpHeaders.CONTENT_TYPE` is equals to *application/x-www-form-urlencoded* and the `httpPayload` is a `map`, the payload is transformed into a single string using `URLEncoded`. - -{% highlight yaml %} -brooklyn.initializers: -- type: org.apache.brooklyn.core.effector.http.HttpCommandEffector - brooklyn.config: - name: request-access-token - description: Request an access token for the Azure API - uri: - $brooklyn:formatString: - - "https://login.windows.net/%s/oauth2/token"; - - $brooklyn:config("tenant.id") - httpVerb: POST - httpPayload: - resource: https://management.core.windows.net/ - client_id: $brooklyn:config("application.id") - grant_type: client_credentials - client_secret: $brooklyn:config("application.secret") - jsonPathAndSensors: - $.access_token: access.token - headers: - Content-Type: "application/x-www-form-urlencoded" -{% endhighlight %} - -See [`here`](https://brooklyn.apache.org/v/latest/misc/javadoc/org/apache/brooklyn/core/effector/http/HttpCommandEffector.html) for more details. - -### AddChildrenEffector - -An `Effector` to add a child blueprint to an entity. - -{% highlight yaml %} -brooklyn.initializers: -- type: org.apache.brooklyn.core.effector.AddChildrenEffector - brooklyn.config: - name: add_tomcat - blueprint_yaml: | - name: sample - description: Tomcat sample JSP and servlet application. - origin: http://www.oracle.com/nCAMP/Hand - services: - - - type: io.camp.mock:AppServer - name: Hello WAR - wars: - /: hello.war - controller.spec: - port: 80 - - brooklyn.catalog: - name: catalog-name - type: io.camp.mock.MyApplication - version: 0.9 - libraries: - - name: org.apache.brooklyn.test.resources.osgi.brooklyn-test-osgi-entities - version: 0.1.0 - url: classpath:/brooklyn/osgi/brooklyn-test-osgi-entities.jar - auto_start: true -{% endhighlight %} - -One of the config keys `BLUEPRINT_YAML` (containing a YAML blueprint (map or string)) or `BLUEPRINT_TYPE` (containing a string referring to a catalog type) should be supplied, but not both. - -See [`here`](https://brooklyn.apache.org/v/latest/misc/javadoc/org/apache/brooklyn/core/effector/AddChildrenEffector.html) for more details. - -Writing an Effector -------------------- - -### Your First Effector - -Effectors generally perform actions on entities. -Each effector instance is associated with an entity, -and at runtime it will typically exectute an operation, collect the result and, potentially, publish it as sensor on that entity, performing some computation. - -Writing an effector is straightforward. -Simply extend [`AddEffector`](https://brooklyn.apache.org/v/latest/misc/javadoc/org/apache/brooklyn/core/effector/AddEffector.html), -providing an implementation for `newEffectorBuilder` and adding a constructor that consumes the builder or override an existing effector. - -{% highlight java %} - - public MyEffector(ConfigBag params) { - super(newEffectorBuilder(params).build()); -} - -public static EffectorBuilder<String> newEffectorBuilder(ConfigBag params) { - EffectorBuilder<String> eff = AddEffector.newEffectorBuilder(String.class, params); - eff.impl(new Body(eff.buildAbstract(), params)); - return eff; -} -{% endhighlight %} - -and supply an `EffectorBody` similar to: - -{% highlight java %} - -protected static class Body extends EffectorBody<String> { - ... - - @Override - public String call(final ConfigBag params) { - ... - } -} -{% endhighlight %} - -### Best Practice - -The following recommendations should be considered when designing effectors: - -#### Effectors should be small and composable - -One effector which executes a command and emits a sensor, and a second effector which uses the previous sensor, if defined, to execute another operation. - http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/58bb3aa0/guide/blueprints/enrichers.md ---------------------------------------------------------------------- diff --git a/guide/blueprints/enrichers.md b/guide/blueprints/enrichers.md deleted file mode 100644 index 6ef1247..0000000 --- a/guide/blueprints/enrichers.md +++ /dev/null @@ -1,145 +0,0 @@ ---- -title: Enrichers -layout: website-normal -toc: ../guide_toc.json -categories: [use, guide, defining-applications] ---- - -Enrichers provide advanced manipulation of an entity's sensor values. -See below for documentation of the stock enrichers available in Apache Brooklyn. - -#### Transformer - -[`org.apache.brooklyn.enricher.stock.Transformer`](https://brooklyn.apache.org/v/latest/misc/javadoc/org/apache/brooklyn/enricher/stock/Transformer.html) - -Takes a source sensor and modifies it in some way before publishing the result in a new sensor. See below an example using `$brooklyn:formatString`. - -{% highlight yaml %} -{% readj example_yaml/enricher-transformer.yaml %} -{% endhighlight %} - -#### Propagator - -[`org.apache.brooklyn.enricher.stock.Propagator`](https://brooklyn.apache.org/v/latest/misc/javadoc/org/apache/brooklyn/enricher/stock/Propagator.html) - -Use propagator to duplicate one sensor as another, giving the supplied sensor mapping. -The other use of Propagator is where you specify a producer (using `$brooklyn:entity(...)` as below) -from which to take sensors; in that mode you can specify `propagate` as a list of sensors whose names are unchanged, instead of (or in addition to) this map. - -{% highlight yaml %} -{% readj example_yaml/enricher-propagator.yaml %} -{% endhighlight %} - -#### Custom Aggregating - -[`org.apache.brooklyn.enricher.stock.Aggregator`](https://brooklyn.apache.org/v/latest/misc/javadoc/org/apache/brooklyn/enricher/stock/Aggregator.html) - -Aggregates multiple sensor values (usually across a tier, esp. a cluster) and performs a supplied aggregation method to them to return an aggregate figure, e.g. sum, mean, median, etc. - -{% highlight yaml %} -{% readj example_yaml/enricher-aggregator.yaml %} -{% endhighlight %} - -There are a number of additional configuration keys available for the Aggregators: - -| Configuration Key | Default | Description | -|-----------------------------------|---------|---------------------------------------------------------------------| -| enricher.transformation.untyped | list | Specifies a transformation, as a function from a collection to the value, or as a string matching a pre-defined named transformation, such as 'average' (for numbers), 'sum' (for numbers), 'isQuorate' (to compute a quorum), 'first' (the first value, or null if empty), or 'list' (the default, putting any collection of items into a list) | -| quorum.check.type | | The requirement to be considered quorate -- possible values: 'all', 'allAndAtLeastOne', 'atLeastOne', 'atLeastOneUnlessEmpty', 'alwaysHealthy'", "allAndAtLeastOne" | -| quorum.total.size | 1 | The total size to consider when determining if quorate | - -#### Joiner - -[`org.apache.brooklyn.enricher.stock.Joiner`](https://brooklyn.apache.org/v/latest/misc/javadoc/org/apache/brooklyn/enricher/stock/Joiner.html) - -Joins a sensor whose output is a list into a single item joined by a separator. - -{% highlight yaml %} -{% readj example_yaml/enricher-joiner.yaml %} -{% endhighlight %} - -There are a number of additional configuration keys available for the joiner: - -| Configuration Key | Default | Description | -|-----------------------------------|---------|---------------------------------------------------------------------| -| enricher.joiner.separator | , | Separator string to insert between each argument | -| enricher.joiner.keyValueSeparator | = | Separator string to insert between each key-value pair | -| enricher.joiner.joinMapEntries | false | Whether to add map entries as key-value pairs or just use the value | -| enricher.joiner.quote | true | Whether to bash-escape each parameter and wrap in double-quotes | -| enricher.joiner.minimum | 0 | Minimum number of elements to join; if fewer than this, sets null | -| enricher.joiner.maximum | null | Maximum number of elements to join (null means all elements taken) | - -#### Delta Enricher - -[`org.apache.brooklyn.policy.enricher.DeltaEnricher`](https://brooklyn.apache.org/v/latest/misc/javadoc/org/apache/brooklyn/policy/enricher/DeltaEnricher.html) - -Converts an absolute sensor into a delta sensor (i.e. the difference between the current and previous value) - -#### Time-weighted Delta - -[`org.apache.brooklyn.enricher.stock.YamlTimeWeightedDeltaEnricher`](https://brooklyn.apache.org/v/latest/misc/javadoc/org/apache/brooklyn/enricher/stock/YamlTimeWeightedDeltaEnricher.html) - -Converts absolute sensor values into a difference over time. The `enricher.delta.period` indicates the measurement interval. - -{% highlight yaml %} -{% readj example_yaml/enricher-time-weighted-delta.yaml %} -{% endhighlight %} - -#### Rolling Mean - -[`org.apache.brooklyn.policy.enricher.RollingMeanEnricher`](https://brooklyn.apache.org/v/latest/misc/javadoc/org/apache/brooklyn/policy/enricher/RollingMeanEnricher.html) - -Transforms a sensor into a rolling average based on a fixed window size. This is useful for smoothing sample type metrics, such as latency or CPU time - -#### Rolling Time-window Mean - -[`org.apache.brooklyn.policy.enricher.RollingTimeWindowMeanEnricher`](https://brooklyn.apache.org/v/latest/misc/javadoc/org/apache/brooklyn/policy/enricher/RollingTimeWindowMeanEnricher.html) - -Transforms a sensor's data into a rolling average based on a time window. This time window can be specified with the config key `confidenceRequired` - Minimum confidence level (ie period covered) required to publish a rolling average (default `8d`). - -#### Http Latency Detector - -[`org.apache.brooklyn.policy.enricher.RollingTimeWindowMeanEnricher.HttpLatencyDetector`](https://brooklyn.apache.org/v/latest/misc/javadoc/org/apache/brooklyn/policy/enricher/HttpLatencyDetector.html) - -An Enricher which computes latency in accessing a URL, normally by periodically polling that URL. This is then published in the sensors `web.request.latency.last` and `web.request.latency.windowed`. - -There are a number of additional configuration keys available for the Http Latency Detector: - -| Configuration Key | Default | Description | -|-----------------------------------|---------|----------------------------------------------------------------------| -| latencyDetector.url | | The URL to compute the latency of | -| latencyDetector.urlSensor | | A sensor containing the URL to compute the latency of | -| latencyDetector.urlPostProcessing | | Function applied to the urlSensor value, to determine the URL to use | -| latencyDetector.rollup | | The window size (in duration) over which to compute | -| latencyDetector.requireServiceUp | false | Require the service is up | -| latencyDetector.period | 1s | The period of polling | - -#### Combiner - -[`org.apache.brooklyn.enricher.stock.Combiner`](https://brooklyn.apache.org/v/latest/misc/javadoc/org/apache/brooklyn/enricher/stock/Combiner.html) - -Can be used to combine the values of sensors. This enricher should be instantiated using `Enrichers.builder().combining(..)`. -This enricher is only available in Java blueprints and cannot be used in YAML. - -#### Note On Enricher Producers - -If an entity needs an enricher whose source sensor (`enricher.sourceSensor`) belongs to another entity, then the enricher -configuration must include an `enricher.producer` key referring to the other entity. - -For example, if we consider the Transfomer from above, suppose that `enricher.sourceSensor: $brooklyn:sensor("urls.tcp.list")` -is actually a sensor on a different entity called `load.balancer`. In this case, we would need to supply an -`enricher.producer` value. - -{% highlight yaml %} -{% readj example_yaml/enricher-transformer.yaml %} -{% endhighlight %} - -It is important to note that the value supplied to `enricher.producer` must be immediately resolvable. While it would be valid -DSL syntax to write: - -{% highlight yaml %} -enricher.producer: brooklyn:entity($brooklyn:attributeWhenReady("load.balancer.entity")) -{% endhighlight %} - -(assuming the `load.balancer.entity` sensor returns a Brooklyn entity), this will not function properly because `enricher.producer` -will unsuccessfully attempt to get the supplied entity immediately.
