http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/f38b9e7b/guide/blueprints/chef/index.md ---------------------------------------------------------------------- diff --git a/guide/blueprints/chef/index.md b/guide/blueprints/chef/index.md new file mode 100644 index 0000000..f0fa3d0 --- /dev/null +++ b/guide/blueprints/chef/index.md @@ -0,0 +1,18 @@ +--- +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/blueprints/chef/writing-chef.md ---------------------------------------------------------------------- diff --git a/guide/blueprints/chef/writing-chef.md b/guide/blueprints/chef/writing-chef.md new file mode 100644 index 0000000..671d961 --- /dev/null +++ b/guide/blueprints/chef/writing-chef.md @@ -0,0 +1,79 @@ +--- +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/f38b9e7b/guide/blueprints/clusters-and-policies.md ---------------------------------------------------------------------- diff --git a/guide/blueprints/clusters-and-policies.md b/guide/blueprints/clusters-and-policies.md new file mode 100644 index 0000000..d40c97f --- /dev/null +++ b/guide/blueprints/clusters-and-policies.md @@ -0,0 +1,42 @@ +--- +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. In fact, JBoss is the default appserver, +and because configuration in Brooklyn is 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/f38b9e7b/guide/blueprints/clusters.md ---------------------------------------------------------------------- diff --git a/guide/blueprints/clusters.md b/guide/blueprints/clusters.md new file mode 100644 index 0000000..4c1312c --- /dev/null +++ b/guide/blueprints/clusters.md @@ -0,0 +1,34 @@ +--- +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/f38b9e7b/guide/blueprints/configuring-vms.md ---------------------------------------------------------------------- diff --git a/guide/blueprints/configuring-vms.md b/guide/blueprints/configuring-vms.md new file mode 100644 index 0000000..e7e7f47 --- /dev/null +++ b/guide/blueprints/configuring-vms.md @@ -0,0 +1,31 @@ +--- +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/f38b9e7b/guide/blueprints/creating-yaml.md ---------------------------------------------------------------------- diff --git a/guide/blueprints/creating-yaml.md b/guide/blueprints/creating-yaml.md new file mode 100644 index 0000000..6f91784 --- /dev/null +++ b/guide/blueprints/creating-yaml.md @@ -0,0 +1,78 @@ +--- +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/f38b9e7b/guide/blueprints/custom-entities.md ---------------------------------------------------------------------- diff --git a/guide/blueprints/custom-entities.md b/guide/blueprints/custom-entities.md new file mode 100644 index 0000000..88d62ff --- /dev/null +++ b/guide/blueprints/custom-entities.md @@ -0,0 +1,269 @@ +--- +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 consists of the two lines in the previous example, +we can instead write our example as: + +{% highlight yaml %} +{% readj example_yaml/vanilla-bash-netcat-file.yaml %} +{% endhighlight %} + + +#### 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. + + +#### Determining Successful Launch + +One requirement of the launch script is that it store the process ID (PID) in the file +pointed to by `$PID_FILE`, hence the second line of the script. +This is because Brooklyn wants to monitor the services under management. +You'll observe this if you connect to one of the netcat services, +as the process exits afterwards and Brooklyn sets the entity to an `ON_FIRE` state. +(You can also test this with a `killall nc` before connecting +or issueing a `stop` command on the server -- but not on the example, +as stopping an application root causes it to be removed altogether!) + +There are other options for determining launch: 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`. + +{% highlight yaml %} +{% readj example_yaml/vanilla-bash-netcat-more-commands.yaml %} +{% endhighlight %} + +And indeed, once you've run one `telnet` to the server, you'll see that the +service has gone "on fire" in Brooklyn -- because the `nc` process stops after one run. + + +#### 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`, +before the policy restarts it. + + +### Sensors and 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 `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 + +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 + +#### Summary + +These examples are relatively simple example, 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. +Next, if you need to drive off-piste, or you want to write tests against these blueprints, +have a look at, for example, `VanillaBashNetcatYamlTest.java` in the Brooklyn codebase, +or follow the other references below. http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/f38b9e7b/guide/blueprints/enrichers.md ---------------------------------------------------------------------- diff --git a/guide/blueprints/enrichers.md b/guide/blueprints/enrichers.md new file mode 100644 index 0000000..436a423 --- /dev/null +++ b/guide/blueprints/enrichers.md @@ -0,0 +1,180 @@ +--- +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 %} +brooklyn.enrichers: +- 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")) +{% 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 %} +brooklyn.enrichers: +- type: org.apache.brooklyn.enricher.stock.Propagator + brooklyn.config: + producer: $brooklyn:entity("cluster") +- type: org.apache.brooklyn.enricher.stock.Propagator + brooklyn.config: + sensorMapping: + $brooklyn:sensor("url"): $brooklyn:sensor("org.apache.brooklyn.core.entity.Attributes", "main.uri") +{% 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 %} +brooklyn.enrichers: +- type: org.apache.brooklyn.enricher.stock.Aggregator + brooklyn.config: + enricher.sourceSensor: $brooklyn:sensor("webapp.reqs.perSec.windowed") + enricher.targetSensor: $brooklyn:sensor("webapp.reqs.perSec.perNode") + enricher.aggregating.fromMembers: true + transformation: average +{% 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), 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 %} +brooklyn.enrichers: +- 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 +{% 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 %} +brooklyn.enrichers: +- type: org.apache.brooklyn.enricher.stock.YamlTimeWeightedDeltaEnricher + brooklyn.config: + enricher.sourceSensor: reqs.count + enricher.targetSensor: reqs.per_sec + enricher.delta.period: 1s +{% 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 %} +brooklyn.enrichers: +- type: org.apache.brooklyn.enricher.stock.Transformer + brooklyn.config: + enricher.producer: $brooklyn:entity("load.balancer") + enricher.sourceSensor: $brooklyn:sensor("urls.tcp.string") + enricher.targetSensor: $brooklyn:sensor("urls.tcp.withBrackets") + enricher.targetValue: | + $brooklyn:formatString("[%s]", $brooklyn:attributeWhenReady("urls.tcp.string")) +{% 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. http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/f38b9e7b/guide/blueprints/entity-configuration.md ---------------------------------------------------------------------- diff --git a/guide/blueprints/entity-configuration.md b/guide/blueprints/entity-configuration.md new file mode 100644 index 0000000..14561ac --- /dev/null +++ b/guide/blueprints/entity-configuration.md @@ -0,0 +1,548 @@ +--- +title: Entity Configuration +layout: website-normal +toc: ../guide_toc.json +categories: [use, guide, defining-applications] +--- + +Within a blueprint or catalog item, entities can be configured. The rules for setting this +configuration, including when composing and extending existing entities, is described in this +section. + + +### Basic Configuration + +Within a YAML file, entity configuration should be supplied within a `brooklyn.config` map. It is +also possible to supply configuration at the top-level of the entity. However, that approach is +discouraged as it can sometimes be ambiguous (e.g. if the config key is called "name" or "type"), +and also it does not work in all contexts such as for an enricher's configuration. + +A simple example is shown below: + +{% highlight yaml %} +services: +- type: org.apache.brooklyn.entity.webapp.tomcat.TomcatServer + brooklyn.config: + webapp.enabledProtocols: http + http.port: 9080 + wars.root: http://search.maven.org/remotecontent?filepath=org/apache/brooklyn/example/brooklyn-example-hello-world-webapp/0.9.0/brooklyn-example-hello-world-webapp-0.9.0.war +{% endhighlight %} + +If no config value is supplied, the default for that config key will be used. For example, +`http.port` would default to 8080 if not explicitly supplied. + +Some config keys also have a short-form (e.g. `httpPort` instead of `http.port` would also work +in the YAML example above). However, that approach is discouraged as it does not work in all contexts +such as for inheriting configuration from a parent entity. + + +### Configuration in a Catalog Item + +When defining an entity in the catalog, it can include configuration values like any other +blueprint (i.e. inside the `brooklyn.config` block). + +It can also explicitly declare config keys, using the `brooklyn.parameters` block. The example +below illustrates the principle: + +{% highlight yaml %} +brooklyn.catalog: + items: + - id: entity-config-example + itemType: entity + name: Entity Config Example + item: + type: org.apache.brooklyn.entity.software.base.VanillaSoftwareProcess + brooklyn.parameters: + - name: custom.message + type: string + description: Message to be displayed + default: Hello + brooklyn.config: + shell.env: + MESSAGE: $brooklyn:config("custom.message") + launch.command: | + echo "My example launch command: $MESSAGE" + checkRunning.command: | + echo "My example checkRunning command: $MESSAGE" +{% endhighlight %} + +Once added to the catalog, it can be used with the simple blueprint below (substituting the location +of your choice). Because no configuration has been overridden, this will use the default value +for `custom.message`, and will use the given values for `launch.command` and `checkRunning.command`: + +{% highlight yaml %} +location: aws-ec2:us-east-1 +services: +- type: entity-config-example +{% endhighlight %} + +For details of how to write and add catalog items, see [Catalog]({{ site.path.guide }}/blueprints/catalog/). + + +#### Config Key Constraints + +The config keys in the `brooklyn.parameters` can also have constraints defined, for what values +are valid. If more than one constraint is defined, then they must all be satisfied. The constraints +can be any of: + +* `required`: deployment will fail if no value is supplied for this config key. +* `regex: ...`: the value will be compared against the given regular expression. +* A predicate, declared using the DSL `$brooklyn:object`. + +This is illustrated in the example below: + +{% highlight yaml %} +brooklyn.catalog: + items: + - id: entity-constraint-example + itemType: entity + name: Entity Config Example + item: + type: org.apache.brooklyn.entity.stock.BasicEntity + brooklyn.parameters: + - name: compulsoryExample + type: string + constraints: + - required + - name: addressExample + type: string + constraints: + - regex: ^(?:[0-9]{1,3}\.){3}[0-9]{1,3}$ + - name: numberExample + type: double + constraints: + - $brooklyn:object: + type: org.apache.brooklyn.util.math.MathPredicates + factoryMethod.name: greaterThan + factoryMethod.args: + - 0.0 + - $brooklyn:object: + type: org.apache.brooklyn.util.math.MathPredicates + factoryMethod.name: lessThan + factoryMethod.args: + - 256.0 +{% endhighlight %} + +An example usage of this toy example, once added to the catalog, is shown below: + +{% highlight yaml %} +services: +- type: entity-constraint-example + brooklyn.config: + compulsoryExample: foo + addressExample: 1.1.1.1 + numberExample: 2.0 +{% endhighlight %} + + +### Inheriting Configuration + +Configuration can be inherited from a super-type, and from a parent entity in the runtime +management hierarchy. This applies to entities and locations. In a future release, this will be +extended to also apply to policies and enrichers. + +When a blueprint author defines a config key, they can explicitly specify the rules for inheritance +(both for super/sub-types, and for the runtime management hiearchy). This gives great flexibilty, +but should be used with care so as not to surprise users of the blueprint. + +The default behaviour is outlined below, along with examples and details of how to explilcitly +define the desired behaviour. + + +#### Normal Configuration Precedence + +There are several places that a configuration value can come from. If different values are +specified in multiple places, then the order of precedence is as listed below: + +1. Configuration on the entity itself +2. Inherited configuration from the super-type +3. Inherited configuration from the runtime type hierarchy +4. The config key's default value + + +#### Inheriting Configuration from Super-type + +When using an entity from the catalog, its configuration values can be overridden. For example, +consider the `entity-config-example` added to the catalog in the section +[Configuration in a Catalog Item](#configuration-in-a-catalog-item). +We can override these values. If not overridden, then the existing values from the super-type will be used: + +{% highlight yaml %} +location: aws-ec2:us-east-1 +services: +- type: entity-config-example + brooklyn.config: + custom.message: Goodbye + launch.command: | + echo "Sub-type launch command: $MESSAGE" +{% endhighlight %} + + + +In this example, the `custom.message` overrides the default defined on the config key. +The `launch.command` overrides the original command. The other config (e.g. `checkRunning.command`) +is inherited unchanged. + +It will write out: `Sub-type launch command: Goodbye`. + + +#### Inheriting Configuration from a Parent in the Runtime Management Hieararchy + +Configuration passed to an entity is inherited by all child entities, unless explicitly overridden. + +In the example below, the `wars.root` config key is inherited by all TomcatServer entities created +under the cluster, so they will use that war: + +{% highlight yaml %} +services: +- type: org.apache.brooklyn.entity.group.DynamicCluster + brooklyn.config: + wars.root: http://search.maven.org/remotecontent?filepath=org/apache/brooklyn/example/brooklyn-example-hello-world-webapp/0.9.0/brooklyn-example-hello-world-webapp-0.9.0.war + dynamiccluster.memberspec: + $brooklyn:entitySpec: + type: org.apache.brooklyn.entity.webapp.tomcat.TomcatServer +{% endhighlight %} + +In the above example, it would be better to have specified the `wars.root` configuration in the +`TomcatServer` entity spec, rather than at the top level. This would make it clearer for the reader +what is actually being configured. + +The technique of inherited config can simplify some blueprints, but care should be taken. +For more complex (composite) blueprints, this can be difficult to use safely; it relies on +knowledge of the internals of the child components. For example, the inherited config +may impact multiple sub-components, rather than just the specific entity to be changed. +This is particularly true when using complex items from the catalog, and when using common config +values (e.g. `install.version`). + +An alternative approach is to declare the expected configuration options at the top level of the +catalog item, and then (within the catalog item) explicitly inject those values into the correct +sub-components. Users of this catalog item would set only those exposed config options, rather +than trying to inject config directly into the nested entities. + + +#### DSL Evaluation of Inherited Config + +When writing blueprints that rely on inheritance from the runtime management hierarchy, it is +important to understand how config keys that use DSL will be evaluated. In particular, when +evaluating a DSL expression, it will be done in the context of the entity declaring the config +value (rather than on the entity using the config value). + +For example, consider the config value `$brooklyn:attributeWhenReady("host.name")` +declared on entity X, and inherited by child entity Y. If entity Y uses this config value, +it will get the "host.name" attribute of entity X. + +Below is another (contrived!) example of this DSL evaluation. When evaluating `refExampleConfig`, +it retrievies the value of `exampleConfig` which is the DSL expression, and evaluates this in the +context of the parent entity that declares it. Therefore `$brooklyn:config("ownConfig")` returns +the parent's `ownConfig` value, and the final result for `refExampleConfig` is set to "parentValue": + +{% highlight yaml %} +services: +- type: org.apache.brooklyn.entity.stock.BasicApplication + brooklyn.config: + ownConfig: parentValue + exampleConfig: $brooklyn:config("ownConfig") + + brooklyn.children: + - type: org.apache.brooklyn.entity.stock.BasicEntity + brooklyn.config: + ownConfig: childValue + refExampleConfig: $brooklyn:config("exampleConfig") +{% endhighlight %} + +_However, the web-console also shows other misleading (incorrect!) config values for the child +entity. It shows the inherited config value of `exampleConfig` as "childValue" (because the +REST api did not evaluate the DSL in the correct context, when retrieving the value! +See https://issues.apache.org/jira/browse/BROOKLYN-455._ + + +#### Merging Configuration Values + +For some configuration values, the most logical behaviour is to merge the configuration value +with that in the super-type. This depends on the type and meaning of the config key, and is thus +an option when defining the config key. + +Currently it is only supported for merging config keys of type Map. + +Some common config keys will default to merging the values from the super-type. These config keys +include those below. The value is merged with that of its super-type (but will not be merged with +the value on a parent entity): + +* `shell.env`: a map of environment variables to pass to the runtime shell +* `files.preinstall`: a mapping of files, to be copied before install, to destination name relative to installDir +* `templates.preinstall`: a mapping of templates, to be filled in and copied before pre-install, to destination name relative to installDir +* `files.install`: a mapping of files, to be copied before install, to destination name relative to installDir +* `templates.install`: a mapping of templates, to be filled in and copied before install, to destination name relative to installDir +* `files.runtime`: a mapping of files, to be copied before customisation, to destination name relative to runDir +* `templates.runtime`: a mapping of templates, to be filled in and copied before customisation, to destination name relative to runDir +* `provisioning.properties`: custom properties to be passed in when provisioning a new machine + +A simple example of merging `shell.env` is shown below (building on the `entity-config-example` in +the section [Configuration in a Catalog Item](#configuration-in-a-catalog-item)). +The environment variables will include the `MESSAGE` +set in the super-type and the `MESSAGE2` set here: + +{% highlight yaml %} +location: aws-ec2:us-east-1 +services: +- type: entity-config-example + brooklyn.config: + shell.env: + MESSAGE2: Goodbye + launch.command: | + echo "Different example launch command: $MESSAGE and $MESSAGE2" +{% endhighlight %} + +To explicitly remove a value from the super-type's map (rather than adding to it), a blank entry +can be defined. + + +#### Entity provisioning.properties: Overriding and Merging + +An entity (which extends `SoftwareProcess`) can define a map of `provisioning.properties`. If +the entity then provisions a location, it passes this map of properties to the location for +obtaining the machine. These properties will override and augment the configuration on the location +itself. + +When deploying to a jclouds location, one can specify `templateOptions` (of type map). Rather than +overriding, these will be merged with any templateOptions defined on the location. + +In the example below, the VM will be provisioned with minimum 2G ram and minimum 2 cores. It will +also use the merged template options value of +`{placementGroup: myPlacementGroup, securityGroupIds: sg-000c3a6a}`: + +{% highlight yaml %} +location: + aws-ec2:us-east-1: + minRam: 2G + templateOptions: + placementGroup: myPlacementGroup +services: +- type: org.apache.brooklyn.entity.machine.MachineEntity + brooklyn.config: + provisioning.properties: + minCores: 2 + templateOptions: + securityGroupIds: sg-000c3a6a +{% endhighlight %} + +The merging of `templateOptions` is shallow (i.e. maps within the `templateOptions` are not merged). +In the example below, the `userMetadata` value within `templateOptions` will be overridden by the +entity's value, rather than the maps being merged; the value used when provisioning will be +`{key2: val2}`: + +{% highlight yaml %} +location: + aws-ec2:us-east-1: + templateOptions: + userMetadata: + key1: val1 +services: +- type: org.apache.brooklyn.entity.machine.MachineEntity + brooklyn.config: + provisioning.properties: + userMetadata: + key2: val2 +{% endhighlight %} + + +#### Re-inherited Versus not Re-inherited + +For some configuration values, the most logical behaviour is for an entity to "consume" the config +key's value, and thus not pass it down to children in the runtime type hierarchy. This is called +"not re-inherited". + +Some common config keys that will not re-inherited include: + +* `install.command` (and the `pre.install.command` and `post.install.command`) +* `customize.command` (and the `pre.customize.command` and `post.customize.command`) +* `launch.command` (and the ``pre.launch.command` and `post.launch.command`) +* `checkRunning.command` +* `stop.command` +* The similar commands for `VanillaWindowsProcess` powershell. +* The file and template install config keys (e.g. `files.preinstall`, `templates.preinstall`, etc) + +An example is shown below. Here, the "logstash-child" is a sub-type of `VanillaSoftwareProcess`, +and is co-located on the same VM as Tomcat. We don't want the Tomcat's configuration, such as +`install.command`, to be inherited by the logstash child. If it was inherited, the logstash-child +entity might re-execute the Tomcat's install command! Instead, the `install.command` config is +"consumed" by the Tomcat instance and is not re-inherited: + +{% highlight yaml %} +services: +- type: org.apache.brooklyn.entity.webapp.tomcat.Tomcat8Server + brooklyn.config: + children.startable.mode: background_late + brooklyn.children: + - type: logstash-child + brooklyn.config: + logstash.elasticsearch.host: $brooklyn:entity("es").attributeWhenReady("urls.http.withBrackets") +... +{% endhighlight %} + +"Not re-inherited" differs from "never inherited". The example below illustrates the difference, +though this use is discouraged (it is mostly for backwards compatibility). The `post.install.command` +is not consumed by the `BasicApplication`, so will be inherited by the `Tomcat8Server` which will +consume it. The config value will therefore not be inherited by the `logstash-child`. + +{% highlight yaml %} +services: +- type: org.apache.brooklyn.entity.stock.BasicApplication + brooklyn.config: + post.install.command: echo "My post.install command" + brooklyn.children: + - type: org.apache.brooklyn.entity.webapp.tomcat.Tomcat8Server + brooklyn.config: + children.startable.mode: background_late + brooklyn.children: + - type: logstash-child + brooklyn.config: + logstash.elasticsearch.host: $brooklyn:entity("es").attributeWhenReady("urls.http.withBrackets") +... +{% endhighlight %} + + +#### Never Inherited + +For some configuration values, the most logical behaviour is for the value to never be inherited +in the runtime management hiearchy. + +Some common config keys that will never inherited include: + +* `defaultDisplayName`: this is the name to use for the entity, if an explicit name is not supplied. + This is particularly useful when adding an entity in a catalog item (so if the user does not give + a name, it will get a sensible default). It would not be intuitive for all the children of that + entity to also get that default name. + +* `id`: the id of an entity (as supplied in the YAML, to allow references to that entity) is not + inherited. It is the id of that specific entity, so must not be shared by all its children. + + +#### Inheritance Modes: Deep Dive + +The javadoc in the code is useful for anyone who wants to go deep! See +`org.apache.brooklyn.config.BasicConfigInheritance` and `org.apache.brooklyn.config.ConfigInheritances` +in the repo https://github.com/apache/brooklyn-server. + +When defining a new config key, the exact semantics for inheritance can be defined. There are +separate options to control config inheritance from the super-type, and config inheritance from the +parent in the runtime management hierarchy. + +The possible modes are: + +* `NEVER_INHERITED`: indicates that a key's value should never be inherited (even if defined on + an entity that does not know the key). Most usages will prefer `NOT_REINHERITED`. + +* `NOT_REINHERITED`: indicates that a config key value (if used) should not be passed down to + children / sub-types. Unlike `NEVER_INHERITED`, these values can be passed down if they are not + used by the entity (i.e. if the entity does not expect it). However, when used by a child, + it will not be passed down any further. If the inheritor also defines a value the parent's + value is ignored irrespective (as in `OVERWRITE`; see `NOT_REINHERITED_ELSE_DEEP_MERGE` if merging + is desired). + +* `NOT_REINHERITED_ELSE_DEEP_MERGE`: as `NOT_REINHERITED` but in cases where a value is inherited + because a parent did not recognize it, if the inheritor also defines a value the two values should + be merged. + +* `OVERWRITE`: indicates that if a key has a value at both an ancestor and a descendant, the + descendant and his descendants will prefer the value at the descendant. + +* `DEEP_MERGE`: indicates that if a key has a value at both an ancestor and a descendant, the + descendant and his descendants should attempt to merge the values. If the values are not mergable, + behaviour is undefined (and often the descendant's value will simply overwrite). + + +#### Explicit Inheritance Modes + +_The YAML support for explicitly defining the inheritance mode is still work-in-progress. The options +documented below will be enhanced in a future version of AMP, to better support the modes described +above._ + +In a YAML blueprint, within the `brooklyn.parameters` section for declaring new config keys, one can +set the mode for `inheritance.type` and `inheritance.parent` (i.e. for inheritance from the super-type, and +inheritance in the runtime management hierarchy). The possible values are: + +* `deep_merge`: the inherited and the given value should be merged; maps within the map will also be merged +* `always`: the inherited value should be used, unless explicitly overridden by the entity +* `none`: the value should not be inherited; if there is no explicit value on the entity then the default value will be used + +Below is a (contrived!) example of inheriting the `example.map` config key. When using this entity +in a blueprint, the entity's config will be merged with that defined in the super-type, and the +parent entity's value will never be inherited: + +{% highlight yaml %} +brooklyn.catalog: + items: + - id: entity-config-inheritance-example + version: "1.1.0-SNAPSHOT" + itemType: entity + name: Entity Config Inheritance Example + item: + type: org.apache.brooklyn.entity.machine.MachineEntity + brooklyn.parameters: + - name: example.map + type: java.util.Map + inheritance.type: deep_merge + inheritance.parent: none + default: + MESSAGE_IN_DEFAULT: InDefault + brooklyn.config: + example.map: + MESSAGE: Hello +{% endhighlight %} + +The blueprints below demonstrate the various permutations for setting configuration for the +config `example.map`. This can be inspected by looking at the entity's config. The config +we see for app1 is the inherited `{MESSAGE: "Hello"}`; in app2 we define additional configuration, +which will be merged to give `{MESSAGE: "Hello", MESSAGE_IN_CHILD: "InChild"}`; in app3, the +config from the parent is not inherited because there is an explicit inheritance.parent of "none", +so it just has the value `{MESSAGE: "Hello"}`; in app4 again the parent's config is ignored, +with the super-type and entity's config being merged to give `{MESSAGE: "Hello", MESSAGE_IN_CHILD: "InChild"}`. + +{% highlight yaml %} +location: aws-ec2:us-east-1 +services: +- type: org.apache.brooklyn.entity.stock.BasicApplication + name: app1 + brooklyn.children: + - type: entity-config-inheritance-example + +- type: org.apache.brooklyn.entity.stock.BasicApplication + name: app2 + brooklyn.children: + - type: entity-config-inheritance-example + brooklyn.config: + example.map: + MESSAGE_IN_CHILD: InChild + +- type: org.apache.brooklyn.entity.stock.BasicApplication + name: app3 + brooklyn.config: + example.map: + MESSAGE_IN_PARENT: InParent + brooklyn.children: + - type: entity-config-inheritance-example + +- type: org.apache.brooklyn.entity.stock.BasicApplication + name: app4 + brooklyn.config: + example.map: + MESSAGE_IN_PARENT: InParent + brooklyn.children: + - type: entity-config-inheritance-example + brooklyn.config: + example.map: + MESSAGE_IN_CHILD: InChild +{% endhighlight %} + +A limitations of `inheritance.parent` is when inheriting values from parent and grandparent +entities: a value specified on the parent will override (rather than be merged with) the +value on the grandparent. + + +#### Merging Policy and Enricher Configuration Values + +A current limitation is that sub-type inheritance is not supported for configuration of +policies and enrichers. The current behaviour is that config is not inherited. The concept of +inheritance from the runtime management hierarchy does not apply for policies and enrichers +(they do not have "parents"; they are attached to an entity). http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/f38b9e7b/guide/blueprints/example_yaml/appserver-clustered-w-db-concise.yaml ---------------------------------------------------------------------- diff --git a/guide/blueprints/example_yaml/appserver-clustered-w-db-concise.yaml b/guide/blueprints/example_yaml/appserver-clustered-w-db-concise.yaml new file mode 100644 index 0000000..64ed9a0 --- /dev/null +++ b/guide/blueprints/example_yaml/appserver-clustered-w-db-concise.yaml @@ -0,0 +1,15 @@ +name: appserver-clustered-w-db-concise +services: +- type: org.apache.brooklyn.entity.webapp.ControlledDynamicWebAppCluster + brooklyn.config: + cluster.initial.size: 2 + wars.root: http://search.maven.org/remotecontent?filepath=org/apache/brooklyn/example/brooklyn-example-hello-world-sql-webapp/0.8.0-incubating/brooklyn-example-hello-world-sql-webapp-0.8.0-incubating.war + http.port: 8080+ + java.sysprops: + brooklyn.example.db.url: $brooklyn:formatString("jdbc:%s%s?user=%s\\&password=%s", + component("db").attributeWhenReady("datastore.url"), "visitors", "brooklyn", "br00k11n") +- type: org.apache.brooklyn.entity.database.mysql.MySqlNode + id: db + name: DB HelloWorld Visitors + brooklyn.config: + datastore.creation.script.url: https://github.com/apache/brooklyn-library/blob/master/examples/simple-web-cluster/src/main/resources/visitors-creation-script.sql http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/f38b9e7b/guide/blueprints/example_yaml/appserver-clustered-w-db.yaml ---------------------------------------------------------------------- diff --git a/guide/blueprints/example_yaml/appserver-clustered-w-db.yaml b/guide/blueprints/example_yaml/appserver-clustered-w-db.yaml new file mode 100644 index 0000000..a3fa749 --- /dev/null +++ b/guide/blueprints/example_yaml/appserver-clustered-w-db.yaml @@ -0,0 +1,19 @@ +name: appserver-clustered-w-db +services: +- type: org.apache.brooklyn.entity.webapp.ControlledDynamicWebAppCluster + brooklyn.config: + cluster.initial.size: 2 + dynamiccluster.memberspec: + $brooklyn:entitySpec: + type: org.apache.brooklyn.entity.webapp.jboss.JBoss7Server + brooklyn.config: + wars.root: http://search.maven.org/remotecontent?filepath=org/apache/brooklyn/example/brooklyn-example-hello-world-sql-webapp/0.8.0-incubating/brooklyn-example-hello-world-sql-webapp-0.8.0-incubating.war + http.port: 8080+ + java.sysprops: + brooklyn.example.db.url: $brooklyn:formatString("jdbc:%s%s?user=%s\\&password=%s", + component("db").attributeWhenReady("datastore.url"), "visitors", "brooklyn", "br00k11n") +- type: org.apache.brooklyn.entity.database.mysql.MySqlNode + id: db + name: DB HelloWorld Visitors + brooklyn.config: + datastore.creation.script.url: https://github.com/apache/brooklyn-library/raw/master/examples/simple-web-cluster/src/main/resources/visitors-creation-script.sql http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/f38b9e7b/guide/blueprints/example_yaml/appserver-configured-in-config.yaml ---------------------------------------------------------------------- diff --git a/guide/blueprints/example_yaml/appserver-configured-in-config.yaml b/guide/blueprints/example_yaml/appserver-configured-in-config.yaml new file mode 100644 index 0000000..765a8c2 --- /dev/null +++ b/guide/blueprints/example_yaml/appserver-configured-in-config.yaml @@ -0,0 +1,6 @@ +name: appserver-configured-in-config +services: +- type: org.apache.brooklyn.entity.webapp.jboss.JBoss7Server + brooklyn.config: + wars.root: http://search.maven.org/remotecontent?filepath=org/apache/brooklyn/example/brooklyn-example-hello-world-sql-webapp/0.8.0-incubating/brooklyn-example-hello-world-sql-webapp-0.8.0-incubating.war + http.port: 8080 http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/f38b9e7b/guide/blueprints/example_yaml/appserver-configured.yaml ---------------------------------------------------------------------- diff --git a/guide/blueprints/example_yaml/appserver-configured.yaml b/guide/blueprints/example_yaml/appserver-configured.yaml new file mode 100644 index 0000000..51bf3ca --- /dev/null +++ b/guide/blueprints/example_yaml/appserver-configured.yaml @@ -0,0 +1,5 @@ +name: appserver-configured +services: +- type: org.apache.brooklyn.entity.webapp.jboss.JBoss7Server + war: http://search.maven.org/remotecontent?filepath=org/apache/brooklyn/example/brooklyn-example-hello-world-sql-webapp/0.8.0-incubating/brooklyn-example-hello-world-sql-webapp-0.8.0-incubating.war + httpPort: 8080 http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/f38b9e7b/guide/blueprints/example_yaml/appserver-w-db-other-flavor.yaml ---------------------------------------------------------------------- diff --git a/guide/blueprints/example_yaml/appserver-w-db-other-flavor.yaml b/guide/blueprints/example_yaml/appserver-w-db-other-flavor.yaml new file mode 100644 index 0000000..9b648d8 --- /dev/null +++ b/guide/blueprints/example_yaml/appserver-w-db-other-flavor.yaml @@ -0,0 +1,17 @@ +name: appserver-w-db-other-flavor +services: +- type: org.apache.brooklyn.entity.webapp.tomcat.TomcatServer + name: AppServer HelloWorld + brooklyn.config: + wars.root: http://search.maven.org/remotecontent?filepath=org/apache/brooklyn/example/brooklyn-example-hello-world-sql-webapp/0.8.0-incubating/brooklyn-example-hello-world-sql-webapp-0.8.0-incubating.war + http.port: 8080+ + java.sysprops: + brooklyn.example.db.url: $brooklyn:formatString("jdbc:%s%s?user=%s\\&password=%s", + component("db").attributeWhenReady("datastore.url"), "visitors", "brooklyn", "br00k11n") +- type: org.apache.brooklyn.entity.database.mariadb.MariaDbNode + id: db + name: DB HelloWorld Visitors + brooklyn.config: + datastore.creation.script.url: https://github.com/apache/brooklyn-library/raw/master/examples/simple-web-cluster/src/main/resources/visitors-creation-script.sql + provisioning.properties: + minRam: 8192 http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/f38b9e7b/guide/blueprints/example_yaml/appserver-w-db.yaml ---------------------------------------------------------------------- diff --git a/guide/blueprints/example_yaml/appserver-w-db.yaml b/guide/blueprints/example_yaml/appserver-w-db.yaml new file mode 100644 index 0000000..d4bc706 --- /dev/null +++ b/guide/blueprints/example_yaml/appserver-w-db.yaml @@ -0,0 +1,15 @@ +name: appserver-w-db +services: +- type: org.apache.brooklyn.entity.webapp.jboss.JBoss7Server + name: AppServer HelloWorld + brooklyn.config: + wars.root: http://search.maven.org/remotecontent?filepath=org/apache/brooklyn/example/brooklyn-example-hello-world-sql-webapp/0.8.0-incubating/brooklyn-example-hello-world-sql-webapp-0.8.0-incubating.war + http.port: 8080+ + java.sysprops: + brooklyn.example.db.url: $brooklyn:formatString("jdbc:%s%s?user=%s\\&password=%s", + component("db").attributeWhenReady("datastore.url"), "visitors", "brooklyn", "br00k11n") +- type: org.apache.brooklyn.entity.database.mysql.MySqlNode + id: db + name: DB HelloWorld Visitors + brooklyn.config: + datastore.creation.script.url: https://github.com/apache/brooklyn-library/raw/master/examples/simple-web-cluster/src/main/resources/visitors-creation-script.sql http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/f38b9e7b/guide/blueprints/example_yaml/appserver-w-policy.yaml ---------------------------------------------------------------------- diff --git a/guide/blueprints/example_yaml/appserver-w-policy.yaml b/guide/blueprints/example_yaml/appserver-w-policy.yaml new file mode 100644 index 0000000..4b10f59 --- /dev/null +++ b/guide/blueprints/example_yaml/appserver-w-policy.yaml @@ -0,0 +1,27 @@ +name: appserver-w-policy +services: +- type: org.apache.brooklyn.entity.webapp.ControlledDynamicWebAppCluster + brooklyn.config: + cluster.initial.size: 1 + dynamiccluster.memberspec: + $brooklyn:entitySpec: + type: org.apache.brooklyn.entity.webapp.jboss.JBoss7Server + brooklyn.config: + wars.root: http://search.maven.org/remotecontent?filepath=org/apache/brooklyn/example/brooklyn-example-hello-world-sql-webapp/0.8.0-incubating/brooklyn-example-hello-world-sql-webapp-0.8.0-incubating.war + http.port: 8080+ + java.sysprops: + brooklyn.example.db.url: $brooklyn:formatString("jdbc:%s%s?user=%s\\&password=%s", + component("db").attributeWhenReady("datastore.url"), "visitors", "brooklyn", "br00k11n") + brooklyn.policies: + - type: org.apache.brooklyn.policy.autoscaling.AutoScalerPolicy + brooklyn.config: + metric: $brooklyn:sensor("brooklyn.entity.webapp.DynamicWebAppCluster", "webapp.reqs.perSec.windowed.perNode") + metricLowerBound: 10 + metricUpperBound: 100 + minPoolSize: 1 + maxPoolSize: 5 +- type: org.apache.brooklyn.entity.database.mysql.MySqlNode + id: db + name: DB HelloWorld Visitors + brooklyn.config: + datastore.creation.script.url: https://github.com/apache/brooklyn-library/raw/master/examples/simple-web-cluster/src/main/resources/visitors-creation-script.sql http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/f38b9e7b/guide/blueprints/example_yaml/cluster-vm.yaml ---------------------------------------------------------------------- diff --git a/guide/blueprints/example_yaml/cluster-vm.yaml b/guide/blueprints/example_yaml/cluster-vm.yaml new file mode 100644 index 0000000..e21977a --- /dev/null +++ b/guide/blueprints/example_yaml/cluster-vm.yaml @@ -0,0 +1,13 @@ +name: cluster-vm +services: +- type: org.apache.brooklyn.entity.group.DynamicCluster + brooklyn.config: + cluster.initial.size: 5 + dynamiccluster.memberspec: + $brooklyn:entitySpec: + type: org.apache.brooklyn.entity.software.base.EmptySoftwareProcess + name: VM + provisioning.properties: + minRam: 8g + minCores: 4 + minDisk: 100g http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/f38b9e7b/guide/blueprints/example_yaml/fabric-with-multiple-locations.yaml ---------------------------------------------------------------------- diff --git a/guide/blueprints/example_yaml/fabric-with-multiple-locations.yaml b/guide/blueprints/example_yaml/fabric-with-multiple-locations.yaml new file mode 100644 index 0000000..d923025 --- /dev/null +++ b/guide/blueprints/example_yaml/fabric-with-multiple-locations.yaml @@ -0,0 +1,15 @@ +name: fabric-of-app-server-clusters +locations: +- aws-ec2:us-east-1 +- aws-ec2:us-west-1 +services: +- type: org.apache.brooklyn.entity.group.DynamicFabric + brooklyn.config: + dynamiccluster.memberspec: + $brooklyn:entitySpec: + type: org.apache.brooklyn.entity.group.DynamicCluster + brooklyn.config: + cluster.initial.size: 3 + dynamiccluster.memberspec: + $brooklyn:entitySpec: + type: org.apache.brooklyn.entity.webapp.tomcat.Tomcat8Server http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/f38b9e7b/guide/blueprints/example_yaml/simple-appserver-with-location-byon.yaml ---------------------------------------------------------------------- diff --git a/guide/blueprints/example_yaml/simple-appserver-with-location-byon.yaml b/guide/blueprints/example_yaml/simple-appserver-with-location-byon.yaml new file mode 100644 index 0000000..7e4c0ca --- /dev/null +++ b/guide/blueprints/example_yaml/simple-appserver-with-location-byon.yaml @@ -0,0 +1,10 @@ +name: simple-appserver-with-location-byon +location: + byon: + user: brooklyn + privateKeyFile: ~/.ssh/brooklyn.pem + hosts: + - 192.168.0.18 + - 192.168.0.19 +services: +- type: org.apache.brooklyn.entity.webapp.tomcat.Tomcat8Server http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/f38b9e7b/guide/blueprints/example_yaml/simple-appserver-with-location-per-entity.yaml ---------------------------------------------------------------------- diff --git a/guide/blueprints/example_yaml/simple-appserver-with-location-per-entity.yaml b/guide/blueprints/example_yaml/simple-appserver-with-location-per-entity.yaml new file mode 100644 index 0000000..a39e27d --- /dev/null +++ b/guide/blueprints/example_yaml/simple-appserver-with-location-per-entity.yaml @@ -0,0 +1,8 @@ +name: simple-appserver-with-location-per-entity +services: +- type: org.apache.brooklyn.entity.webapp.tomcat.Tomcat8Server + location: + byon(hosts="192.168.0.18",user="brooklyn",privateKeyFile="~/.ssh/brooklyn.pem") +- type: org.apache.brooklyn.entity.webapp.jboss.JBoss7Server + location: + byon(hosts="192.168.0.19",user="brooklyn",privateKeyFile="~/.ssh/brooklyn.pem") http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/f38b9e7b/guide/blueprints/example_yaml/simple-appserver-with-location.yaml ---------------------------------------------------------------------- diff --git a/guide/blueprints/example_yaml/simple-appserver-with-location.yaml b/guide/blueprints/example_yaml/simple-appserver-with-location.yaml new file mode 100644 index 0000000..764eaac --- /dev/null +++ b/guide/blueprints/example_yaml/simple-appserver-with-location.yaml @@ -0,0 +1,8 @@ +name: simple-appserver-with-location +location: + jclouds:aws-ec2: + region: us-east-1 + identity: AKA_YOUR_ACCESS_KEY_ID + credential: <access-key-hex-digits> +services: +- type: org.apache.brooklyn.entity.webapp.tomcat.Tomcat8Server http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/f38b9e7b/guide/blueprints/example_yaml/simple-appserver.yaml ---------------------------------------------------------------------- diff --git a/guide/blueprints/example_yaml/simple-appserver.yaml b/guide/blueprints/example_yaml/simple-appserver.yaml new file mode 100644 index 0000000..8e9d76a --- /dev/null +++ b/guide/blueprints/example_yaml/simple-appserver.yaml @@ -0,0 +1,4 @@ +name: simple-appserver +location: localhost +services: +- type: org.apache.brooklyn.entity.webapp.jboss.JBoss7Server http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/f38b9e7b/guide/blueprints/example_yaml/simple-vm.yaml ---------------------------------------------------------------------- diff --git a/guide/blueprints/example_yaml/simple-vm.yaml b/guide/blueprints/example_yaml/simple-vm.yaml new file mode 100644 index 0000000..8f6447c --- /dev/null +++ b/guide/blueprints/example_yaml/simple-vm.yaml @@ -0,0 +1,8 @@ +name: simple-vm +services: +- type: org.apache.brooklyn.entity.software.base.EmptySoftwareProcess + name: VM + provisioning.properties: + minRam: 8192mb + minCores: 4 + minDisk: 100gb http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/f38b9e7b/guide/blueprints/example_yaml/test-app-with-enrichers-slightly-simpler.yaml ---------------------------------------------------------------------- diff --git a/guide/blueprints/example_yaml/test-app-with-enrichers-slightly-simpler.yaml b/guide/blueprints/example_yaml/test-app-with-enrichers-slightly-simpler.yaml new file mode 100644 index 0000000..93b6795 --- /dev/null +++ b/guide/blueprints/example_yaml/test-app-with-enrichers-slightly-simpler.yaml @@ -0,0 +1,58 @@ +# +# example showing how enrichers can be set +# +name: test-app-with-enrichers +description: Testing many enrichers +services: +- type: org.apache.brooklyn.entity.group.DynamicCluster + id: cluster + location: localhost + brooklyn.config: + cluster.initial.size: 3 + dynamiccluster.memberspec: + $brooklyn:entitySpec: + type: org.apache.brooklyn.core.test.entity.TestEntity + brooklyn.enrichers: + - type: org.apache.brooklyn.enricher.stock.Transformer + # transform "ip" (which we expect a feed, not shown here, to set) to a URL; + # you can curl an address string to the sensors/ip endpoint an entity to trigger these enrichers + brooklyn.config: + enricher.sourceSensor: $brooklyn:sensor("ip") + enricher.targetSensor: $brooklyn:sensor("url") + enricher.targetValue: $brooklyn:formatString("http://%s/";, $brooklyn:attributeWhenReady("ip")) + - type: org.apache.brooklyn.enricher.stock.Propagator + # 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 + brooklyn.config: + sensorMapping: + $brooklyn:sensor("url"): $brooklyn:sensor("org.apache.brooklyn.core.entity.Attributes", "main.uri") + brooklyn.enrichers: + - type: org.apache.brooklyn.enricher.stock.Aggregator + # aggregate `url` sensors from children into a list + brooklyn.config: + enricher.sourceSensor: $brooklyn:sensor("url") + enricher.targetSensor: $brooklyn:sensor("urls.list") + enricher.aggregating.fromMembers: true + - type: org.apache.brooklyn.enricher.stock.Joiner + # create a string from that list, for use e.g. in bash scripts + brooklyn.config: + enricher.sourceSensor: $brooklyn:sensor("urls.list") + enricher.targetSensor: $brooklyn:sensor("urls.list.comma_separated.max_2") + maximum: 2 + # TODO infer uniqueTag, name etc + uniqueTag: urls.list.comma_separated.max_2 + - type: org.apache.brooklyn.enricher.stock.Joiner + # pick one uri as the main one to use + brooklyn.config: + enricher.sourceSensor: $brooklyn:sensor("urls.list") + enricher.targetSensor: $brooklyn:sensor("org.apache.brooklyn.core.entity.Attributes", "main.uri") + quote: false + maximum: 1 +brooklyn.enrichers: +- type: org.apache.brooklyn.enricher.stock.Propagator + # if nothing specified for `propagating` or `sensorMapping` then + # Propagator will do all but the usual lifecycle defaults, handy at the root! + brooklyn.config: + producer: $brooklyn:entity("cluster") http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/f38b9e7b/guide/blueprints/example_yaml/vanilla-bash-netcat-catalog.bom ---------------------------------------------------------------------- diff --git a/guide/blueprints/example_yaml/vanilla-bash-netcat-catalog.bom b/guide/blueprints/example_yaml/vanilla-bash-netcat-catalog.bom new file mode 100644 index 0000000..6416ab7 --- /dev/null +++ b/guide/blueprints/example_yaml/vanilla-bash-netcat-catalog.bom @@ -0,0 +1,36 @@ +brooklyn.catalog: + id: netcat-example + version: "1.0" + itemType: entity + item: + type: org.apache.brooklyn.entity.software.base.VanillaSoftwareProcess + name: Simple Netcat Server + + launch.command: | + echo $MESSAGE | nc -l $NETCAT_PORT & + echo $! > $PID_FILE + + env: + MESSAGE: $brooklyn:config("message") + NETCAT_PORT: $brooklyn:attributeWhenReady("netcat.port") + + brooklyn.parameters: + - name: message + description: a message to send to the caller + default: hello + - name: netcat.port + type: port + description: the port netcat should run on + default: 4321+ + + brooklyn.enrichers: + - type: org.apache.brooklyn.enricher.stock.Transformer + brooklyn.config: + uniqueTag: main-uri-generator + enricher.sourceSensor: $brooklyn:sensor("host.address") + enricher.targetSensor: $brooklyn:sensor("main.uri") + enricher.targetValue: + $brooklyn:formatString: + - "http://%s:%s/"; + - $brooklyn:attributeWhenReady("host.address") + - $brooklyn:attributeWhenReady("netcat.port") http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/f38b9e7b/guide/blueprints/example_yaml/vanilla-bash-netcat-cluster.yaml ---------------------------------------------------------------------- diff --git a/guide/blueprints/example_yaml/vanilla-bash-netcat-cluster.yaml b/guide/blueprints/example_yaml/vanilla-bash-netcat-cluster.yaml new file mode 100644 index 0000000..813445f --- /dev/null +++ b/guide/blueprints/example_yaml/vanilla-bash-netcat-cluster.yaml @@ -0,0 +1,12 @@ +name: Netcat Cluster Example +location: localhost +services: +- type: org.apache.brooklyn.entity.group.DynamicCluster + brooklyn.config: + dynamiccluster.memberspec: + $brooklyn:entitySpec: + type: netcat-example + message: hello from cluster member + netcat.port: 8000+ + cluster.initial.size: 3 + restartMode: parallel http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/f38b9e7b/guide/blueprints/example_yaml/vanilla-bash-netcat-env.yaml ---------------------------------------------------------------------- diff --git a/guide/blueprints/example_yaml/vanilla-bash-netcat-env.yaml b/guide/blueprints/example_yaml/vanilla-bash-netcat-env.yaml new file mode 100644 index 0000000..061d31b --- /dev/null +++ b/guide/blueprints/example_yaml/vanilla-bash-netcat-env.yaml @@ -0,0 +1,12 @@ +name: Netcat Example with Environment Vars +location: localhost +services: +- type: org.apache.brooklyn.entity.software.base.VanillaSoftwareProcess + name: Simple Netcat Server + launch.command: | + echo $MESSAGE | nc -l $NETCAT_PORT & + echo $! > $PID_FILE + + env: + MESSAGE: hello + NETCAT_PORT: 4321 http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/f38b9e7b/guide/blueprints/example_yaml/vanilla-bash-netcat-file.yaml ---------------------------------------------------------------------- diff --git a/guide/blueprints/example_yaml/vanilla-bash-netcat-file.yaml b/guide/blueprints/example_yaml/vanilla-bash-netcat-file.yaml new file mode 100644 index 0000000..d768739 --- /dev/null +++ b/guide/blueprints/example_yaml/vanilla-bash-netcat-file.yaml @@ -0,0 +1,6 @@ +name: Simple Netcat Example From File +location: localhost +services: +- type: org.apache.brooklyn.entity.software.base.VanillaSoftwareProcess + name: Simple Netcat Server + download.url: file:///tmp/netcat-server.tgz http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/f38b9e7b/guide/blueprints/example_yaml/vanilla-bash-netcat-more-commands.yaml ---------------------------------------------------------------------- diff --git a/guide/blueprints/example_yaml/vanilla-bash-netcat-more-commands.yaml b/guide/blueprints/example_yaml/vanilla-bash-netcat-more-commands.yaml new file mode 100644 index 0000000..f4e894f --- /dev/null +++ b/guide/blueprints/example_yaml/vanilla-bash-netcat-more-commands.yaml @@ -0,0 +1,16 @@ +name: Netcat Example with Explicit Check and Stop Commands +location: localhost +services: +- type: org.apache.brooklyn.entity.software.base.VanillaSoftwareProcess + name: Simple Netcat Server + launch.command: | + echo hello | nc -l 4321 & + echo $! > $PID_FILE + + # The following overrides demonstrate the use of a custom shell environment as well as + # check-running and stop commands. These are optional; default behavior will "do the + # right thing" with the pid file automatically. + + env: { CHECK_MARKER: "checkRunning", STOP_MARKER: "stop" } + checkRunning.command: echo $CHECK_MARKER >> DATE && test -f "$PID_FILE" && ps -p `cat $PID_FILE` >/dev/null + stop.command: echo $STOP_MARKER >> DATE && test -f "$PID_FILE" && { kill -9 `cat $PID_FILE`; rm /tmp/vanilla.pid; } http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/f38b9e7b/guide/blueprints/example_yaml/vanilla-bash-netcat-port-parameter.yaml ---------------------------------------------------------------------- diff --git a/guide/blueprints/example_yaml/vanilla-bash-netcat-port-parameter.yaml b/guide/blueprints/example_yaml/vanilla-bash-netcat-port-parameter.yaml new file mode 100644 index 0000000..90f83b4 --- /dev/null +++ b/guide/blueprints/example_yaml/vanilla-bash-netcat-port-parameter.yaml @@ -0,0 +1,21 @@ +name: Netcat Example with Parameter +location: localhost +services: +- type: org.apache.brooklyn.entity.software.base.VanillaSoftwareProcess + name: Simple Netcat Server + launch.command: | + echo $MESSAGE | nc -l $NETCAT_PORT & + echo $! > $PID_FILE + + env: + MESSAGE: $brooklyn:config("message") + NETCAT_PORT: $brooklyn:attributeWhenReady("netcat.port") + + brooklyn.parameters: + - name: message + description: a message to send to the caller + default: hello + - name: netcat.port + type: port + description: the port netcat should run on + default: 4321+ http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/f38b9e7b/guide/blueprints/example_yaml/vanilla-bash-netcat-port.yaml ---------------------------------------------------------------------- diff --git a/guide/blueprints/example_yaml/vanilla-bash-netcat-port.yaml b/guide/blueprints/example_yaml/vanilla-bash-netcat-port.yaml new file mode 100644 index 0000000..3ec0212 --- /dev/null +++ b/guide/blueprints/example_yaml/vanilla-bash-netcat-port.yaml @@ -0,0 +1,13 @@ +name: Netcat Example with Port Opened +location: localhost +services: +- type: org.apache.brooklyn.entity.software.base.VanillaSoftwareProcess + name: Simple Netcat Server + launch.command: | + echo hello | nc -l 4321 & + echo $! > $PID_FILE + + brooklyn.config: + # matching the regex `.*\.port` will cause the port to be opened + # if in a cloud where configurable security groups are available + netcat.port: 4321 http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/f38b9e7b/guide/blueprints/example_yaml/vanilla-bash-netcat-reference.yaml ---------------------------------------------------------------------- diff --git a/guide/blueprints/example_yaml/vanilla-bash-netcat-reference.yaml b/guide/blueprints/example_yaml/vanilla-bash-netcat-reference.yaml new file mode 100644 index 0000000..0f10c55 --- /dev/null +++ b/guide/blueprints/example_yaml/vanilla-bash-netcat-reference.yaml @@ -0,0 +1,5 @@ +name: Netcat Type Reference Example +location: localhost +services: +- type: netcat-example + message: hello from netcat using a registered type http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/f38b9e7b/guide/blueprints/example_yaml/vanilla-bash-netcat-restarter.yaml ---------------------------------------------------------------------- diff --git a/guide/blueprints/example_yaml/vanilla-bash-netcat-restarter.yaml b/guide/blueprints/example_yaml/vanilla-bash-netcat-restarter.yaml new file mode 100644 index 0000000..47e54ab --- /dev/null +++ b/guide/blueprints/example_yaml/vanilla-bash-netcat-restarter.yaml @@ -0,0 +1,20 @@ +name: Netcat Example with Restarter Policy +location: localhost +services: +- type: org.apache.brooklyn.entity.software.base.VanillaSoftwareProcess + id: netcat-server + name: Simple Netcat Server + launch.command: | + echo hello | nc -l 4321 & + echo $! > $PID_FILE + brooklyn.enrichers: + - type: org.apache.brooklyn.policy.ha.ServiceFailureDetector + brooklyn.config: + # wait 15s after service fails before propagating failure + serviceFailedStabilizationDelay: 15s + brooklyn.policies: + - type: org.apache.brooklyn.policy.ha.ServiceRestarter + brooklyn.config: + # repeated failures in a time window can cause the restarter to abort, + # propagating the failure; a time window of 0 will mean it always restarts! + failOnRecurringFailuresInThisDuration: 0
