[chef] Re: Re: New user feedback and questions

[Brian Candler < >]

On Mon, Sep 07, 2009 at 11:12:02AM -0700, Adam Jacob wrote:
> > Now I see these as just a series of actions with parameters which are
> > executed one after the other, not tasks to be deferred. Therefore the 
> > issues
> > about ordering of actions vanish: if you want action A to be executed 
> > before
> > action B, you just write A before B :-)
> 
> The tricky part is, they *are* being executed later.  When you write:
> 
> service "apache" do
>   action :enable
> end
> 
> You are creating a new resource, and adding it to the
> ResourceCollection.

OK - and at the end, the ResourceCollection is executed in order.

This makes sense. You don't want to start executing potentially destructive
actions, only to find part way through that something is missing a
parameter, say.

> Also, when you are in the block you are executing code in the context
> of an instance of the resource class - which means you can insert any
> arbitrary code you might want in there. (And people do - for example,
> using a case statement to set an attribute to two different values.)

Although of course you can insert arbitrary code in a normal method call
with parameters, e.g.

   foo "bar",
      :attr => (case wibble
                when 1
                  "baz"
                end),

or

   myattr = ...
   foo "bar", :attr => myattr

Arguably less pretty though.

> Have any suggestions on where in the documentation we should insert
> some more knowledge for folks?

I think at "Cooking School":
http://wiki.opscode.com/display/chef/Cooking+with+Chef
or else under "Cookbooks".

Some of this info already exists under "Recipes", like the fact that
resources are executed in order - it would be good to make it more explicit
at this point, just as you described above (i.e. resources are created,
setup using the block, added to a collection, and then the collection is
executed in sequence).

However by the time you get here you've already drilled down to a pretty low
level, and the tree is quite wide, so it's very easy to miss this:

                                         +- attributes
                     +- nodes            +- definitions
                     +- roles            +- files
                     +- cookbooks -------+ 
Cooking with Chef ---+                   +- libraries
                     +- resources        +- recipes **!here!
                     +- providers        +- templates
                     +- search indexes   +- metadata

So I think an overview document which explains how recipes are parsed and
run would be useful. Also including some info from and/or link to "Anatomy
of a Chef Run", which isn't in this subtree at all.

I think that the "recipe" is the level at which most people will start
working and hence need to understand what's happening: at first they'll use
existing resources and providers, and won't need to deal with nodes, roles,
definitions etc. At least, that's how it was for me.

I'm still not clear exactly how "attributes" and "recipes" are parsed and
run, since it's clear that setting an attribute can affect a recipe, but
also the examples show how attributes can add recipes to the collection (is
the collection empty at this point, which means these recipes will be
executed first, or has it already been parsed?) That would also be useful to
include.

Since the concepts of "attributes" and "recipes" are defined under
"cookbooks", then perhaps "cookbooks" is the right place to describe how
these elements interact with each other.

> > (Right now I'm just using chef solo rather than a server)
> 
> So the above does not apply. :)

Sure, I was just trying to avoid the "why don't you try it and see?" answer.
I need to set up a VM test environment for this, as I'm a bit scared of the
amount of changes it appears chef server will make to my system by
bootstrapping itself.

> We've been working on ways to let you write real integration tests,
> which would go a long way towards allowing you to do real testing in a
> VM.  As it stands, the best practice is to have a staging environment
> that gets your new changes first, and only prop changes to production
> when you are comfortable.

OK, that was the conclusion I was coming to anyway.

Many thanks for your prompt and detailed answers.

Regards,

Brian.