brooklyn-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From aleds...@apache.org
Subject [1/2] git commit: User guide: update to the Chef blueprint chapter
Date Wed, 01 Oct 2014 16:38:12 GMT
Repository: incubator-brooklyn
Updated Branches:
  refs/heads/master 3ef6e256f -> c2b56d756


User guide: update to the Chef blueprint chapter


Project: http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/repo
Commit: http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/commit/298cec64
Tree: http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/tree/298cec64
Diff: http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/diff/298cec64

Branch: refs/heads/master
Commit: 298cec64a7fcea0cbf0956885b7b5f76f810ac6e
Parents: 6fa0d22
Author: Richard Downer <richard@apache.org>
Authored: Wed Oct 1 10:46:17 2014 +0100
Committer: Richard Downer <richard@apache.org>
Committed: Wed Oct 1 17:12:19 2014 +0100

----------------------------------------------------------------------
 docs/use/guide/defining-applications/Chef.png   | Bin 0 -> 36222 bytes
 .../defining-applications/chef-blueprints.md    |  76 ++++++++++++++-----
 2 files changed, 59 insertions(+), 17 deletions(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/298cec64/docs/use/guide/defining-applications/Chef.png
----------------------------------------------------------------------
diff --git a/docs/use/guide/defining-applications/Chef.png b/docs/use/guide/defining-applications/Chef.png
new file mode 100644
index 0000000..d899de2
Binary files /dev/null and b/docs/use/guide/defining-applications/Chef.png differ

http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/298cec64/docs/use/guide/defining-applications/chef-blueprints.md
----------------------------------------------------------------------
diff --git a/docs/use/guide/defining-applications/chef-blueprints.md b/docs/use/guide/defining-applications/chef-blueprints.md
index fb7c380..7d34dd0 100644
--- a/docs/use/guide/defining-applications/chef-blueprints.md
+++ b/docs/use/guide/defining-applications/chef-blueprints.md
@@ -13,6 +13,52 @@ A plan for the full integration is online [here](https://docs.google.com/a/cloud
 This guide assumes you are familiar with the basics of [creating YAML blueprints](creating-yaml.html).
 
 
+## 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.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.
+
+
 ## Creating Blueprints from Chef
 
 In a nutshell, a new Chef-based entity can be defined as a service by specifying
@@ -139,37 +185,33 @@ which make blueprints literally as simple as:
   `node['brooklyn']['config']['mysql_password']`, you can dispense with the `launch_attributes`
section.
 
 
-### Using Chef Server
+## 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:
 
-* **Option 1: Knife Shell Environment**
+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!
 
-  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`.)
+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).
 
-* **Option 2: Configuring Knife**
+If you want to specify a different configuration, there are a number of config keys you can
use:
 
-  If `knife` is not configured by default, or 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
+* `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
+## Tips and Tricks
 
 To help you on your way writing Chef blueprints, here are a handful of pointers
 particularly useful in this context:


Mime
View raw message