Return-Path: X-Original-To: apmail-brooklyn-commits-archive@minotaur.apache.org Delivered-To: apmail-brooklyn-commits-archive@minotaur.apache.org Received: from mail.apache.org (hermes.apache.org [140.211.11.3]) by minotaur.apache.org (Postfix) with SMTP id D5CD5CD3A for ; Fri, 9 Jan 2015 15:35:08 +0000 (UTC) Received: (qmail 94965 invoked by uid 500); 9 Jan 2015 15:35:10 -0000 Delivered-To: apmail-brooklyn-commits-archive@brooklyn.apache.org Received: (qmail 94943 invoked by uid 500); 9 Jan 2015 15:35:10 -0000 Mailing-List: contact commits-help@brooklyn.incubator.apache.org; run by ezmlm Precedence: bulk List-Help: List-Unsubscribe: List-Post: List-Id: Reply-To: dev@brooklyn.incubator.apache.org Delivered-To: mailing list commits@brooklyn.incubator.apache.org Received: (qmail 94934 invoked by uid 99); 9 Jan 2015 15:35:10 -0000 Received: from athena.apache.org (HELO athena.apache.org) (140.211.11.136) by apache.org (qpsmtpd/0.29) with ESMTP; Fri, 09 Jan 2015 15:35:10 +0000 X-ASF-Spam-Status: No, hits=-2000.0 required=5.0 tests=ALL_TRUSTED,T_RP_MATCHES_RCVD X-Spam-Check-By: apache.org Received: from [140.211.11.3] (HELO mail.apache.org) (140.211.11.3) by apache.org (qpsmtpd/0.29) with SMTP; Fri, 09 Jan 2015 15:34:56 +0000 Received: (qmail 92645 invoked by uid 99); 9 Jan 2015 15:34:31 -0000 Received: from tyr.zones.apache.org (HELO tyr.zones.apache.org) (140.211.11.114) by apache.org (qpsmtpd/0.29) with ESMTP; Fri, 09 Jan 2015 15:34:31 +0000 Received: by tyr.zones.apache.org (Postfix, from userid 65534) id 41DC58162E7; Fri, 9 Jan 2015 15:34:31 +0000 (UTC) Content-Type: text/plain; charset="us-ascii" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit From: heneveld@apache.org To: commits@brooklyn.incubator.apache.org Date: Fri, 09 Jan 2015 15:35:08 -0000 Message-Id: <6d6a300fced04aec97aefb90c2306e84@git.apache.org> In-Reply-To: References: X-Mailer: ASF-Git Admin Mailer Subject: [39/44] incubator-brooklyn git commit: Changes as per review X-Virus-Checked: Checked by ClamAV on apache.org Changes as per review Project: http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/repo Commit: http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/commit/4e54debc Tree: http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/tree/4e54debc Diff: http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/diff/4e54debc Branch: refs/heads/master Commit: 4e54debce74d416f6f8c62211c9da3cec7aca708 Parents: cdebdf3 Author: Robert Moss Authored: Fri Jan 9 15:15:01 2015 +0000 Committer: Robert Moss Committed: Fri Jan 9 15:19:29 2015 +0000 ---------------------------------------------------------------------- docs/guide/chef/about-chef.md | 50 --------- docs/guide/chef/advanced-chef-integration.md | 48 --------- docs/guide/chef/chef-call-flow.png | Bin 36222 -> 0 bytes docs/guide/chef/creating-blueprints.md | 105 ------------------- docs/guide/chef/example_yaml/mysql-chef-1.yaml | 24 ----- docs/guide/chef/example_yaml/mysql-chef-2.yaml | 28 ----- docs/guide/chef/index.md | 18 ---- docs/guide/chef/writing-chef.md | 79 -------------- docs/guide/index.md | 1 - docs/guide/ops/persistence/index.md | 13 --- docs/guide/ops/webconsole/index.md | 9 +- docs/guide/start/managing.md | 2 +- docs/guide/yaml/bigger-blueprint.md | 43 -------- docs/guide/yaml/chef/about-chef.md | 50 +++++++++ .../yaml/chef/advanced-chef-integration.md | 48 +++++++++ docs/guide/yaml/chef/chef-call-flow.png | Bin 0 -> 36222 bytes docs/guide/yaml/chef/creating-blueprints.md | 105 +++++++++++++++++++ .../yaml/chef/example_yaml/mysql-chef-1.yaml | 24 +++++ .../yaml/chef/example_yaml/mysql-chef-2.yaml | 28 +++++ docs/guide/yaml/chef/index.md | 18 ++++ docs/guide/yaml/chef/writing-chef.md | 79 ++++++++++++++ docs/guide/yaml/index.md | 2 +- docs/guide/yaml/mutlitple-services.md | 36 +++++++ docs/website/index.md | 2 +- 24 files changed, 393 insertions(+), 419 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/4e54debc/docs/guide/chef/about-chef.md ---------------------------------------------------------------------- diff --git a/docs/guide/chef/about-chef.md b/docs/guide/chef/about-chef.md deleted file mode 100644 index 66207bc..0000000 --- a/docs/guide/chef/about-chef.md +++ /dev/null @@ -1,50 +0,0 @@ ---- -title: About Chef -title_in_menu: About Chef -layout: guide-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 AMP Server and the Chef Server. - -[![Chef Flow Diagram](chef-call-flow.png "Chef Flow Diagram" )](Chef.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 AMP 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/incubator-brooklyn/blob/4e54debc/docs/guide/chef/advanced-chef-integration.md ---------------------------------------------------------------------- diff --git a/docs/guide/chef/advanced-chef-integration.md b/docs/guide/chef/advanced-chef-integration.md deleted file mode 100644 index 9a7cc67..0000000 --- a/docs/guide/chef/advanced-chef-integration.md +++ /dev/null @@ -1,48 +0,0 @@ ---- -title: Advanced Chef Integration -title_in_menu: Advanced Chef Integration -layout: guide-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: - -``` -- type: chef:cookbook_name - cookbook_urls: - cookbook_name: url://for/cookbook.tgz - dependency1: url://for/dependency1.tgz - launch_run_list: [ "cookbook_name::start" ] - launch_attributes: # map of arguments to set in the chef node - service_name: cookbook_service - pid_file: /var/run/cookbook.pid -``` - -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/incubator-brooklyn/blob/4e54debc/docs/guide/chef/chef-call-flow.png ---------------------------------------------------------------------- diff --git a/docs/guide/chef/chef-call-flow.png b/docs/guide/chef/chef-call-flow.png deleted file mode 100644 index d899de2..0000000 Binary files a/docs/guide/chef/chef-call-flow.png and /dev/null differ http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/4e54debc/docs/guide/chef/creating-blueprints.md ---------------------------------------------------------------------- diff --git a/docs/guide/chef/creating-blueprints.md b/docs/guide/chef/creating-blueprints.md deleted file mode 100644 index 4baa553..0000000 --- a/docs/guide/chef/creating-blueprints.md +++ /dev/null @@ -1,105 +0,0 @@ ---- -title: Creating Blueprints from Chef -title_in_menu: Creating Blueprints from Chef -layout: guide-normal ---- - -## Creating Blueprints from Chef - -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.)* - -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 (`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/incubator-brooklyn/blob/4e54debc/docs/guide/chef/example_yaml/mysql-chef-1.yaml ---------------------------------------------------------------------- diff --git a/docs/guide/chef/example_yaml/mysql-chef-1.yaml b/docs/guide/chef/example_yaml/mysql-chef-1.yaml deleted file mode 100644 index bdac530..0000000 --- a/docs/guide/chef/example_yaml/mysql-chef-1.yaml +++ /dev/null @@ -1,24 +0,0 @@ -name: chef-mysql-sample -services: -- type: chef:mysql - - cookbook_urls: - # only needed for chef solo; URL can be local to brooklyn, or github, etc... - mysql: https://github.com/opscode-cookbooks/mysql/archive/v4.0.12.tar.gz - openssl: https://github.com/opscode-cookbooks/openssl/archive/v1.1.0.tar.gz - build-essential: https://github.com/opscode-cookbooks/build-essential/archive/v1.4.4.tar.gz - - launch_run_list: [ "mysql::server" ] - launch_attributes: - mysql: - # these attrs are required by the mysql cookbook under node['mysql'] - server_root_password: p4ssw0rd - server_repl_password: p4ssw0rd - server_debian_password: p4ssw0rd - # many others are attrs are supported by the cookbook and can be passed here... - - # how to determine if the process is running and how to kill it - # (supported options are `service_name` and `pid_file`; normally you should just pick one. - # here we use the pid_file because the service_name varies, mysql on centos, mysqld on ubuntu!) - #service_name: mysqld - pid_file: /var/run/mysqld/mysqld.pid http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/4e54debc/docs/guide/chef/example_yaml/mysql-chef-2.yaml ---------------------------------------------------------------------- diff --git a/docs/guide/chef/example_yaml/mysql-chef-2.yaml b/docs/guide/chef/example_yaml/mysql-chef-2.yaml deleted file mode 100644 index ced2dbe..0000000 --- a/docs/guide/chef/example_yaml/mysql-chef-2.yaml +++ /dev/null @@ -1,28 +0,0 @@ -name: chef-mysql-sample -services: -- type: chef:mysql - id: db - - cookbook_urls: - # only needed for chef solo; URL can be local to brooklyn, or github, etc... - mysql: https://github.com/opscode-cookbooks/mysql/archive/v4.0.12.tar.gz - openssl: https://github.com/opscode-cookbooks/openssl/archive/v1.1.0.tar.gz - build-essential: https://github.com/opscode-cookbooks/build-essential/archive/v1.4.4.tar.gz - - launch_run_list: [ "mysql::server" ] - launch_attributes: - mysql: - # these attrs are required by the mysql cookbook under node['mysql'] - server_root_password: $brooklyn:component("db").config("mysql.password") - server_repl_password: $brooklyn:component("db").config("mysql.password") - server_debian_password: $brooklyn:component("db").config("mysql.password") - # many others are attrs are supported by the cookbook and can be passed here... - - # how to determine if the process is running and how to kill it - # (supported options are `service_name` and `pid_file`; normally you should just pick one. - # here we use the pid_file because the service_name varies, mysql on centos, mysqld on ubuntu!) - #service_name: mysqld - pid_file: /var/run/mysqld/mysqld.pid - -brooklyn.config: - mysql.password: p4ssw0rd http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/4e54debc/docs/guide/chef/index.md ---------------------------------------------------------------------- diff --git a/docs/guide/chef/index.md b/docs/guide/chef/index.md deleted file mode 100644 index 2f47aa3..0000000 --- a/docs/guide/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](creating-yaml.html). - -{% include list-children.html %} http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/4e54debc/docs/guide/chef/writing-chef.md ---------------------------------------------------------------------- diff --git a/docs/guide/chef/writing-chef.md b/docs/guide/chef/writing-chef.md deleted file mode 100644 index 3fa9401..0000000 --- a/docs/guide/chef/writing-chef.md +++ /dev/null @@ -1,79 +0,0 @@ ---- -title: Writing Chef for Blueprints -title_in_menu: Writing Chef for Blueprints -layout: guide-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:component('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/incubator-brooklyn/blob/4e54debc/docs/guide/index.md ---------------------------------------------------------------------- diff --git a/docs/guide/index.md b/docs/guide/index.md index 637a68a..2e2dadf 100644 --- a/docs/guide/index.md +++ b/docs/guide/index.md @@ -8,7 +8,6 @@ children: - { path: /guide/start/index.md } - { path: /guide/concepts/index.md } - { path: /guide/yaml/index.md } -- { path: /guide/chef/index.md } - { path: /guide/java/index.md } - { path: /guide/ops/index.md } - { path: /guide/misc/index.md } http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/4e54debc/docs/guide/ops/persistence/index.md ---------------------------------------------------------------------- diff --git a/docs/guide/ops/persistence/index.md b/docs/guide/ops/persistence/index.md index 98737c9..be19606 100644 --- a/docs/guide/ops/persistence/index.md +++ b/docs/guide/ops/persistence/index.md @@ -3,14 +3,12 @@ title: Persistence layout: guide-normal --- - Brooklyn can be configured to persist its state so that the Brooklyn server can be restarted, or so that a high availability standby server can take over. Brooklyn can persist its state to one of two places: the file system, or to an Object Store of your choice. - Command Line Options -------------------- @@ -39,7 +37,6 @@ the following config keys: * `brooklyn.persistence.location.spec` - File-based Persistence ---------------------- @@ -65,7 +62,6 @@ entity's: id; display name; type; config; attributes; tags; relationships to loc entities, group membership, policies and enrichers; and dynamically added effectors and sensors. - Object Store Persistence ------------------------ @@ -96,7 +92,6 @@ brooklyn launch --persist auto --persistenceDir myContainerName --persistenceLoc {% endhighlight %} - Rebind ------ @@ -109,7 +104,6 @@ HTTP or JMX). This new state will be reported in the web-console and can also tr any registered policies. - Copying Persistence State ------------------------- @@ -128,19 +122,16 @@ The `copy-state` CLI command takes the following arguments: The local transformations file to be applied to the copy of the data before uploading it. - Handling Rebind Failures ------------------------ If rebind were to fail for any reason, details of the underlying failures will be reported in the brooklyn.debug.log. There are several approaches to resolving problems. - ### Determine Underlying Cause The problems reported in brooklyn.debug.log will indicate where the problem lies - which entities, locations or policies, and in what way it failed. - ### Ignore Errors The `~/.brooklyn/brooklyn.properties` has several configuration options: @@ -174,7 +165,6 @@ The meaning of the configuration options is: * `rebind.failureMode.rebind`: any errors on rebind not covered by the more specific error cases described above. - ### Seek Help Help can be found at `dev@brooklyn.incubator.apache.org`, where folk will be able to investigate @@ -184,7 +174,6 @@ By sharing the persisted state (with credentials removed), Brooklyn developers w reproduce and debug the problem. - ### Fix-up the State The state of each entity, location, policy and enricher is persisted in XML. @@ -206,7 +195,6 @@ instance. After fixing the entities, locations and/or policies, the Brooklyn ins new persisted state can be copied and used to fix the production instance. - High Availability ----------------- @@ -252,7 +240,6 @@ For example, the following cURL command could be used to change the state of a ` curl -v -X POST -d mode=HOT_STANDBY -H "Brooklyn-Allow-Non-Master-Access: true" http://localhost:8082/v1/server/ha/state - Writing Persistable Code ------------------------ The most common problem on rebind is that custom entity code has not been written in a way http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/4e54debc/docs/guide/ops/webconsole/index.md ---------------------------------------------------------------------- diff --git a/docs/guide/ops/webconsole/index.md b/docs/guide/ops/webconsole/index.md index de28aa2..9764ae9 100644 --- a/docs/guide/ops/webconsole/index.md +++ b/docs/guide/ops/webconsole/index.md @@ -2,7 +2,7 @@ title: Runtime Management layout: guide-normal --- - + brooklyn uses many of the ideas from autonomic computing to implement management of entities in a structured and reusable fashion (including provisioning, healing, and optimising). @@ -21,7 +21,6 @@ This chapter describes these high-level runtime concepts, then proceeds to prese detailed information on the underlying implementation of management within brooklyn. - Startup Configuration --------------------- @@ -47,7 +46,6 @@ is supported and recommended. - Command Line Interface ---------------------- @@ -100,7 +98,6 @@ You can add things to the brooklyn classpath in a number of ways: * Use the ``BROOKLYN_CLASSPATH`` environment variable. If set, this is prepended to the brooklyn classpath. - Management Web Console ---------------------- @@ -230,7 +227,6 @@ brooklyn.webconsole.security.keystore.certificate.alias=brooklyn In order to access the Brooklyn console, you will also need to enable security, and setup a user as described above - Other Ways to Observe Activity ------------------------------ @@ -287,7 +283,6 @@ TODO --> - Key APIs -------- - + Sensors and Effectors --------------------- http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/4e54debc/docs/guide/start/managing.md ---------------------------------------------------------------------- diff --git a/docs/guide/start/managing.md b/docs/guide/start/managing.md index 5c91ded..44645f7 100644 --- a/docs/guide/start/managing.md +++ b/docs/guide/start/managing.md @@ -37,4 +37,4 @@ To stop an application, select the application in the tree view (the top/root en ### Next -Brooklyn's real power is in using Policies to automatically *manage* applications. +Brooklyn's real power is in using [Policies](policies.html) to automatically *manage* applications. http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/4e54debc/docs/guide/yaml/bigger-blueprint.md ---------------------------------------------------------------------- diff --git a/docs/guide/yaml/bigger-blueprint.md b/docs/guide/yaml/bigger-blueprint.md deleted file mode 100644 index 1037063..0000000 --- a/docs/guide/yaml/bigger-blueprint.md +++ /dev/null @@ -1,43 +0,0 @@ ---- -title: A Bigger Blueprint -layout: guide-normal -toc: ../guide_toc.json -categories: [use, guide, defining-applications] ---- - -We've seen the configuration of machines and how to build up clusters. -Now let's return to our app-server example and explore how more interesting -services can be configured, composed, and combined. - -Also note there are some good overview materials [here]({{site.path.guide}}//use/guide/defining-applications/basic-concepts.html) -covering clusters, sensors, effectors and more, -if you're the kind of person who likes to learn more about concepts before seeing them in action. - - -### Service Configuration - -We'll begin by using more key-value pairs to configure the JBoss server to run a real app: - -{% highlight yaml %} -{% readj example_yaml/appserver-configured.yaml %} -{% endhighlight %} - -(As before, you'll need to add the `location` info; `localhost` will work for these and subsequent examples.) - -When this is deployed, you can see management information in the Brooklyn Web Console, -including a link to the deployed application (downloaded to the target machine from the `hello-world` URL), -running on port 8080. - -**Top tip**: If port 8080 might be in use, you can specify `8080+` to take the first available port >= 8080; -the actual port will be reported as a sensor by Brooklyn. - -It's also worth indicating an alternate, more formal syntax. -Not all configuration on entities is supported at the top level of the service specification -(only those which are defined as "flags" in the underlying blueprint, -e.g. the `@SetFromFlag("war")` in the `WebAppServiceConstants` parent of `JBoss7Server`). -All configuration has a formal qualified name, and this can be supplied even where flags or config keys are not -explicitly defined, by placing it into a `brooklyn.config` section: - -{% highlight yaml %} -{% readj example_yaml/appserver-configured-in-config.yaml %} -{% endhighlight %} http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/4e54debc/docs/guide/yaml/chef/about-chef.md ---------------------------------------------------------------------- diff --git a/docs/guide/yaml/chef/about-chef.md b/docs/guide/yaml/chef/about-chef.md new file mode 100644 index 0000000..66207bc --- /dev/null +++ b/docs/guide/yaml/chef/about-chef.md @@ -0,0 +1,50 @@ +--- +title: About Chef +title_in_menu: About Chef +layout: guide-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 AMP Server and the Chef Server. + +[![Chef Flow Diagram](chef-call-flow.png "Chef Flow Diagram" )](Chef.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 AMP 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/incubator-brooklyn/blob/4e54debc/docs/guide/yaml/chef/advanced-chef-integration.md ---------------------------------------------------------------------- diff --git a/docs/guide/yaml/chef/advanced-chef-integration.md b/docs/guide/yaml/chef/advanced-chef-integration.md new file mode 100644 index 0000000..9a7cc67 --- /dev/null +++ b/docs/guide/yaml/chef/advanced-chef-integration.md @@ -0,0 +1,48 @@ +--- +title: Advanced Chef Integration +title_in_menu: Advanced Chef Integration +layout: guide-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: + +``` +- type: chef:cookbook_name + cookbook_urls: + cookbook_name: url://for/cookbook.tgz + dependency1: url://for/dependency1.tgz + launch_run_list: [ "cookbook_name::start" ] + launch_attributes: # map of arguments to set in the chef node + service_name: cookbook_service + pid_file: /var/run/cookbook.pid +``` + +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/incubator-brooklyn/blob/4e54debc/docs/guide/yaml/chef/chef-call-flow.png ---------------------------------------------------------------------- diff --git a/docs/guide/yaml/chef/chef-call-flow.png b/docs/guide/yaml/chef/chef-call-flow.png new file mode 100644 index 0000000..d899de2 Binary files /dev/null and b/docs/guide/yaml/chef/chef-call-flow.png differ http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/4e54debc/docs/guide/yaml/chef/creating-blueprints.md ---------------------------------------------------------------------- diff --git a/docs/guide/yaml/chef/creating-blueprints.md b/docs/guide/yaml/chef/creating-blueprints.md new file mode 100644 index 0000000..4baa553 --- /dev/null +++ b/docs/guide/yaml/chef/creating-blueprints.md @@ -0,0 +1,105 @@ +--- +title: Creating Blueprints from Chef +title_in_menu: Creating Blueprints from Chef +layout: guide-normal +--- + +## Creating Blueprints from Chef + +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.)* + +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 (`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/incubator-brooklyn/blob/4e54debc/docs/guide/yaml/chef/example_yaml/mysql-chef-1.yaml ---------------------------------------------------------------------- diff --git a/docs/guide/yaml/chef/example_yaml/mysql-chef-1.yaml b/docs/guide/yaml/chef/example_yaml/mysql-chef-1.yaml new file mode 100644 index 0000000..bdac530 --- /dev/null +++ b/docs/guide/yaml/chef/example_yaml/mysql-chef-1.yaml @@ -0,0 +1,24 @@ +name: chef-mysql-sample +services: +- type: chef:mysql + + cookbook_urls: + # only needed for chef solo; URL can be local to brooklyn, or github, etc... + mysql: https://github.com/opscode-cookbooks/mysql/archive/v4.0.12.tar.gz + openssl: https://github.com/opscode-cookbooks/openssl/archive/v1.1.0.tar.gz + build-essential: https://github.com/opscode-cookbooks/build-essential/archive/v1.4.4.tar.gz + + launch_run_list: [ "mysql::server" ] + launch_attributes: + mysql: + # these attrs are required by the mysql cookbook under node['mysql'] + server_root_password: p4ssw0rd + server_repl_password: p4ssw0rd + server_debian_password: p4ssw0rd + # many others are attrs are supported by the cookbook and can be passed here... + + # how to determine if the process is running and how to kill it + # (supported options are `service_name` and `pid_file`; normally you should just pick one. + # here we use the pid_file because the service_name varies, mysql on centos, mysqld on ubuntu!) + #service_name: mysqld + pid_file: /var/run/mysqld/mysqld.pid http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/4e54debc/docs/guide/yaml/chef/example_yaml/mysql-chef-2.yaml ---------------------------------------------------------------------- diff --git a/docs/guide/yaml/chef/example_yaml/mysql-chef-2.yaml b/docs/guide/yaml/chef/example_yaml/mysql-chef-2.yaml new file mode 100644 index 0000000..ced2dbe --- /dev/null +++ b/docs/guide/yaml/chef/example_yaml/mysql-chef-2.yaml @@ -0,0 +1,28 @@ +name: chef-mysql-sample +services: +- type: chef:mysql + id: db + + cookbook_urls: + # only needed for chef solo; URL can be local to brooklyn, or github, etc... + mysql: https://github.com/opscode-cookbooks/mysql/archive/v4.0.12.tar.gz + openssl: https://github.com/opscode-cookbooks/openssl/archive/v1.1.0.tar.gz + build-essential: https://github.com/opscode-cookbooks/build-essential/archive/v1.4.4.tar.gz + + launch_run_list: [ "mysql::server" ] + launch_attributes: + mysql: + # these attrs are required by the mysql cookbook under node['mysql'] + server_root_password: $brooklyn:component("db").config("mysql.password") + server_repl_password: $brooklyn:component("db").config("mysql.password") + server_debian_password: $brooklyn:component("db").config("mysql.password") + # many others are attrs are supported by the cookbook and can be passed here... + + # how to determine if the process is running and how to kill it + # (supported options are `service_name` and `pid_file`; normally you should just pick one. + # here we use the pid_file because the service_name varies, mysql on centos, mysqld on ubuntu!) + #service_name: mysqld + pid_file: /var/run/mysqld/mysqld.pid + +brooklyn.config: + mysql.password: p4ssw0rd http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/4e54debc/docs/guide/yaml/chef/index.md ---------------------------------------------------------------------- diff --git a/docs/guide/yaml/chef/index.md b/docs/guide/yaml/chef/index.md new file mode 100644 index 0000000..2f47aa3 --- /dev/null +++ b/docs/guide/yaml/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](creating-yaml.html). + +{% include list-children.html %} http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/4e54debc/docs/guide/yaml/chef/writing-chef.md ---------------------------------------------------------------------- diff --git a/docs/guide/yaml/chef/writing-chef.md b/docs/guide/yaml/chef/writing-chef.md new file mode 100644 index 0000000..3fa9401 --- /dev/null +++ b/docs/guide/yaml/chef/writing-chef.md @@ -0,0 +1,79 @@ +--- +title: Writing Chef for Blueprints +title_in_menu: Writing Chef for Blueprints +layout: guide-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:component('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/incubator-brooklyn/blob/4e54debc/docs/guide/yaml/index.md ---------------------------------------------------------------------- diff --git a/docs/guide/yaml/index.md b/docs/guide/yaml/index.md index 04180b9..848f7ac 100644 --- a/docs/guide/yaml/index.md +++ b/docs/guide/yaml/index.md @@ -6,12 +6,12 @@ children: - setting-locations.md - configuring-vms.md - clusters.md -- bigger-blueprint.md - multiple-services.md - clusters-and-policies.md - custom-entities.md - catalog-maintenance.md - { path: yaml-reference.md, title: YAML Blueprint Reference } +- chef/ --- http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/4e54debc/docs/guide/yaml/mutlitple-services.md ---------------------------------------------------------------------- diff --git a/docs/guide/yaml/mutlitple-services.md b/docs/guide/yaml/mutlitple-services.md index 17e1f04..b5dfe34 100644 --- a/docs/guide/yaml/mutlitple-services.md +++ b/docs/guide/yaml/mutlitple-services.md @@ -4,6 +4,42 @@ layout: guide-normal toc: ../guide_toc.json categories: [use, guide, defining-applications] --- +We've seen the configuration of machines and how to build up clusters. +Now let's return to our app-server example and explore how more interesting +services can be configured, composed, and combined. + +Also note there are some good overview materials [here]({{site.path.guide}}//use/guide/defining-applications/basic-concepts.html) +covering clusters, sensors, effectors and more, +if you're the kind of person who likes to learn more about concepts before seeing them in action. + + +### Service Configuration + +We'll begin by using more key-value pairs to configure the JBoss server to run a real app: + +{% highlight yaml %} +{% readj example_yaml/appserver-configured.yaml %} +{% endhighlight %} + +(As before, you'll need to add the `location` info; `localhost` will work for these and subsequent examples.) + +When this is deployed, you can see management information in the Brooklyn Web Console, +including a link to the deployed application (downloaded to the target machine from the `hello-world` URL), +running on port 8080. + +**Top tip**: If port 8080 might be in use, you can specify `8080+` to take the first available port >= 8080; +the actual port will be reported as a sensor by Brooklyn. + +It's also worth indicating an alternate, more formal syntax. +Not all configuration on entities is supported at the top level of the service specification +(only those which are defined as "flags" in the underlying blueprint, +e.g. the `@SetFromFlag("war")` in the `WebAppServiceConstants` parent of `JBoss7Server`). +All configuration has a formal qualified name, and this can be supplied even where flags or config keys are not +explicitly defined, by placing it into a `brooklyn.config` section: + +{% highlight yaml %} +{% readj example_yaml/appserver-configured-in-config.yaml %} +{% endhighlight %} If you explored the `hello-world-sql` application we just deployed, you'll have noticed it tries to access a database. http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/4e54debc/docs/website/index.md ---------------------------------------------------------------------- diff --git a/docs/website/index.md b/docs/website/index.md index da0478b..dac0968 100644 --- a/docs/website/index.md +++ b/docs/website/index.md @@ -5,7 +5,7 @@ landing: true children: - learnmore/ - { path: download/, menu: null } -- { path: /guide/start/blueprints.md, title: Get Started } +- { path: /guide/start/running.md, title: Get Started } - path: documentation/ menu: - { path: /guide/index.md, title_in_menu: "User Guide",