Skip to content
Permalink
Browse files
User guide: update to the Chef blueprint chapter
  • Loading branch information
rdowner committed Oct 1, 2014
1 parent 47305b2 commit cebcf56b6ba4eccccd95c4b4054ed93e400a5ab8
Show file tree
Hide file tree
Showing 2 changed files with 59 additions and 17 deletions.
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
@@ -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:

0 comments on commit cebcf56

Please sign in to comment.